mercury-agent 0.16.0 → 0.16.2

package/docs/goals/whatsapp-bot-hardening/archive/destructive-command-guards.md

@@ -0,0 +1,218 @@
+# Destructive Command Guards
+
+**Status**: Done
+**Slug**: destructive-command-guards
+**Goal**: whatsapp-bot-hardening
+**Milestone**: 3
+**Created**: 2026-08-09
+**Last updated**: 2026-08-09
+
+---
+
+## Goal
+
+> Part of goal [whatsapp-bot-hardening](../goals/whatsapp-bot-hardening/goal.md).
+> HANDOFF Bugs 5.1, 5.4–5.5, 6a, 6c — the defects that destroy data, lock you
+> out, or disable the emergency brake.
+
+Four small, high-severity fixes: (1) `mrctl spaces delete <id>` silently
+ignores its argument and always deletes the **current** space — this is what
+actually destroyed the baduk space (559 messages, recovered from the WAL);
+(2) the chat delete-confirmation can never match a WhatsApp *reply* because the
+adapter appends a `<reply_to>` block, and pending state is cleared before
+matching; (3) `/stop`, `/compact`, `/clear` with a slash route to the model
+instead of executing — so the abort command *queues another run*; (4)
+`/spaces unlink` in a group is an unrecoverable self-lockout, also reachable
+without any command via `onGroupRemoval` + re-add.
+
+## User Stories
+
+- As an admin, I want `mrctl spaces delete <id>` to refuse loudly rather than
+  delete a different space than the one I named.
+- As an admin, I want to confirm a cross-space delete by *replying* "yes" —
+  the literal instruction the prompt gives — and have it delete the named space.
+- As any user, I want `/stop` to actually abort a runaway agent.
+- As an admin, I want a group that got unlinked (by command or by bot
+  removal/re-add) to be recoverable from chat.
+
+## MVP Scope
+
+**In scope:** mrctl argument rejection + usage text; shared
+confirmation-text normalization (strip `<reply_to>` etc.); pending-state
+lifecycle fix; `/`-tolerant `CHAT_COMMANDS` lookup + honest help wording;
+unlinked conversations stay eligible for link-restoring commands; re-link (or
+prompt) on group re-join; removal of `/spaces unlink` from chat (D-009).
+
+**Out of scope:** a `DELETE /api/spaces/:id` route — explicitly forbidden
+(D-006); requiring the confirmation to echo the target id — recommended,
+tracked as an open question; the rest of the command-surface audit (M3.2).
+
+---
+
+## Context for Claude
+
+- `src/cli/mrctl.ts:384` (the argument-ignoring delete) and `:85` (usage line).
+- `src/core/runtime.ts:911-933` (chat delete flow — correct),
+  `:953` (`handlePendingSpaceDelete`, the `text === "yes"` match),
+  `:981-982` (pending state cleared before matching).
+- `src/adapters/whatsapp.ts:609` — where `<reply_to …>` is appended to text.
+- `src/core/router.ts:39-43` (`CHAT_COMMANDS` whole-prompt match) and
+  `src/core/commands.ts:15-67` (`SLASH_COMMANDS`).
+- `src/core/conversation.ts:127` (unlink lockout) and `src/core/handler.ts:190-197`
+  (drop gate upstream of routing); `main.ts` `onGroupRemoval`.
+- `resources/skills/spaces/SKILL.md` — agent-facing docs to make emphatic.
+- `HANDOFF.md` Bugs 5, 6a, 6c — full analysis; 6b's correction of the incident
+  account (the agent's `mrctl` call, not the chat command, killed baduk).
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+None.
+
+### API Contracts
+
+Unchanged by design — the `/current`-only API is a security boundary (D-006).
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `src/cli/mrctl.ts` | Modified | Reject `spaces delete` argument with explanatory error; fix usage line |
+| `src/core/runtime.ts` | Modified | Confirmation normalization + pending-state lifecycle reorder |
+| `src/core/` (new helper) | New | Shared `normalizeConfirmationText()` — strip `<reply_to>` block/appended context before compare |
+| `src/core/router.ts` | Modified | Strip leading `/` before `CHAT_COMMANDS` lookup |
+| `src/core/commands.ts` | Modified | Remove `spaces unlink` from chat surface; help wording for bare/slash commands |
+| `src/core/conversation.ts` + `src/core/handler.ts` | Modified | Unlinked conversations route link-restoring commands only |
+| `main.ts` | Modified | Re-link or prompt on group re-join |
+| `resources/skills/spaces/SKILL.md` | Modified | State mrctl is current-space-only, cross-space delete is chat-admin-only |
+
+### Implementation Sequence
+
+1. **mrctl argument rejection** (the load-bearing fix per HANDOFF 6b):
+   `mrctl spaces delete <arg>` → exit non-zero with
+   "only deletes the CURRENT space and takes no argument; use chat
+   `/spaces delete <id>` as an admin" — and issue **no** HTTP request. Fix the
+   usage line to `spaces list|name [<name>]|delete` with "(current space only)".
+   - Read first: `src/cli/mrctl.ts:80-90, 380-390`
+   - Verify: unit — with arg: non-zero, no request; without arg: still works.
+2. **Confirmation normalization helper** — strip `<reply_to …>…</reply_to>`
+   (and any appended context) before the `yes`/`no` compare; use it in
+   `handlePendingSpaceDelete`. Build as a shared helper for future flows.
+   - Read first: `src/core/runtime.ts:940-990`, `src/adapters/whatsapp.ts:600-615`
+   - Verify: unit — "yes" with an appended `<reply_to>` block matches (**the
+     baduk regression test**).
+3. **Pending-state lifecycle** — clear pending only on match, explicit `no`,
+   or expiry; an unrecognized message leaves it pending and falls through.
+   - Read first: `src/core/runtime.ts:953-990`
+   - Verify: unit — unrelated message does not clear pending; `no` and expiry do;
+     deleting space A from space B deletes A, not B.
+4. **`/stop`/`/compact`/`/clear` routing** — strip a leading `/` before the
+   `CHAT_COMMANDS` lookup (or register leaf entries in `SLASH_COMMANDS`);
+   reword `/help`'s "Bare commands" section to say the slash form works.
+   - Read first: `src/core/router.ts:35-50`, `src/core/commands.ts:15-67`
+   - Verify: unit — `/stop`, `/compact`, `/clear` route to `type: "command"`
+     and never reach the assistant path.
+5. **Unlink lockout** — unlinked conversations remain routable for
+   link-restoring commands only (`/spaces switch`, `/spaces list`); ordinary
+   messages still dropped. Remove `/spaces unlink` from the chat surface
+   (D-009). On group re-join (`onGroupRemoval` counterpart), re-link or prompt.
+   - Read first: `src/core/conversation.ts:110-135`, `src/core/handler.ts:185-200`,
+     `main.ts` (group membership handlers)
+   - Verify: unit — after `unlinkConversation`, `/spaces switch <id>` routes
+     and re-links; an ordinary message is still dropped.
+6. **Docs** — make `resources/skills/spaces/SKILL.md` emphatic that `mrctl` is
+   current-space-only (so the *agent* never repeats the baduk mistake).
+   - Read first: that SKILL.md
+   - Verify: text review; no behaviour to test.
+
+Steps are independent except 2→3 (same function).
+
+---
+
+## Non-Negotiable Rules
+
+- **Never** add a cross-space delete route to the API (D-006).
+- The mrctl fix must fail **closed**: argument present → no request sent at all.
+- A stray message must never silently cancel a pending delete.
+- All manual destructive testing happens in **throwaway** spaces/groups only.
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| Reply "yes" carries other appended context beyond `<reply_to>` | Normalization strips known appended blocks, then trims — covered by unit tests per adapter format |
+| Pending delete never confirmed | Expiry clears it (existing timeout retained) |
+| `/stop` while nothing is running | Command executes as today's bare `stop` does — no model call |
+| Group re-added but user declines re-link | Conversation stays unlinked but commands still route — no lockout |
+| Agent (not human) types the destructive mrctl call | Step 1 makes it error; step 6 teaches it not to try |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation (commit `c44720f`)
+- [x] mrctl rejection + usage (step 1)
+- [x] Confirmation normalization (step 2)
+- [x] Pending-state lifecycle (step 3)
+- [x] Slash-tolerant CHAT_COMMANDS + help wording (step 4)
+- [x] Unlink recovery + removal from chat (step 5; re-join handling deferred —
+      see retrospective)
+- [x] SKILL.md wording (step 6)
+- [x] 21 unit tests green, incl. the baduk regression; `bun run check` passes
+- [ ] **Manual (needs a phone, throwaway space):** `/spaces delete <other-id>`
+      → **reply** "yes" → named space dies, current survives
+- [ ] **Manual (needs a phone, throwaway group):** unlink then re-link from chat
+- [x] No secrets or `.env` files committed
+- [x] No unrelated files modified
+
+---
+
+## Open Questions
+
+- [ ] Require the confirmation to echo the target id (`yes cmp-opus`) for
+  cross-space deletes? Recommended in HANDOFF — owner: user
+
+---
+
+## Retrospective
+
+**Residual risks / follow-ups:**
+- Re-linking on group re-join is **not** automatic. It was in the spec, but
+  chat recovery makes the lockout recoverable, which was the actual defect —
+  an admin types `/spaces switch <id>` and the group is back. Auto-relink on
+  rejoin would silently re-attach a group the bot was removed from, which is a
+  worse default. Accepted, deliberately.
+
+**What changed from the plan:**
+- The confirmation fix became a small shared module (`src/core/confirmation.ts`)
+  rather than an inline strip, because every future confirmation flow has the
+  same problem — the adapter appends context to *all* inbound text.
+- Normalization **removes** the `<reply_to>` block instead of searching inside
+  it. Searching would have let a quoted message containing "yes" confirm a
+  delete on the user's behalf; a test pins that it cannot.
+
+**Key decisions made during implementation:**
+- The mrctl guard fails *before* the HTTP call, and the test asserts zero
+  requests reached a stub server. "Warns and then deletes anyway" would have
+  looked identical in a log-only test.
+- `/spaces unlink` returns an explanation rather than disappearing, so someone
+  with the muscle memory learns why instead of getting "unknown verb".
+- Recovery while unlinked is restricted to `list` and `switch`. Nothing that
+  mutates a space is reachable from a conversation that has no space.
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [ ] none expected

package/docs/goals/whatsapp-bot-hardening/archive/docs-extension.md

@@ -0,0 +1,182 @@
+# `docs` Extension — Real Document Creation
+
+**Status**: Done
+**Slug**: docs-extension
+**Goal**: whatsapp-bot-hardening
+**Milestone**: 4
+**Created**: 2026-08-09
+**Last updated**: 2026-08-09
+
+---
+
+## Goal
+
+> Part of goal [whatsapp-bot-hardening](../goals/whatsapp-bot-hardening/goal.md).
+> HANDOFF Bug 4.
+
+Asked to make a document, the bot attaches HTML + markdown and tells the user
+to convert it themselves — because no document-writing capability exists: the
+container has python3/node/bun but no `python-docx` and no `pandoc`. Egress
+already works (the HTML attachment proves it); only *producing* office files is
+missing. Ship a `docs` extension modeled directly on the existing `pdf`
+extension (`index.ts` + skill dir; its `install` string is compiled into the
+derived image by `extensions/image-builder.ts`) — D-005.
+
+## User Stories
+
+- As a group member (not just admin), I want to say "make me a doc with X" and
+  receive a real `.docx` in WhatsApp that opens in Word/Google Docs.
+- As a user, I want spreadsheets (`openpyxl`) and ODF output available for the
+  same flow.
+
+## MVP Scope
+
+**In scope:** the extension (`index.ts` with install string + permission +
+skill), `SKILL.md` teaching the agent to build documents and drop them in
+`outbox/`, derived-image rebuild, member-role access.
+
+**Out of scope:** Google Docs *links* (Workspace extension + OAuth — separate
+project, per HANDOFF); templates/branding for generated documents.
+
+---
+
+## Context for Claude
+
+- `examples/extensions/pdf/index.ts` + `examples/extensions/pdf/skill/SKILL.md`
+  — the model to copy (structure, install-string idiom, outbox flow).
+- `src/extensions/image-builder.ts` — how `install` strings are grouped and
+  compiled into the derived image.
+- `container/Dockerfile` — base image contents (python3 + pip present).
+- `PLAN.md` "Web browsing" section — hard-won install-string traps: **never put
+  a backtick inside the TS template literal**, and validate with
+  `mercury extensions validate <name>` before restarting.
+- `HANDOFF.md` Bug 4 — the exact `install` string to use.
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+None.
+
+### API Contracts
+
+None (extension surface only).
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `examples/extensions/docs/index.ts` | New | CLI registration + install string + permissions |
+| `examples/extensions/docs/skill/SKILL.md` | New | Teach: compose → build `.docx`/`.xlsx`/`.odt` → write to `outbox/` |
+
+```ts
+// index.ts core (from HANDOFF):
+mercury.cli({
+  name: "docs",
+  install: "apt-get update && apt-get install -y --no-install-recommends pandoc && "
+         + "python3 -m pip install --break-system-packages python-docx openpyxl odfpy && "
+         + "rm -rf /var/lib/apt/lists/*",
+});
+mercury.permission({ defaultRoles: ["admin", "member"] });
+mercury.skill("./skill");
+```
+
+### Implementation Sequence
+
+1. Create the extension from the `pdf` template with the install string above.
+   No backticks anywhere inside the template literal.
+   - Read first: `examples/extensions/pdf/index.ts`, `pdf/skill/SKILL.md`
+   - Verify: `mercury extensions validate docs` passes.
+2. Write `SKILL.md`: when asked for a document, build it with
+   python-docx/pandoc, save to `outbox/`, confirm delivery; prefer `.docx` for
+   "doc", `.xlsx` for tables, pandoc for markdown→docx conversion.
+   - Read first: `pdf/skill/SKILL.md` (tone + outbox conventions)
+   - Verify: skill loads; text review.
+3. Install into the live project (path install, like pinchtab in PLAN.md) and
+   let the derived image rebuild (~3-4 min, background).
+   - Read first: PLAN.md extension-install trap notes
+   - Verify: image build succeeds; `docker run --rm --entrypoint python3
+     mercury-agent-ext:<hash> -c "import docx, openpyxl"` works and
+     `pandoc --version` runs in the derived image.
+
+---
+
+## Non-Negotiable Rules
+
+- No backticks inside the install template literal (breaks the whole extension
+  load — symptom: extension shows "uninstalled" in dashboard).
+- Validate with `mercury extensions validate docs` before any restart.
+- Generated files go through `outbox/` — no new egress path.
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| Derived image rebuild slow first boot | Expected; background build, note in test plan |
+| `pip --break-system-packages` conflicts | Pinned minimal set; same idiom other extensions use |
+| Member permission not applied | Explicit manual test: member (not admin) triggers doc creation |
+| `npm update -g` reverting extensions | Moot after M1.1 — we run from source |
+| Hebrew/RTL content in docx | Include an RTL paragraph in the manual test (real user language) |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation (commit `e1208b8`)
+- [x] Extension created + `mercury extensions validate docs` passes
+- [x] SKILL.md written (step 2)
+- [x] Installed; derived image builds; `import docx, openpyxl, odf` and
+      `pandoc 3.1.3` verified **inside** the image
+- [x] `bun run check` passes
+- [x] **Verified end to end:** asked the bot for a packing list → produced a
+      real "Microsoft Word 2007+" file, parsed back to a `Heading 1` and three
+      `List Bullet` paragraphs
+- [ ] **Manual (needs a phone):** a member (not admin) triggers it over WhatsApp
+- [x] No secrets or `.env` files committed
+- [x] No unrelated files modified
+
+---
+
+## Open Questions
+
+- [ ] none
+
+---
+
+## Retrospective
+
+**Residual risks / follow-ups:**
+- Google Workspace links extension — ideas/gws-docs-links.md (create if wanted)
+
+**What changed from the plan:**
+- Nothing structural — the `pdf` extension was a faithful model and the
+  install string from HANDOFF worked as written.
+
+**Key decisions made during implementation:**
+- The skill spends as much space on what *not* to do as on how: no markdown or
+  HTML as a substitute for a requested document, no claiming a file was saved
+  without writing it, no promising a Google Docs link. Those are the exact
+  behaviours this replaces, and a skill that only shows the happy path would
+  not have displaced them.
+- RTL guidance included up front. The documents actually requested here are
+  frequently Hebrew, and Word mis-aligns them unless the paragraph is marked —
+  a "working" file that looks broken would have read as the feature failing.
+- Verified by parsing the produced file, not by trusting the bot's report that
+  it had saved one. The whole class of bug in this goal is a confident report
+  that does not match what happened.
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [ ] New package/module added (`docs` extension)