@jeffober/thatch 0.2.3 → 0.2.5

package/docs/plans/llm-alerts.md

@@ -1,287 +0,0 @@
-# Thatch Alerts: Notify the User When the LLM Pauses or Finishes
-
-## Synopsis
-
-Add an opt-in alert layer to the thatch opencode plugin that sends a desktop
-notification when the LLM (a) is blocked on a human decision -- an interactive
-question or a permission request -- or (b) finishes a round of real work. Bookkeeping
-rounds driven by thatch's own nudges and background-task completions never notify.
-One code path serves both installed opencode lines (v1.18.x and v2.x). The brain
-lives in the server plugin, which is a single instance per project directory, so
-deduplication and debouncing per session are free.
-
-## Background
-
-Jeff's workflow: ask a question, switch to another window, let the LLM work. He
-needs a notification when the work finishes or when it stalls waiting for him.
-Nothing else deserves a notification.
-
-What exists today and why it is not enough:
-
-- opencode v2's built-in TUI attention plugin (`internal:notifications`) notifies
-  on question, permission, done, and error. It has no per-event configuration, and
-  its "done" fires on every turn end -- including turns triggered by thatch nudges
-  and background-task completions. That turns async thatch activity into
-  notification spam.
-- The v1 line has no TUI plugin system at all. The community notifier plugin
-  Jeff used on v1 is orphaned (config remnants in `~/.config/opencode`, upstream
-  issue mohak34/opencode-notifier#108).
-- Thatch already ships `thatch_notify_user` (voice + banner, session-labeled), but
-  it is a tool the LLM invokes on request. It cannot fire on host-level events,
-  and it must not fire on every turn end.
-
-opencode's attention API (system notification + sound, focus-aware) exists only in
-the TUI plugin context, so a pure server plugin cannot use it. Shipping a thatch
-TUI plugin would deliver notifications through the terminal but would reintroduce
-the double-TUI problem: one plugin instance per attached TUI means one notification
-per TUI, and the same v2 session can live in two TUIs. Server-side delivery avoids
-that by construction.
-
-## Goals
-
-- Notify on `question.asked` and `permission.asked` (the blocking cases).
-- Notify when a round of real work ends (busy -> idle transition).
-- Stay silent on rounds whose only tool calls were thatch or meta tools, and on
-  turns triggered by synthetic input (nudges, task completions, watcher wake-ups).
-- Stay silent on recoverable errors and user-initiated aborts; notify when a
-  session dies in a state nothing will wake.
-- Work identically on opencode v1.18.x and v2.x from one code path.
-- Deduplicate and debounce per session in one process.
-
-## Non-goals (deferred)
-
-- TUI plugin delivery via opencode's attention API (v2-only, focus-aware, but
-  per-TUI instances defeat dedup). Revisit as a v2 enhancement: a TUI plugin could
-  report focus state to the server plugin for focus gating.
-- Focus gating in general. Server-side delivery cannot see terminal focus; banners
-  may land while the terminal is focused. Accepted: Jeff's stated workflow is to be
-  away from the terminal, and one unified code path is worth the noise.
-- Reload-state persistence. v2 auto-reload discards plugin memory on every save to
-  the dev shim tree (see the PR #16 design). Worst case here is one missed or
-  duplicate alert at a reload boundary, which Jeff has ruled acceptable. No
-  `runtime_state` journaling for alerts.
-- Claude Code / Cursor hosts. The MCP server has no event stream. Claude Code's
-  `Notification` and `Stop` hooks could feed the same classifier later; a parity
-  row documents the gap.
-
-## Design
-
-### Architecture
-
-One actor owns all alert state: the thatch plugin instance inside the shared
-opencode server process (per project directory). Both v1 and v2 load exactly one
-instance per directory no matter how many clients are attached, so per-session
-dedup and debounce are plain in-memory maps. Delivery reuses the platform
-dispatcher that `thatch_notify_user` already uses.
-
-```text
-event hook (question/permission/session.*)
-        |
-        v
-per-session alert state machine  --->  classifier (real work?)
-        |                                     |
-        v                                     v
-   src/notify.ts dispatcher  <--- config (alerts section)
-   (osascript / notify-send / say)
-```
-
-### Event capture
-
-| Event | Action |
-|---|---|
-| `question.asked` | Notify "needs your answer". Track request id; clear on `question.replied` / `question.rejected`. |
-| `permission.asked` | Notify "needs approval". Track request id; clear on `permission.replied`. |
-| `session.status` busy or retry | Mark the session active. Clear any recorded error (a retry means opencode is still working). |
-| `session.status` idle (from active) | Evaluate the round: classify, then notify or stay silent. |
-| `session.error` | Record the error on the session. Do not notify yet -- the status transition decides. |
-
-Both lines publish `question.asked` / `permission.asked` on the event bus with the
-full request payload (sessionID included), and `session.status` carries
-`{ type: "idle" | "busy" | "retry" }`. Verify both against the installed versions
-before implementation (see Verification).
-
-### Per-session state machine
-
-State kept per session id: `active` (bool), `lastError` (name + message or null),
-`pendingAsks` (request ids already notified). Transitions mirror the built-in v2
-plugin's proven pattern, with error handling changed to match Jeff's intent:
-
-- error followed by busy/retry -> recovered, clear the error, keep going quiet.
-- error followed directly by idle -> nothing will wake the session; notify
-  "needs attention" instead of a done notification.
-- `MessageAbortedError` -> always silent (the user pressed abort; they know).
-- busy -> idle with no error -> the done path: classify the round, notify only
-  real work.
-
-Notification state is rebuilt empty on plugin setup. Reload or restart mid-turn
-means the busy->idle transition is never observed and that round stays silent.
-Accepted.
-
-### Round classification (shared classifier)
-
-At idle, inspect the round's tool calls and skip when the round did no real work:
-
-1. Skip sessions with a `parentID` (subagent children never notify).
-2. Skip when the triggering user message is synthetic-only. This covers thatch
-   nudge turns, background-task completions, and watcher wake-ups. Without this
-   rule, zero-tool-call narration turns (the typical completion-injection turn)
-   would still notify.
-3. Otherwise inspect the last assistant message's tool parts. Skip when every tool
-   call is in the meta set: `thatch_*`, the dispatch tools `task` / `agent` /
-   `subagent` (name differs by version -- match the set, never one name), `skill`,
-   `todowrite`, `question`, and `execute` calls whose code only wraps thatch tools
-   (reuse the `unwrapExecuteThatchCalls` scan from `src/extraction.ts`).
-4. Real tool calls present -> notify "work finished", titled with the session
-   title (every notification identifies its session -- standing preference).
-
-The meta-tool exclusion and the execute-unwrap scan already exist in the
-extraction buffer's non-bufferable filter. Extract them into one shared pure
-function (in `src/extraction.ts` or a sibling) consumed by both the buffer and
-this classifier, so the aggregator-tool lessons live in one place. Unit tests for
-the shared classifier extend the existing meta-tool buffer tests.
-
-### Config
-
-New `alerts` section in `~/.config/thatch/config.json` (schema in `src/config.ts`,
-written via `config_set`, hand-editable, atomic save -- same as `notifications`):
-
-```jsonc
-{
-  "alerts": {
-    "pause": { "mode": "banner" },   // question + permission
-    "done":  { "mode": "banner" },   // real-work turn end
-    "error": { "mode": "banner" }    // stalled session
-  }
-}
-```
-
-`mode` accepts `both` / `banner` / `voice` / `none`, defaulting to `banner` for
-every event. Voice is opt-in per event: turn-end voice would fire far too often to
-be the default, and `thatch_notify_user` remains the LLM-invoked voice channel.
-Delivery goes through `sendNotification` in `src/notify.ts`, which already owns
-per-platform dispatch (darwin: `osascript` banner + `/usr/bin/say`; linux:
-`notify-send` / `spd-say` / `espeak`) and the injectable spawner tests need.
-Spoken alerts carry the session-identifying source label, per the standing rule.
-
-### Version support
-
-The event hook, session status events, and the notify dispatcher exist on both
-lines. Divergence is confined to two seams, both already abstracted in
-`src/capabilities.ts` / the v1-v2 adapter layer:
-
-- Message reading for the classifier: v2 exposes session context/messages through
-  the promise client; v1 has its own message-list shape. Map both into one
-  internal part view (tool calls + synthetic flags) in the capabilities layer.
-- Tool naming: the dispatch tool is `task` (v1) vs `subagent` (v2); the classifier
-  matches the set.
-
-## Verification (before implementation)
-
-1. SSE probe against the installed v1.18.x serve: confirm `question.asked`,
-   `permission.asked`, and `session.status` appear on `/api/event` and carry the
-   session's directory as `location` (the plugin event hook drops events whose
-   location does not match).
-2. Same probe against installed v2.x.
-3. Confirm the message-list shape on both lines exposes tool parts (with tool
-   names) and synthetic flags, so the classifier can read them.
-4. Confirm one plugin instance per directory in the shared server (both lines) --
-   this is the dedup guarantee, so verify rather than assume.
-
-## Implementation milestones
-
-1. Extract the shared round classifier (meta set + execute-unwrap) from the
-   extraction filter; unit tests first.
-2. Alert state machine in the plugin event hook (`src/index.ts` or a new
-   `src/alerts.ts`): pause tracking, active/error/idle transitions.
-3. Capabilities-layer message mapping for both lines.
-4. `alerts` config section + `config_get` / `config_set` wiring + dispatcher
-   calls.
-5. QA use cases + docs.
-
-## Testing
-
-- Unit: classifier cases (all-meta skip, real work notify, execute-wrapped unwrap,
-  dispatch-tool set, synthetic-only skip); state-machine transitions (busy->idle
-  notify once, error->retry quiet, error->idle notify, abort silent, dedup by
-  request id); config parsing and defaults.
-- QA (`tests/qa/auto/`): drive a session through the plugin harness with the
-  injectable spawner capturing `sendNotification` calls; assert pause and done
-  alerts fire, nudge turns stay silent. Import the file from the suite's
-  `index.test.ts` barrel.
-- Gate: `mise run check` and `mise run qa-auto` green before commit.
-
-## Docs impact
-
-- `docs/user/notifications.md` -- alerts section: what fires, how to configure
-  `alerts`, limitations (no focus gating, opencode-only).
-- `docs/dev/features/notifications.md` -- architecture: event capture, state
-  machine, shared classifier, version seams.
-- `docs/dev/README.md` -- module table row if a new module lands.
-- `docs/dev/mcp-parity.md` -- row for the opencode-only alerts surface.
-- `docs/dev/gotchas.md` -- entry if the v1/v2 event or message-shape seams cost
-  debugging time.
-
-## Decisions already made
-
-- Server-plugin delivery over TUI-plugin delivery (dedup by construction, unified
-  across versions).
-- Reload state loss accepted; no `runtime_state` journaling.
-- Watcher wake-up turns stay silent; the LLM can call `thatch_notify_user` when it
-  decides something is important (tool already exists).
-- User aborts stay silent; unrecovered errors notify.
-- Banner default, voice opt-in per event.
-- Retire the orphaned v1 notifier config during rollout; leave v2's built-in
-  attention settings untouched unless doubles annoy (its TUI-side notifications
-  only fire when blurred).
-
-## Deviations from the plan as written
-
-Recorded during implementation and review pass 1 (crash-override-00004);
-the review's blocking findings were real and fixed:
-
-- **The round's tool side comes from live bookkeeping, not the message
-  list.** The plan's classifier read tool calls from messages and reused
-  `unwrapExecuteThatchCalls` there; message parts do not carry tool
-  arguments, so the unwrap was impossible at that seam (and was silently
-  dropped -- the round-1 review caught the plan Mandate going unmet). The
-  shipped design marks real work at the extraction buffer's push site
-  (`sessionRealWork`), which already classifies meta tools and unwraps
-  execute-wrapped thatch calls. `RoundShape` carries only the trigger side
-  (synthetic) and the round error. `deriveRoundShape` is exported and pure
-  (the review found the inline closure untestable, which is exactly where
-  the blocking bug hid).
-- **The round delimiter is the host's idle marker on v2** (review B1):
-  v2.0.16 appends a `{type: "idle"}` marker message at every turn end, and
-  the plan's "newest non-assistant message is the trigger" scan picked the
-  marker -- every v2 round looked empty and done alerts were dead. The
-  round is now everything after the previous marker (the host's turn
-  definition; also fixes mid-round steers on v2). V1 keeps the trigger
-  scan (no markers; mid-round steers under-classify -- accepted v1
-  limitation).
-- **A v2 execution failure now delivers the verdict immediately** (review
-  B2): failed is the only terminal event for a failed busy period -- no
-  idle follows it -- so the adapter translates it to the v1-shaped pair
-  (`session.error` + `session.status` idle). Interrupts translate to an
-  error named by reason (`user` -> MessageAbortedError silent, `shutdown`
-  -> SessionShutdownError silent, `inactivity` -> SessionInactivityError ->
-  needs-attention) + idle.
-- **Unknown round shape stays silent**, not "notify". The original choice
-  (never miss a completion) made every adapter-level test whose client mock
-  lacks a message surface spawn a real osascript banner during `mise run
-  check` -- the state machine reached live delivery through the pump's
-  busy->idle path. Silence on a failed fetch is also the better product
-  behavior: alerts are best-effort, and the same fetch failure already
-  breaks the wrap-up greenlight check, so the session degrades consistently.
-- **v1 event names verified from source, not SSE probe**: v1.18.9 publishes
-  `question.asked`/`question.replied`/`question.rejected`
-  (`packages/schema/src/v1/question.ts`) and `permission.asked`/
-  `permission.replied` (`packages/schema/src/v1/permission.ts`); the
-  installed v1 SDK's `types.gen.d.ts` is stale (no question events, and
-  `permission.updated` is a legacy type with no publish site). The events
-  flow through the plugin event hook as untyped `{type, properties}`, so
-  SDK staleness is harmless. Reply events carry `requestID` on both lines
-  (the review killed a defensive `permissionID` fallback as dead code).
-- **v2 idle translation reused**: v2's SSE stream delivers the idle signal
-  as `session.execution.*` events (the existing `translateEvent` mapping),
-  so pause events needed translation cases there rather than a new
-  subscription path.

package/docs/plans/thatch-actions.md

@@ -1,179 +0,0 @@
-# Thatch Actions: Prompt Cores Shared by Nudges and /thatch Commands
-
-## Synopsis
-
-Extract the behavior instructions currently embedded in nudge text into
-prompt-core constants in `src/prompts.ts`, then build `/thatch/*` user-facing
-commands on top of the same constants. The nudge and the command become two
-envelopes around one instruction body: the nudge adds escalation tiers and
-stop-and-wait framing, the command adds user-invocation framing. First
-payoff is `/thatch/defrag`, but the structure covers any behavior the nudges
-currently ask the agent to perform on demand.
-
-## Background
-
-Nudges are instruction-carrying messages injected by hooks. Several encode a
-multi-step behavior the agent must execute (dispatch a sub-agent, fetch the
-extraction payload, run a skill, ack). The same behaviors have no user-facing
-invocation path: the user cannot say "drain the extraction queue now" or
-"consolidate duplicate memories now" -- they can only wait for a nudge or
-describe the desired behavior in prose and hope the agent maps it to the right
-skill + tool sequence.
-
-Two existing pieces make this cheap to add:
-
-- `src/commands.ts` already ships `/thatch/compact` and `/thatch/exit` as
-  markdown command files synced into the opencode config dir, and already
-  composes them from shared fragments (`sharedChecklist`,
-  `userMessageSection`).
-- The "Shared prose sync across prompt variants" problem is documented:
-  prompt prose lives in parallel functions with no single source of truth,
-  and drift in unasserted sections passes tests. This plan makes the shared
-  behavior text a true constant.
-
-## Design: prompt cores and envelopes
-
-A **prompt core** is a constant string in `src/prompts.ts` holding the
-host-agnostic instruction body for one behavior: which tools to call, in what
-order, with what arguments, and what "done" looks like.
-
-An **envelope** wraps a core with delivery-specific framing:
-
-- The nudge envelope adds: escalation tier wording, the load-bearing
-  stop-and-wait ending (see "Extraction nudge stop-and-wait wording is
-  load-bearing" -- the stop-and-wait text is nudge-only and must NOT leak
-  into action envelopes, because an action IS user input), and the
-  "system nudge, not user input" disclaimer.
-- The action envelope adds: frontmatter description, the `# User Message`
-  section with `$ARGUMENTS`, and any greenlight-token mechanics (wrap-up
-  commands only).
-
-Cores are plain string constants, not template functions, so both envelopes
-interpolate them identically. Where a core needs host-specific tool names
-(`thatch_memory_remember` vs `mcp__thatch__memory_remember`), the core takes
-the opencode spelling and MCP consumers apply the documented token
-substitution, matching the existing systemPrompt/mcpInstructions convention.
-
-## Actions v1
-
-| Command | Core behavior | Existing machinery |
-|---|---|---|
-| `/thatch/defrag` | Run `thatch_find_duplicates`, classify each pair with the thatch-dedup-classifier skill, consolidate (remember/overwrite or forget), mark pairs checked | find_duplicates + dedup classifier skill |
-| `/thatch/extract` | Fetch the extraction payload, run the fact-extractor skill, call `extraction_done` | get_extraction_payload + fact-extractor skill |
-| `/thatch/hygiene` | Run the hygiene report, act on stale and orphaned branch-scoped memories | `hygieneReport()` + `/thatch hygiene` CLI |
-| `/thatch/reflect` | Run the session-reflection skill over the current session | thatch-session-reflection skill |
-
-The wrap-up commands (`compact`, `exit`) stay as-is; their checklist text
-becomes a core reused by both templates (already true via `sharedChecklist`).
-
-`/thatch/extract` interacts with opencode's direct extraction (parent idle
-spawns the extractor child; the nudge is only a fallback). The action must
-reuse the same accept/complete semantics and must not fight the `extracting`
-set: if direct extraction is already running for the session, the action
-should report that and stop rather than double-dispatch.
-
-## Host parity
-
-Commands are markdown or MCP prompts, synced per host. Behavior parity is the
-goal; format differences are documented, not hidden.
-
-- **opencode** (existing): `installOpencodeCommands` syncs markdown to
-  `~/.config/opencode/command/thatch/` on every plugin load.
-- **Claude Code**: native user-level slash commands read markdown from
-  `~/.claude/commands/thatch/` (user scope) or `.claude/commands/thatch/`
-  (project scope), with the same `$ARGUMENTS` substitution. The sync lives in
-  `setup.ts` alongside the existing installers and follows their patterns:
-  idempotent content-compare like `installSkills`, both global and local
-  scopes, reported in the setup output next to the skills report.
-  (Deviation from the draft below: no `checkSetup` entry. That function
-  answers one question - "is thatch set up at all" - and command files
-  self-heal on every setup run, so flagging their absence as a startup
-  warning would be noise.) Differences: no plugin, so no
-  `command.execute.before` arming -- greenlight-token wrap-up commands do not
-  ship to Claude Code; and tool names use the `mcp__thatch__` prefix. MCP
-  hosts do have hooks now (session-start reminders, chat-wake stop hooks), so
-  hook wiring is not the barrier; the missing piece is only the plugin's TUI
-  control routes.
-- **Cursor**: no file-based commands. The stdio MCP server (`mcp.ts`) gains
-  MCP Prompts support (`prompts/list`, `prompts/get`), which Cursor surfaces
-  as slash commands. The dispatch switch currently handles `initialize`,
-  `tools/list`, `tools/call`, and `ping`; prompts get a `compileTools`-style
-  `compilePrompts()` and two new cases. Prompt arguments use MCP's
-  `{{argument}}`-style templating, so each action core gets an MCP-prompt
-  rendering alongside the markdown rendering.
-
-README gains "What works in Claude Code" and "What works in Cursor" sections
-listing per-host support without restating the shared docs. The parity matrix
-in `docs/dev/mcp-parity.md` gets an Actions row next to the existing
-Wrap-up commands row.
-
-## Session ID plumbing
-
-Since the plan was drafted, `HostToolContext` (tool-defs.ts) landed: every
-tool's `execute` receives the invoking session's ID as a third parameter on
-the opencode path, and the watch tools already consume it. `extraction_done`
-also already has the optional `session_id` with the omit-vs-parent rule in
-its description. The remaining work is narrower than first planned:
-
-- `get_extraction_payload`: `session_id` becomes optional. `execute` uses
-  `args.session_id ?? host?.sessionID`. On the opencode path the wrapper
-  supplies the invoking session, so omitted means "this session."
-- MCP path: the host context is omitted (no session concept), so an omitted
-  `session_id` returns a clear error telling the model to pass the parent
-  session's ID from the extraction nudge.
-
-One wrinkle to document: the zod arg shape is shared between hosts, so
-optionality is global -- you cannot make the arg required on MCP and optional
-on opencode at the schema level. Enforcement happens in `execute` per host,
-and the arg description must carry the rule so the model self-corrects.
-
-The rule the LLM must apply, stated everywhere the tools are described:
-
-> Omit `session_id` when acting on the session you are running in. Pass the
-> parent session's `session_id` when running inside a sub-agent that was
-> dispatched to process another session's extraction queue.
-
-This rule appears in: the arg descriptions in `tool-defs.ts`, the extraction
-prompt core (used by both nudge and action envelopes), the fact-extractor
-skill, and the dev docs. Tests cover both paths: omit-resolves-to-current
-and explicit-parent-ID (the existing sub-agent drain bug's regression path).
-
-## Decisions
-
-- Prompt cores live in `src/prompts.ts`, not a new module; `commands.ts`
-  imports them. One prompt module, consistent with the existing module map.
-- Actions are generated, not hand-written: each action has one core and a
-  per-host renderer, so a wording change cannot drift between nudge and
-  command.
-- No `--dry-run` flag for defrag in v1; the dedup classifier skill already
-  asks for pair-by-pair verdicts, which is the interactive safety net.
-- MCP Prompts for Cursor are additive to `mcp.ts` and do not change the
-  tools/list contract.
-
-## Testing
-
-- `tests/commands.test.ts` (or the existing plugin tests): command-file
-  content assertions per host, including that each action's markdown contains
-  its core text verbatim.
-- Claude setup tests: command sync writes, updates only on content change,
-  and `checkSetup` flags a missing or stale command file.
-- MCP tests: `prompts/list` returns every action; `prompts/get` interpolates
-  arguments; an omitted-session-ID `get_extraction_payload` call errors with
-  the pass-the-parent-ID message (no host context on the MCP path).
-- Plugin tests: `get_extraction_payload` without `session_id` resolves via
-  the host context to the invoking session; with an explicit parent ID,
-  drains the parent's queue (the existing sub-agent drain bug's regression
-  path).
-- Parity guard: a test asserts every opencode command def has a
-  corresponding MCP prompt (and vice versa) except the documented exclusions
-  (wrap-up greenlight commands on non-opencode hosts).
-
-## Docs
-
-- `docs/dev/features/commands.md` and `docs/user/commands.md` (two-tier):
-  action list, host parity matrix, session ID rule.
-- `docs/dev/mcp-parity.md`: Actions row in the parity matrix; revisit the
-  Wrap-up commands row if greenlight arming ever lands on MCP hosts.
-- README: "What works in Claude Code" / "What works in Cursor" sections.
-- QA use cases: one auto use case for `/thatch/defrag` end-to-end, one for
-  `/thatch/extract` with omitted session ID.