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, response policy	Implemented
poc/src/communication.ts	Pure log, parser, and context logic	Implemented
poc/src/message-cache.ts	Channel message cache in a tmp folder	Implemented
poc/src/action-log.ts	Persistent JSONL action log with rotation	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/test-cache.ts	Unit tests for the message cache	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_voice_state	Which voice channel a user is in and who else is there.
get_message_log	Read the trigger log.
get_action_log	Read the persistent action log.
run_commands	Run several read-only tools in one call, in order.
get_context	Assemble conversation context for a channel. Fetches new messages by default.
get_puppet_config	Read the response policy and context settings.
set_puppet_config	Change the response policy and context settings.
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
pnpm test:cache

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

Settings and paths

Setting	Default	Purpose
VESKSLOP_SOCKET	$XDG_RUNTIME_DIR/vesktop-puppet.sock	Core bridge socket
VESKSLOP_STATE_FILE	poc/.veskslop-state.json	Owner, trust list, and config
VESKSLOP_ACTION_LOG	<state dir>/actions.jsonl	Persistent action log
VESKSLOP_ACTION_LOG_MAX_BYTES	5 MiB	Action log rotation limit
VESKSLOP_CACHE_DIR	<tmp>/veskslop-cache	Context cache folder
VESKSLOP_CACHE_MAX_BYTES	50 MiB	Context cache size limit
MCP_HOST / MCP_PORT	127.0.0.1 / 8788	MCP listen address

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.