121 lines
5.0 KiB
Markdown
121 lines
5.0 KiB
Markdown
# Daemon
|
|
|
|
The daemon runs outside Vesktop. It holds all logic. It talks to the core bridge and exposes MCP.
|
|
|
|
## Files
|
|
|
|
| File | Role | Status |
|
|
| --- | --- | --- |
|
|
| `poc/src/control-bridge.ts` | MCP server, tool list, health endpoint | Implemented |
|
|
| `poc/src/puppet.ts` | Trust list, command handling, trigger log, response policy | Implemented |
|
|
| `poc/src/communication.ts` | Pure log, parser, and context logic | Implemented |
|
|
| `poc/src/message-cache.ts` | Channel message cache in a tmp folder | Implemented |
|
|
| `poc/src/action-log.ts` | Persistent JSONL action log with rotation | Implemented |
|
|
| `poc/src/pacing.ts` | Paced queue and query coalescing | Implemented |
|
|
| `poc/src/core-client.ts` | Client actions over the core bridge | Implemented (primary transport) |
|
|
| `poc/src/cdp-client.ts` | Chrome DevTools Protocol client | Development fallback |
|
|
| `poc/src/qr-login.ts` | Terminal QR login | Implemented and verified |
|
|
| `poc/src/test-communication.ts` | Unit tests for the pure logic | Implemented |
|
|
| `poc/src/test-cache.ts` | Unit tests for the message cache | Implemented |
|
|
| `poc/src/mock-core.ts` | Mock core bridge for daemon tests | Implemented |
|
|
| `poc/src/test-trigger.ts` | Inject a trigger event into the mock core | Implemented |
|
|
| `poc/src/cdp-probe.ts` | CDP feasibility probe | Development tool |
|
|
| `poc/src/cdp-dispatch.ts` | Run one CDP expression in the client | Development tool |
|
|
|
|
## Transport
|
|
|
|
The primary transport is the validated core bridge. The daemon connects to
|
|
`vesktop-puppet.sock`. All actions go through the validated capability layer. See
|
|
[core-bridge.md](core-bridge.md).
|
|
|
|
The CDP transport is a development fallback. It needs no Vesktop patch. It evaluates raw code in
|
|
the page, so it has no core-side guardrails. Use it for debugging only.
|
|
|
|
## Pacing
|
|
|
|
The daemon paces all commands. The policy is a random delay of 500 to 2800 ms. The queue
|
|
serializes the commands. The queue coalesces identical concurrent reads. The daemon also prefers
|
|
cached state over queries.
|
|
|
|
The core adds a second, hard rate limit. See [core-bridge.md](core-bridge.md).
|
|
|
|
## MCP tools
|
|
|
|
The daemon exposes MCP over Streamable HTTP. The default address is `http://127.0.0.1:8788/mcp`.
|
|
|
|
| Tool | Purpose |
|
|
| --- | --- |
|
|
| `get_state` | List the user, the guilds, and the channels. |
|
|
| `send_message` | Send a message to a channel. |
|
|
| `read_messages` | Read cached messages from a channel. |
|
|
| `send_dm` | Send a DM to a user. |
|
|
| `get_voice_state` | Which voice channel a user is in and who else is there. |
|
|
| `get_message_log` | Read the trigger log. |
|
|
| `get_action_log` | Read the persistent action log. |
|
|
| `run_commands` | Run several read-only tools in one call, in order. |
|
|
| `get_context` | Assemble conversation context for a channel. Fetches new messages by default. |
|
|
| `get_puppet_config` | Read the response policy and context settings. |
|
|
| `set_puppet_config` | Change the response policy and context settings. |
|
|
| `whitelist_list` | List the owner and the trusted users. |
|
|
| `whitelist_add` | Add users to the trust list. |
|
|
| `whitelist_remove` | Remove users from the trust list. |
|
|
|
|
## Run commands
|
|
|
|
```sh
|
|
# Start the daemon. It connects to the core bridge.
|
|
pnpm control:bridge
|
|
|
|
# Start a mock core for tests without Electron.
|
|
VESKSLOP_SOCKET=/tmp/vesktop-puppet-mock.sock pnpm control:mock
|
|
|
|
# Inject a trigger event into the mock core.
|
|
VESKSLOP_SOCKET=/tmp/vesktop-puppet-mock.sock pnpm test:trigger
|
|
|
|
# Send one test DM. The only permitted live target is zzib.
|
|
pnpm poc:dm
|
|
|
|
# Run the pure-logic unit tests.
|
|
pnpm test:comm
|
|
pnpm test:cache
|
|
|
|
# Development tools for the CDP fallback.
|
|
pnpm cdp:probe
|
|
CDP_EXPRESSION='...' pnpm cdp:dispatch
|
|
```
|
|
|
|
## Health endpoint
|
|
|
|
`GET /health` returns the CDP state, the owner ID, and the query count.
|
|
|
|
```json
|
|
{ "ok": true, "cdpConnected": true, "ownerId": "177117296140091393", "queries": 4 }
|
|
```
|
|
|
|
## Settings and paths
|
|
|
|
| Setting | Default | Purpose |
|
|
| --- | --- | --- |
|
|
| `VESKSLOP_SOCKET` | `$XDG_RUNTIME_DIR/vesktop-puppet.sock` | Core bridge socket |
|
|
| `VESKSLOP_STATE_FILE` | `poc/.veskslop-state.json` | Owner, trust list, and config |
|
|
| `VESKSLOP_ACTION_LOG` | `<state dir>/actions.jsonl` | Persistent action log |
|
|
| `VESKSLOP_ACTION_LOG_MAX_BYTES` | 5 MiB | Action log rotation limit |
|
|
| `VESKSLOP_CACHE_DIR` | `<tmp>/veskslop-cache` | Context cache folder |
|
|
| `VESKSLOP_CACHE_MAX_BYTES` | 50 MiB | Context cache size limit |
|
|
| `MCP_HOST` / `MCP_PORT` | `127.0.0.1` / `8788` | MCP listen address |
|
|
|
|
## How to add an MCP tool
|
|
|
|
1. Add the action to the core bridge. See [core-bridge.md](core-bridge.md).
|
|
2. Add a `server.registerTool` call in `poc/src/control-bridge.ts`.
|
|
3. Wrap outbound calls in `paced`.
|
|
4. Add a unit test if the tool has local logic.
|
|
5. Run `pnpm check` in `poc/`.
|
|
|
|
## Security notes
|
|
|
|
- The MCP server binds to localhost by default.
|
|
- Remote access must go over LAN or Tailscale. Do not expose the daemon to the public internet.
|
|
- The daemon holds no Discord credentials. The client holds the session.
|
|
- The daemon token file is separate from the client session. See [auth.md](auth.md).
|