Veskslop-t/docs/daemon.md

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.

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

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

{ "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.
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.