Veskslop-t/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, CURRENT.md, and TODO.md.

CURRENT.md tracks the work state: the current focus, the completed work, the current task, and the next steps. TODO.md holds the ordered backlog. Read both before you start. Update CURRENT.md before you stop.

• architecture.md — system parts and boundaries
• core-bridge.md — the Vesktop-side capability layer
• daemon.md — the external MCP daemon
• webui.md — the web control UI and its JSON API
• voice.md — voice state reads, planned actions, and lifecycle
• 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 sends the first action of a burst in 30-200 ms, then spaces sends 500-2800 ms. A burst resets after a random 5-20 s of quiet. 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.
• Triggers come from trusted users only: one-to-one DMs and direct mentions.
• 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	Implemented
Daemon on the core-bridge transport	Implemented and verified live
QR login, pacing, trigger log	Implemented
Human pacing (fast first send, burst, variable reset)	Implemented
Trusted-only triggers, trust tiers	Implemented
Context cache, fetch cooldown, continuation	Implemented
Response policy (channel or DM)	Implemented
Chat commands (whitelist)	Implemented. poll is paused.
Persistent action log	Implemented
Web UI and JSON API	Nocturne 7a debug shell + roadmap placeholders. Server-side prefs. No auth; LAN or Tailscale only.
Core process control and web QR login	Implemented. Core start/stop verified live.
User search (cache and guild members)	Implemented
Voice state read and VOICE_STATE_UPDATE events	Implemented
Voice actions (voice.join, voice.leave, voice.move)	Implemented. Auto-leave and stay @user pending.
Voice audio (TTS, virtual mic, ducking, browser monitor)	Implemented. Microphone puppeting pending.
Audio capture and transcript (VAD, WAV, STT hook, live events)	Implemented. STT provider not chosen.
Voice video	Not started. Plan in docs/voice.md.
Notification parsing	Not started
Auth persistence in the core	Implemented and verified live
CDP transport	Kept as a development fallback

Work items

See CURRENT.md and TODO.md for the live list. The main items are:

1. Voice auto-leave and the stay @user command, then live-verify join/leave and audio.
2. Notification parsing: edits, deletes, reactions, and replies.
3. Reply-to-puppet as a trigger.
4. Per-user rate limit and command cooldowns.
5. Collector account with read-only voice membership.

Paused: the poll command and the setup command flow. Parked: MCP event delivery and the LLM attachment. Open decisions wait in CURRENT.md → Open discussions.

Resume checklist

1. Read CURRENT.md and TODO.md.
2. Check the git remote. Work on veskslop-t while the original repo is broken.
3. Run pnpm install and pnpm testTypes at the repo root. Run pnpm build to compile.
4. In poc/: run pnpm check, pnpm test:comm, and pnpm test:cache.
5. Run the mock end-to-end: pnpm control:mock, pnpm control:bridge, pnpm test:trigger.
6. Follow docs/testing.md for the live client test.

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