From af6e553df36c64d4eb695bc490c53e59f79e8217 Mon Sep 17 00:00:00 2001 From: Fisto Date: Fri, 11 Sep 2026 16:12:09 +0200 Subject: [PATCH] Docs pass: refresh statuses, add resume checklist, poll and log decisions --- AGENTS.md | 9 +++++++++ CURRENT.md | 2 +- docs/INDEX.md | 4 +++- docs/architecture.md | 2 ++ docs/auth.md | 11 ++++------- docs/decisions.md | 20 +++++++++++++++++++- docs/testing.md | 17 +++++++++++++---- poc/README.md | 7 ++++++- 8 files changed, 57 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0754859..d322c58 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,6 +71,15 @@ See [CURRENT.md](CURRENT.md) and [TODO.md](TODO.md) for the live list. The main 5. MCP event delivery decision. 6. Collector account with read-only voice membership. +## Resume checklist + +1. Read [CURRENT.md](CURRENT.md) and [TODO.md](TODO.md). +2. Check the git remote. Work on `veskslop-t` while the original repo is broken. +3. Run `pnpm install` and `pnpm testTypes` at the repo root. Run `pnpm build` to compile. +4. In `poc/`: run `pnpm check`, `pnpm test:comm`, and `pnpm test:cache`. +5. Run the mock end-to-end: `pnpm control:mock`, `pnpm control:bridge`, `pnpm test:trigger`. +6. Follow [docs/testing.md](docs/testing.md) for the live client test. + ## Dev commands ```sh diff --git a/CURRENT.md b/CURRENT.md index b6bb411..8919ab3 100644 --- a/CURRENT.md +++ b/CURRENT.md @@ -11,7 +11,7 @@ persistent logging. Voice, audio, and video stay deferred. ## In progress -- None. The latest text milestone is complete and verified with the mock core. +- None. The documentation pass is complete. The project is ready to resume. ## Done diff --git a/docs/INDEX.md b/docs/INDEX.md index ff1df2b..3ed904b 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -18,6 +18,8 @@ This file lists the project documents. | File | Scope | | --- | --- | -| [../AGENTS.md](../AGENTS.md) | Agent entry point and guardrails | +| [../AGENTS.md](../AGENTS.md) | Agent entry point, guardrails, resume checklist | +| [../CURRENT.md](../CURRENT.md) | Live session state | +| [../TODO.md](../TODO.md) | Ordered backlog | | [../poc/README.md](../poc/README.md) | Spike and daemon run commands | | [../README.md](../README.md) | Project introduction | diff --git a/docs/architecture.md b/docs/architecture.md index ee83a1d..b9e5d74 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -55,6 +55,8 @@ when the action list changes. | Pacing | `poc/src/pacing.ts` | Implemented | | Trigger log and trust list | `poc/src/communication.ts`, `poc/src/puppet.ts` | Implemented and verified live | | Context cache and response policy | `poc/src/message-cache.ts`, `poc/src/puppet.ts` | Implemented and verified with the mock | +| Chat commands and polls | `poc/src/puppet.ts`, `poc/src/communication.ts` | Implemented and verified with the mock | +| Persistent action log | `poc/src/action-log.ts` | Implemented | | Voice, audio, video | Not started | Not started | ## Data flow diff --git a/docs/auth.md b/docs/auth.md index 4aea412..2bd8391 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -53,11 +53,8 @@ can occur. | Part | Status | | --- | --- | -| QR login and token file | Implemented and verified | -| Pinned profile directory | Implemented and verified. Currently out of the tree after the CDP pivot. | -| Token seeding | Implemented and verified. Currently out of the tree after the CDP pivot. | -| Headless first-launch skip | Implemented and verified. Currently out of the tree after the CDP pivot. | +| QR login and token file | Implemented and verified live | +| Pinned profile directory | Implemented and verified live | +| Token seeding | Implemented and verified live | +| Headless first-launch skip | Implemented and verified live | | Devtools patch | Upstream Vesktop code. Keep it. | - -The three out-of-tree parts are small. Add them again with the core bridge, at the same time as the -bridge hooks. diff --git a/docs/decisions.md b/docs/decisions.md index c176d7d..6c1c727 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -30,7 +30,8 @@ the validated core bridge. **Reason.** CDP needs no Vesktop patch. However, CDP evaluates raw code in the page. It bypasses the core-side validation and rate limits. The project keeps the probe as a development tool. -**Status.** The daemon uses CDP at this time. The core-bridge transport is pending. +**Status.** The primary transport is the validated core bridge. The CDP client and the probe stay in +`poc/` as development tools. ## ADR-4: No bespoke client @@ -79,3 +80,20 @@ more. **Decision.** The only permitted live-send target is user zzib (`177117296140091393`). **Reason.** Tests must not send messages to other users. DMs to zzib are safe and permitted. + +## ADR-10: Poll command + +**Decision.** The poll command accepts `|` or `//` as separators, an optional quoted question, and +many reactions per user. A bare command shows help. + +**Reason.** The pipe is hard to type on some keyboards. `//` is safe in Discord markdown when it has +whitespace on both sides, so URLs stay in one piece. Many selections match how people use polls in +group chats. A bare command gives the user the syntax without a failed poll. + +## ADR-11: Persistent action log + +**Decision.** Write triggers, continuations, commands, replies, and errors to a rotating JSONL file. +Redact token-shaped strings before the write. + +**Reason.** The in-memory trigger log resets at restart. The action log gives a durable audit trail +without storing raw credentials. diff --git a/docs/testing.md b/docs/testing.md index 40f9ce9..7c43796 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -5,14 +5,17 @@ This document describes the test setup, the run commands, and the known gaps. ## Unit tests The pure daemon logic has unit tests. The tests cover the ring buffers, the mention helpers, the -command parser, the trust check, and the pacing range. +command parser, the poll parser, the trust helpers, the context assembly, the redaction, and the +pacing range. The cache tests cover merge, dedupe, trimming, and eviction. ```sh cd poc pnpm test:comm +pnpm test:cache ``` -The file is `poc/src/test-communication.ts`. The tests do not need Discord or Vesktop. +The files are `poc/src/test-communication.ts` and `poc/src/test-cache.ts`. The tests do not need +Discord or Vesktop. ## Type checks @@ -49,6 +52,10 @@ VESKSLOP_SOCKET=/tmp/vesktop-puppet-mock.sock TEST_TRIGGER_CONTENT="whitelist li Expected result: the daemon log shows one trusted entry with the parsed command. The mock log shows the reply (`message.send`). The reply wait is inside the 500 to 2800 ms window. +The mock also covers tiers, continuation, polls, reactions, and the action log. Set config values +with `set_puppet_config` before a test. Inject a reaction with +`TEST_TRIGGER_REACTION=1 TEST_REACTION_MESSAGE_ID=msg-1 TEST_REACTION_EMOJI="1️⃣" pnpm test:trigger`. + ## CDP probe The probe checks the CDP fallback transport. Start the client with @@ -89,7 +96,7 @@ Notes: - `VENCORD_USER_DATA_DIR` pins the Electron profile. The profile holds the client session. - Write `{"firstLaunch": false}` to `/state.json` before the first start. This step skips - the first-launch window. The `VESKSLOP_HEADLESS=1` flag does the same job when it is in the tree. + the first-launch window. The `VESKSLOP_HEADLESS=1` flag does the same job. - The container needs `libasound.so.2` for Electron. Extract the library locally when the system package is not available. @@ -120,5 +127,7 @@ The CDP transport was verified earlier with the same checks. | Gap | Effect | | --- | --- | | Live trigger tests need an incoming message. | Use the mock core, or send from zzib's account. | +| `reaction.add` and the message ID return are mock-verified only. | Confirm Discord's internal `addReaction` lookup on the first live run. | +| Polls and other chat commands are mock-verified only. | Run them on the live client. | | `message.read` is cache-only. | A channel that the client never opened returns zero messages. | -| Voice, audio, and video are not started. | No test coverage. | +| Voice, audio, and video are not started. | No coverage. | diff --git a/poc/README.md b/poc/README.md index 71f1f62..32e98f1 100644 --- a/poc/README.md +++ b/poc/README.md @@ -20,6 +20,7 @@ pnpm install | `pnpm test:trigger` | Inject a trigger event into the mock core. | | `pnpm poc:dm` | Send one test DM to zzib. | | `pnpm test:comm` | Run the unit tests for the pure logic. | +| `pnpm test:cache` | Run the unit tests for the message cache. | | `pnpm cdp:probe` | Check CDP access and event delivery. | | `pnpm cdp:dispatch` | Run one CDP expression in the client. | | `pnpm check` | Type check the daemon code. | @@ -49,9 +50,13 @@ The only permitted live-send target is user zzib. See - QR login works end-to-end. The token came from a phone scan. - The core bridge works live. `get_state` returned the real account and 7 guilds. `send_dm` reached zzib. A synthetic owner message reached the daemon log with the command parsed. -- The mock path works. The daemon handles state, sends, commands, and the two log buckets. +- The mock path works. The daemon handles state, sends, commands, tiers, continuation, polls, + context, and the action log. - Pacing stayed inside the 500 to 2800 ms window. +Open live item: `reaction.add` and the message ID return are mock-verified only. The first live run +must confirm Discord's internal `addReaction` lookup. + ## Findings - Official `discord.js` is bot-only. It fails at login with a user token. The popular selfbot fork