Rework core integration: validated capability layer, docs, and session state

2026-09-11 14:09:04 +02:00
parent 2a15f057df
commit e62d3007d8
33 changed files with 1897 additions and 612 deletions
@@ -0,0 +1,93 @@
+# 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).