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](docs/INDEX.md), [CURRENT.md](CURRENT.md), and
[TODO.md](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](docs/architecture.md) — system parts and boundaries
- [core-bridge.md](docs/core-bridge.md) — the Vesktop-side capability layer
- [daemon.md](docs/daemon.md) — the external MCP daemon
- [webui.md](docs/webui.md) — the web control UI and its JSON API
- [voice.md](docs/voice.md) — voice state reads, planned actions, and lifecycle
- [media.md](docs/media.md) — media archive: command, storage, limits, and Web UI
- [media-scraper.md](docs/media-scraper.md) — the scrape engine: backends, walk, pacing, schema
- [media-mcp.md](docs/media-mcp.md) — the media MCP tool surface
- [slopbot.md](docs/slopbot.md) — the dedicated bot core for media scraping
- [communication.md](docs/communication.md) — trust model, commands, trigger log
- [auth.md](docs/auth.md) — QR login and token persistence
- [testing.md](docs/testing.md) — tests and live test setup
- [decisions.md](docs/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.
- 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. 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](docs/voice.md). |
| Notification parsing (edits, deletes, reactions, replies) | Implemented |
| Reply-to-puppet as a trigger | Implemented |
| Media archive (`scrape media`, Media/Bot tabs) | Design approved 2026-09-16. Checkpoints in [CURRENT.md](CURRENT.md). |
| Slopbot (dedicated bot core for scraping) | Design approved 2026-09-16. Checkpoints in [CURRENT.md](CURRENT.md). |
| Auth persistence in the core | Implemented and verified live |
| CDP transport | Kept as a development fallback |

## Work items

See [CURRENT.md](CURRENT.md) and [TODO.md](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](CURRENT.md) and
   push the branch after each one.

Paused: the `poll` command and the setup command flow. Open decisions wait in
[CURRENT.md](CURRENT.md) → Open discussions.

## Resume checklist

1. Read [CURRENT.md](CURRENT.md) and [TODO.md](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](docs/testing.md) for the live client test.

## Dev commands

```sh
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 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](docs/testing.md).