Veskslop/AGENTS.md

AGENTS.md — Veskslop

Veskslop controls Discord user accounts without a visible client window. It runs the real Vesktop client and drives it through a small, validated capability layer. All logic lives in the external daemon.

Read the docs first: docs/INDEX.md and CURRENT.md.

CURRENT.md tracks the work state: the current focus, the completed work, the current task, and the next steps. Read it before you start. Update it before you stop.

• architecture.md — system parts and boundaries
• core-bridge.md — the Vesktop-side capability layer
• daemon.md — the external MCP daemon
• communication.md — trust model, commands, trigger log
• auth.md — QR login and token persistence
• testing.md — tests and live test setup
• decisions.md — design decisions

Locked decisions

• Use the real Vesktop client. Do not use selfbot protocol libraries. Most are archived, and stale protocol emulation is a ban risk.
• The core validates. The daemon requests. The core rejects bad input with a structured error. The client must not crash, and the daemon must not send malformed data to Discord.
• Keep core patches isolated. Add actions in src/renderer/puppet/ and the bridge in src/main/puppetBridge.ts. Do not spread logic through upstream files.
• The daemon holds the logic: triggers, trust list, command parsing, trigger log, and pacing.
• The daemon binds to localhost. Remote access goes over LAN or Tailscale only.
• Pacing: the daemon delays every command by 500 to 2800 ms. The core adds a hard limit of 500 ms between sends and 30 sends per minute.

Guardrails

• Never commit tokens, credentials, or .env files.
• Do not hardcode Discord limits from memory. Make the limits configurable.
• All outbound actions go through the paced queue.
• Test with throwaway accounts and private test guilds only.
• Live send tests: only DMs to user zzib (177117296140091393).
• Run pnpm testTypes and pnpm lint before you report done. Run pnpm build to compile.

Status

Area	Status
Action protocol and renderer actions	Implemented
Main bridge, event push, hooks	Pending
Daemon on the CDP transport	Implemented and verified live
Daemon on the core-bridge transport	Pending
QR login, pacing, trigger log	Implemented
Auth persistence in the core	Verified, then removed during the CDP pivot. To re-add.
Voice, audio, video	Not started

Work items

See the todo list in the current session. The main items are:

1. Wire the core bridge: events.ts, index.ts, puppetBridge.ts, and the upstream hooks.
2. Re-add auth persistence: pinned DATA_DIR, token file, preload seeding, VESKSLOP_HEADLESS.
3. Move the daemon to the core-bridge transport.
4. Add a mock core for tests.
5. Later: voice actions, audio, video, fetch-based read, client lightening, web debug UI.

Dev commands

pnpm install
pnpm build        # esbuild bundle into dist/
pnpm testTypes    # tsc --noEmit
pnpm lint

cd poc
pnpm check        # type check the daemon
pnpm test:comm    # unit tests