94 lines
3.5 KiB
Markdown
94 lines
3.5 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 on CDP |
|
|
| `poc/src/puppet.ts` | Trust list, command handling, trigger log | Implemented |
|
|
| `poc/src/communication.ts` | Pure log and parser logic | Implemented |
|
|
| `poc/src/pacing.ts` | Paced queue and query coalescing | Implemented |
|
|
| `poc/src/cdp-client.ts` | Chrome DevTools Protocol client | Implemented (current transport) |
|
|
| `poc/src/discord.ts` | Client actions over CDP | Implemented (current transport) |
|
|
| `poc/src/core-client.ts` | Client actions over the core bridge | Pending (target transport) |
|
|
| `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/cdp-probe.ts` | CDP feasibility probe | Implemented (dev tool) |
|
|
|
|
## Transport
|
|
|
|
The daemon supports two transports.
|
|
|
|
1. **CDP (current)** — the daemon starts Vesktop with `--remote-debugging-port=9222`. The daemon
|
|
connects to the Discord page target. It evaluates the action code in the page and receives
|
|
events through a CDP binding. This transport needs no Vesktop patch. The project used it to
|
|
prove the concept and to test the client.
|
|
2. **Core bridge (target)** — the daemon connects to `vesktop-puppet.sock`. All actions go through
|
|
the validated capability layer. This transport gives the core-side guardrails.
|
|
|
|
The daemon logic is the same on both transports. Only the client class changes.
|
|
|
|
## 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_message_log` | Read the trigger log. |
|
|
| `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 client on CDP port 9222.
|
|
pnpm control:bridge
|
|
|
|
# Send one test DM. The only permitted live target is zzib.
|
|
pnpm poc:dm
|
|
|
|
# Run the pure-logic unit tests.
|
|
pnpm test:comm
|
|
|
|
# Probe CDP access and events.
|
|
pnpm cdp:probe
|
|
```
|
|
|
|
## Health endpoint
|
|
|
|
`GET /health` returns the CDP state, the owner ID, and the query count.
|
|
|
|
```json
|
|
{ "ok": true, "cdpConnected": true, "ownerId": "177117296140091393", "queries": 4 }
|
|
```
|
|
|
|
## 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).
|