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

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.

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

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

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