README: reflect the live text layer, real tools, and true roadmap

2026-09-11 16:13:02 +02:00
parent af6e553df3
commit 6fd77ca88d
1 changed files with 81 additions and 71 deletions
@@ -36,20 +36,20 @@

 ## 🚀 What is Veskslop

-Veskslop takes the beloved Vesktop base and surgically removes the part where a person has to click things. What remains is a **headless Discord client**: a daemon that speaks Discord natively, exposes itself as a **proxy**, and lets an **AI agent drive a real Discord account** over **MCP** — while you pipe **audio in**, pipe **audio out**, and shove **live video streams** down its throat.
+Veskslop takes the beloved Vesktop base and deletes the part where a person has to click things. What remains is a **headless Discord client** driven through a **validated capability layer**, so an **AI agent can run a real Discord account over MCP**. Text automation works today. Audio pipes and video streams are the next descent into madness.

 It is Discord, but as infrastructure. It is the account you already have, plus `curl`, minus dignity.

 Think of it as:

 - 🖥️ **A Discord client with the client removed.** Runs on a server, in a container, on a Raspberry Pi, in your weird home lab, wherever.
- 🔀 **A proxy.** Messages, events, voice state, attachments — everything is forwarded, interceptable, scriptable, and API-shaped.
- 🧠 **An agent body.** Your MCP-capable AI gets a real account with real permissions and real consequences.
- 🔊 **An audio router.** Play anything into voice. Capture anything out. TTS in, STT out, pipes for days.
- 📹 **A streaming endpoint.** Push files, cameras, generative visuals, or pure slop into a voice channel.
+- 🧠 **An agent body (text tools live).** Your MCP-capable AI gets a real account with real permissions and real consequences.
+- 🔀 **A proxy (planned).** Messages, events, voice state, attachments — everything forwarded, interceptable, scriptable, and API-shaped.
+- 🔊 **An audio router (planned).** Play anything into voice. Capture anything out. TTS in, STT out, pipes for days.
+- 📹 **A streaming endpoint (planned).** Push files, cameras, generative visuals, or pure slop into a voice channel.
 - 🧪 **A science experiment that will absolutely not get your account banned** *(allegedly)*.

-> **Status: pre-alpha.** The repo currently carries the Vesktop base + global shortcut work. The headless core is being carved out. Everything below is the target architecture — some of it works, some of it is a promise, all of it is the vision.
+> **Status: text layer works.** The real Vesktop client runs headless and is driven through a validated capability layer. Triggers, trust tiers, conversation context, response policy, polls, persistent logging, and MCP tools are live. Voice actions, audio, and video are still the vision. The design docs live in [docs/INDEX.md](docs/INDEX.md).

 ## 🗿 Why though

@@ -67,32 +67,29 @@ Real reasons people actually want this:

 Veskslop ships an **MCP server** so any MCP-capable agent (Claude, GPT-based agents, your local Llama abomination, a cron job with delusions of grandeur) can operate the account through structured tool calls.

-**Planned tool surface** (names may change, vibes will not):
+**Live tool surface** (names may change, vibes will not):

 | Tool | Description |
 | --- | --- |
-| `discord_send_message` | Send a message to a channel, thread, or DM. |
-| `discord_read_messages` | Read recent messages, with filters, pagination, and search. |
-| `discord_list_guilds` | List guilds, channels, threads, and their IDs. |
-| `discord_react` | Add or remove reactions. |
-| `discord_edit_message` | Edit a message the account sent. |
-| `discord_delete_message` | Delete a message the account sent. |
-| `discord_upload_file` | Upload attachments with optional captions. |
-| `discord_join_voice` | Join a voice channel and stay there like a loyal appliance. |
-| `discord_leave_voice` | Leave the voice channel. Deeply emotional. |
-| `discord_play_audio` | Pipe an audio source into the voice channel. |
-| `discord_capture_audio` | Capture per-user audio out of the voice channel. |
-| `discord_start_stream` | Start a video stream in the current voice channel. |
-| `discord_stop_stream` | Stop the stream. |
-| `discord_set_presence` | Status, activity, custom status. Look busy. |
-| `discord_set_voice_state` | Mute, deafen, self-mute, self-deafen. |
-| `discord_get_state` | Snapshot of the account, gateway, and pipelines. |
+| `get_state` | User, guilds, and channels. Cache-only, zero queries. |
+| `get_voice_state` | Which voice channel a user is in and who else is suffering there. |
+| `send_message` | Send a message as the account. Query-paced. |
+| `read_messages` | Read the client's message cache. |
+| `send_dm` | Slide into someone's DMs. |
+| `get_context` | Recent conversation context for a channel. Fetches new messages only. |
+| `get_message_log` | Trigger log: trusted entries and a reserved untrusted buffer. |
+| `get_action_log` | Durable audit trail: triggers, commands, replies, errors. |
+| `get_puppet_config` / `set_puppet_config` | Response policy, context limits, poll duration. |
+| `whitelist_list` / `whitelist_add` / `whitelist_remove` | Trust tiers: user, trusted, admin. |
+| `run_commands` | Run several read-only tools in one call. |

-Every tool is designed to be **safe by default**: explicit opt-in for destructive actions, rate-limit awareness, and a sandbox mode that logs instead of sends.
+**Planned**: voice join/leave, audio play/capture, video streams, message edit/delete/upload, presence and voice state control.

-## 🔀 Proxy mode
+Every action is **safe by default**: strict input validation in the client, structured errors, a hard outbound rate limit, and paced sends. A buggy agent cannot crash the client or spam Discord.

-Veskslop is also a **proxy layer** in front of Discord:
+## 🔀 Proxy mode (planned)
+
+Veskslop is also meant to be a **proxy layer** in front of Discord:

 - **REST passthrough** with authentication handled once.
 - **Gateway event bus** — every event is consumable by local code, webhooks, or other processes.
@@ -107,7 +104,7 @@ your app / agent / script ──▶ Veskslop proxy ──▶ Discord
                                └─ event bus ──▶ subscribers
 ```

-## 🔊 Audio pipes
+## 🔊 Audio pipes (planned)

 Voice is a first-class citizen, not an afterthought duct-taped on at 3am.

@@ -127,7 +124,7 @@ voice channel ──▶ per-user decode ──▶ mix ──▶ PCM/file/STT ─
 <img src="docs/images/veskslop-audio.png" alt="Veskslop audio pipeline" width="80%" />
 <br />

-## 📹 Video streams
+## 📹 Video streams (planned)

 Send video where Discord expects a camera:

@@ -144,71 +141,82 @@ veskslop stream start --guild 123 --channel 456 --source ./slop.mp4 --loop
 ## 🏗️ Architecture

 ```txt
-┌─────────────────────────────────────────────────────────────────┐
+┌─────────────────────────────────────────────────────┐
 │                     MCP CLIENTS                     │
-│         Claude · GPT agents · local models · scripts            │
-└───────────────────────────────┬─────────────────────────────────┘
-                                │ MCP (stdio / HTTP)
-┌───────────────────────────────▼─────────────────────────────────┐
-│                         VESKSLOP CORE                           │
-│   tool server · session daemon · account state · rate guard     │
-│   policy engine · audit log · event bus · config                │
-└───────┬───────────────────┬────────────────────┬────────────────┘
-        │                   │                    │
-┌───────▼───────┐   ┌───────▼────────┐   ┌───────▼──────────┐
-│  Discord API  │   │ Audio pipeline │   │ Video pipeline   │
-│  REST + WSS   │   │ Opus / WebRTC  │   │ encode / stream  │
-└───────────────┘   └────────────────┘   └──────────────────┘
+│          Claude · agents · scripts · cron           │
+└──────────────────────────┬──────────────────────────┘
+                           │ Streamable HTTP (localhost)
+┌──────────────────────────▼──────────────────────────┐
+│                   VESKSLOP DAEMON                   │
+│   triggers · trust · context · response policy      │
+│   action log · pacing · MCP tool server             │
+└──────────────────────────┬──────────────────────────┘
+                           │ JSON lines over a Unix socket
+┌──────────────────────────▼──────────────────────────┐
+│             VESKTOP CORE (validated actions)        │
+│   state · messages · reactions · voice state        │
+└──────────────────────────┬──────────────────────────┘
+                           │ official client traffic
+┌──────────────────────────▼──────────────────────────┐
+│                      DISCORD                        │
+└─────────────────────────────────────────────────────┘
 ```

+The core exposes a fixed action list with strict validation. All logic lives in the daemon. This
+keeps client patches small and upstream rebases easy. See [docs/core-bridge.md](docs/core-bridge.md).
+
 ## ⚡ Quickstart

-> These commands describe the intended developer flow. The headless daemon is a work in progress; today the repo builds the Vesktop base.
-
 ```sh
-git clone https://git.0xfeedc0de.com/zib/Veskslop.git
-cd Veskslop
+git clone https://git.0xfeedc0de.com/zib/Veskslop-t.git
+cd Veskslop-t

-# dependencies
+# dependencies and build
 pnpm install
-
-# build
 pnpm build

-# run the daemon (planned)
-DISCORD_TOKEN="your-token-here" pnpm vesk slop
+# log in once with a terminal QR code
+cd poc && pnpm poc:qr
+
+# run the client headless (use Xvfb on a server), then the daemon
+pnpm control:bridge
 ```

-Connect an MCP client (Claude Desktop style):
+The daemon speaks **Streamable HTTP MCP** on `http://127.0.0.1:8788/mcp`. Point any MCP client at
+that address, or poke it by hand:

-```json
-{
-    "mcpServers": {
-        "veskslop": {
-            "command": "pnpm",
-            "args": ["vesk", "mcp"],
-            "env": {
-                "DISCORD_TOKEN": "your-token-here"
-            }
-        }
-    }
-}
+```sh
+curl -s http://127.0.0.1:8788/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
 ```

+The full setup, including the headless client and the mock core, is in
+[docs/testing.md](docs/testing.md) and [poc/README.md](poc/README.md).
+
 ## 🗺️ Roadmap

 - [x] Fork Vesktop and keep the good parts
- [x] Global shortcuts / keybinds base
- [ ] Extract a true headless core (no Electron window)
- [ ] Gateway + REST session daemon
- [ ] MCP server with the tool surface above
+- [x] Validated core bridge (fixed actions, strict validation, structured errors)
+- [x] Headless client driven through the core bridge
+- [x] Gateway state, message send/read/fetch, reactions, voice state read
+- [x] Trigger log, trust tiers, conversation context, continuation window
+- [x] Response policy, hard rate limits, persistent action log
+- [x] MCP server with the live text tool surface
+- [x] Reaction polls and chat command help
+- [ ] Notification parsing: edits, deletes, replies, references
+- [ ] Reply-to-puppet as a trigger
+- [ ] Per-user rate limits and command cooldowns
+- [ ] Setup command with reaction-based multiple choice
+- [ ] MCP event delivery (poll, stateful session, or local event stream)
+- [ ] Collector account for voice membership fallback
+- [ ] Voice join/leave and invite-link joins
 - [ ] Outbound audio pipeline
 - [ ] Inbound audio capture pipeline
 - [ ] Video stream pipeline
 - [ ] Proxy mode + event bus
- [ ] Policy engine, audit log, rate limiting
 - [ ] Container image (`veskslop:slop-latest`)
- [ ] Documentation that is not a README
 - [ ] Achieve AGI (stretch goal)

 ## 🧨 Disclaimer
@@ -235,6 +243,8 @@ layer. All logic lives in an external daemon.

 Start here:

+- [CURRENT.md](CURRENT.md) — live session state and how to resume
+- [TODO.md](TODO.md) — the ordered backlog
 - [docs/INDEX.md](docs/INDEX.md) — all design documents
 - [AGENTS.md](AGENTS.md) — rules for agents and contributors
 - [poc/README.md](poc/README.md) — daemon run commands