Add AGENTS.md with project direction and Phase 0 plan

2026-09-11 12:14:02 +02:00
parent 09b8624333
commit 4a10eec56a
1 changed files with 85 additions and 0 deletions
@@ -0,0 +1,85 @@
+# 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
+```