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
• media.md — media archive: command, storage, limits, and Web UI
• media-scraper.md — the scrape engine: backends, walk, pacing, schema
• media-mcp.md — the media MCP tool surface
• slopbot.md — the dedicated bot core for media scraping
• 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.
• TTS lives in microslopsam/ (merged from the standalone SAM engine project, including the vendored binaries: they are hard to acquire and small enough to track). Before changing anything TTS, read TTS-DESIGN.md and microslopsam/docs/TTS-DESIGN.md, confirm the in-repo copy is current, and run sh microslopsam/setup/test-wrapper.sh. The daemon's engine points at microslopsam/setup/veskslop-tts.sh; nothing may reference an external SAM checkout.
• 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.
• Never commit media-scrape/db/, scrape databases, downloaded media, or the slopbot token.
• Owner interjections become TODO.md items unless marked "add this now". Add the item, then continue the current task.
• No sudo. Record apt or system-level installs in TODO.md; the owner runs them.
• 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. Mobile first draft (four tabs).
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 follows the owner. stay @user pending.
Voice audio (TTS, virtual mic, ducking, browser monitor)	Implemented. MicroslopSam engine merged into microslopsam/; VOX/HEV presets, VOX prosody, word mode, and the hum are live. 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 (edits, deletes, reactions, replies)	Implemented
Reply-to-puppet as a trigger	Implemented
Media archive (scrape media, Media/Bot tabs)	Implemented: walk, download, previews, per-chat backfill queue, filters, tunables. Checkpoints in CURRENT.md.
Slopbot (dedicated bot core for scraping)	Implemented and live-verified. Checkpoints in CURRENT.md.
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. Live-verify join/leave and audio on the real client.
2. Wire daemon task push for the local agent (agent/, Go + Eino); commands stay in the daemon, free-form triggers go to the agent.
3. Per-user rate limit and command cooldowns.
4. Collector account with read-only voice membership.
5. Remote agent MCP path: notification tools and a documented LAN/Tailscale bind.
6. Media archive (media-scrape/, slopbot): work the checkpoints in CURRENT.md and push the branch after each one.

Paused: the poll command and the setup command flow. 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. Push and auth details are in GITEA.md (repo root, gitignored; never commit it).
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
pnpm test:ui          # optional browser smoke test for the Media tab
pnpm verify:scrapes   # scrape completeness report (exit 1 when a scrape looks truncated)

pnpm test:ui is optional. It needs a running daemon with media data and a Chromium: set PW_CHROMIUM to a binary, or keep one in the Playwright cache (~/.cache/ms-playwright). playwright-core is an optional dependency, so a missing browser never blocks the other tests. VESKSLOP_UI_URL overrides the default https://127.0.0.1:8789/. It opens the Media tab, loads tiles, applies the cached-only filter, checks the zoom slider and Reset, and fails on console errors or broken images. See docs/testing.md.