Veskslop-t/docs/architecture.md

Architecture

Purpose

Veskslop controls one or more Discord user accounts without a visible client window. It uses the real Vesktop client, so the traffic comes from the official client.

Parts

The system has five parts:

1. Vesktop core — the real Vesktop client. It runs headless. It exposes a small capability layer.
2. Core bridge — the capability layer. It accepts validated actions and pushes events.
3. Veskslop daemon — the external process. It holds all logic. It exposes MCP.
4. Web UI — a small browser control surface served by the daemon. See webui.md.
5. MCP clients — agents and tools. They call the daemon.

MCP clients (agents)                 Web browser (owner)
        │ Streamable HTTP (MCP)             │ HTTP + SSE
        ▼                                   ▼
Veskslop daemon ◀───────────────────── web UI listener
        │  ──── JSON lines over a Unix socket ────▶  Vesktop core
        │                                                   │
        │ QR login, pacing, trigger log,                    │ validated actions + events
        │ trust list, MCP tools                             ▼
        │                                            Discord (official client traffic)
        ▼
Local state files (.token, .veskslop-state.json)

Boundary rules

The boundary is narrow on purpose.

• The core exposes a fixed action list. The list has no general "run this code" action.
• The core validates every input. Bad input returns a structured error. The client does not crash.
• The core rate limits all outbound actions. A bug in the daemon cannot cause a send flood.
• The daemon holds the logic: triggers, trust list, command parsing, the trigger log, and pacing.
• The daemon holds no Discord protocol code.

These rules keep upstream rebases small. Logic changes do not touch the core. The core changes only when the action list changes.

Components and status

Component	Location	Status
Action protocol	src/shared/puppetProtocol.ts	Implemented
Validated actions	src/renderer/puppet/actions.ts	Implemented
Event push	src/renderer/puppet/events.ts	Implemented
Main bridge	src/main/puppetBridge.ts	Implemented
Core hooks	src/main/main.ts, src/renderer/ipcCommands.ts, src/shared/IpcEvents.ts, src/preload/VesktopNative.ts	Implemented
Daemon (core-bridge transport)	poc/src/core-client.ts	Implemented and verified live
Daemon (CDP transport)	poc/src/cdp-client.ts	Kept as a development fallback
QR login	poc/src/qr-login.ts	Implemented and verified live
Pacing	poc/src/pacing.ts	Implemented
Trigger log and trust list	poc/src/communication.ts, poc/src/puppet.ts	Implemented and verified live
Context cache and response policy	poc/src/message-cache.ts, poc/src/puppet.ts	Implemented and verified with the mock
Chat commands and polls	poc/src/puppet.ts, poc/src/communication.ts	Implemented. Poll is paused (POLL_ENABLED = false).
Persistent action log	poc/src/action-log.ts	Implemented
Web UI and JSON API	poc/src/webui.ts, poc/public/	Nocturne 7a debug shell + roadmap placeholders
User search	src/renderer/puppet/actions.ts (user.search)	Implemented
Voice state reads	src/renderer/puppet/actions.ts, src/renderer/puppet/events.ts	Implemented
Voice actions, audio, video	Not started	Not started

Data flow

1. An agent calls an MCP tool on the daemon.
2. The daemon applies pacing and policy.
3. The daemon sends one JSON-line action to the core bridge.
4. The bridge forwards the action to the renderer.
5. The renderer validates the action and calls the official client.
6. The renderer returns a result or a structured error.
7. The bridge returns the response to the daemon.

For inbound messages, the flow goes the other way:

1. The client receives a gateway event.
2. The renderer normalizes the event.
3. The bridge pushes the event to subscribed daemon connections.
4. The daemon applies the trigger rules and updates the log.