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
• 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.
• 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
Trusted-only triggers, trust tiers	Implemented
Context cache, fetch cooldown, continuation	Implemented
Response policy (channel or DM)	Implemented
Chat commands (poll)	Implemented
Persistent action log	Implemented
Voice state read	Implemented
Voice actions, 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. Notification parsing: edits, deletes, reactions, and replies.
2. Reply-to-puppet as a trigger.
3. Per-user rate limit and command cooldowns.
4. Setup command with reaction-based multiple choice.
5. MCP event delivery decision.
6. Collector account with read-only voice membership.

Open decisions wait in CURRENT.md → Open discussions: MCP event delivery, untrusted logging, the privacy pass, the setup command flow, and the first live reaction check.

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