86 lines
4.3 KiB
Markdown
86 lines
4.3 KiB
Markdown
# 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
|
||
```
|