# 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).