# AGENTS.md — Veskslop

## What this is

Veskslop is a **headless Discord client daemon** built on the Vesktop codebase. It turns one or
more **Discord user accounts** into a controllable service:

- an **MCP server** (Streamable HTTP) lets AI agents drive a "puppet" account;
- a second, read-only account can collect stats/data without acting;
- **audio is piped in and out** over PipeWire;
- **video streams** can be pushed into voice channels;
- everything is **local-first**: clients reach it over LAN/Tailscale only.

**Vesktop is a separate project with separate goals.** This repo shares history with it but not
direction. Do not carry Vesktop UI features here unless the daemon needs them.

## Decisions (locked unless the user changes them)

- **Core:** TypeScript on Node with pnpm. `discord.js` for gateway/REST, `@discordjs/voice` for voice.
- **Accounts:** multiple user tokens. Expected setup is one read-only collector account plus one
  full-control puppet account; design for N identities behind one control surface.
- **MCP transport:** Streamable HTTP only (no stdio/SSE unless asked).
- **Network:** bind localhost by default. Remote access is always over LAN/Tailscale — never expose
  to the public internet. A client will later authenticate to the proxy for remote control.
- **Audio:** PipeWire only.
- **GUI:** optional minimal **web debug UI** if it is cheap to build; otherwise keep the existing
  Vesktop Electron build runnable for debugging. The daemon must never require Electron.
- **Pacing/safety:** actions emulate a human using the Vesktop client through a queue:
  - first action is snappy (~30–80 ms delay);
  - subsequent bulk actions get randomized delays (~500–2800 ms);
  - a **risky fast mode** is opt-in and minimizes delays;
  - default capabilities are clamped to free-account limits (upload size, stream resolution, etc.);
  - individual abilities can be toggled off.

## How to proceed

**Phase 0 — PoC, do this first.** Find the smallest end-to-end thing that works, then stop and
report back so the user can choose a direction. Candidate spikes, timeboxed:

1. `discord.js` login + list guilds + send a message from a throwaway test account.
2. Minimal MCP Streamable HTTP server exposing `send_message` / `read_messages`, wired to #1.
3. Join a voice channel and play a local file via `@discordjs/voice` (PipeWire output).

Prefer whichever is quickest to prove; do not build production architecture before the user picks.

**After regrouping:** headless daemon skeleton → multi-account session manager → pacing queue →
MCP tool surface → audio pipelines → video pipeline → remote proxy/auth client → web debug UI.

## Architecture sketch

```
MCP clients (agents) ──Streamable HTTP──▶ Veskslop core ──▶ Discord (user tokens)
remote web client ─────auth over LAN─────▶   │
                                             ├─ action queue (human-emulation pacing)
                                             ├─ capability policy + limits + audit log
                                             ├─ audio pipeline (PipeWire)
                                             └─ video pipeline
```

## Guardrails for agents working here

- **Never commit tokens, credentials, or `.env` files.** Use environment variables / a local secret store.
- Do not hardcode Discord limits from memory — verify current free-tier numbers (upload size, stream
  resolution, rate limits) at implementation time, and keep them configurable.
- All outbound actions go through the pacing queue; no direct sends.
- Default to conservative limits and opt-in risky features.
- Test against throwaway accounts and private test guilds only.
- Run `pnpm testTypes` and `pnpm lint` before calling work done; `pnpm build` to compile.

## Open questions

- Which Phase 0 spike becomes the real foundation? (user decides after the spikes)
- Voice E2EE (DAVE) support status in the current voice stack — research before committing.
- Video pipeline feasibility: required codecs/containers and how to feed synthetic frames.
- Scope and auth model of the future remote proxy client and web debug UI.
- How much of the Vesktop Electron tree gets deleted once the daemon is self-sufficient.

## Dev commands

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