Add AGENTS.md with project direction and Phase 0 plan
This commit is contained in:
agent
@@ -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
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user