@jeffober/thatch 0.1.48 → 0.2.0

package/docs/plans/llm-alerts.md

@@ -0,0 +1,287 @@
+# 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/prediction-consolidation.md

@@ -92,12 +92,12 @@ predictions that scored above threshold in the same `scorePredictionNudge`
 call. This is the direct analog of nak's `samskara_fires.cohort_id`.
 
 **Write path:** `scorePredictionNudge` currently returns `PredictionNudgeItem[]`
-and is called from two sites (index.ts auto-fire, sideband.ts MCP path). Add a
+and is called from two sites (runtime.ts auto-fire, sideband.ts MCP path). Add a
 `recordFires` method that takes the scored predictions + a generated cohort_id
 and inserts one row per prediction. The callers generate the cohort_id before
 calling `scorePredictionNudge` and pass it through for recording.
 
-Both callers must record fires. The opencode path (index.ts) has the session_id.
+Both callers must record fires. The opencode path (runtime.ts) has the session_id.
 The MCP path (sideband.ts) does not have a session_id in the sideband request --
 pass null or derive from the socket connection.
 
@@ -278,7 +278,7 @@ db.ts.
 **Code changes by file:**
 - `src/db.ts` -- new table, 4-5 new methods (recordFires, fireCount,
   cofireCount, totalCohorts, findPredictionDuplicates, findCoFireConstellations)
-- `src/index.ts` -- generate cohort_id, pass to recordFires in auto-fire path
+- `src/runtime.ts` -- generate cohort_id, pass to recordFires in auto-fire path
 - `src/sideband.ts` -- same for MCP path
 - `src/hygiene.ts` -- add prediction dedup + constellation counts to report
 - `src/prompts.ts` -- compound minting guidance in all three prompt variants

package/docs/user/README.md

@@ -13,7 +13,7 @@ This README is the overview. Each feature has its own guide:
 - [extraction.md](extraction.md): automatic fact extraction from tool calls
 - [watchers.md](watchers.md): event-driven notifications (PR, branch, and command watching)
 - [cross-session-chat.md](cross-session-chat.md): sessions messaging each other on one machine
-- [notifications.md](notifications.md): banner and voice notifications, user config
+- [notifications.md](notifications.md): banner and voice notifications, automatic LLM alerts (pause / done / error), user config
 - [prediction-engine.md](prediction-engine.md): user decision model
 - [behavior-engine.md](behavior-engine.md): agent self-discipline rules
 - [default-behaviors.md](default-behaviors.md): what ships automatically
@@ -56,7 +56,9 @@ For local development before publishing, use a file path:
 { "plugin": ["./path/to/thatch/src/index.ts"] }
 ```
 
-Or place the thatch repo in `.opencode/plugins/` for auto-loading.
+The same file loads on both opencode lines (1.x via its `server` export,
+2.x via its default export). Or place the thatch repo in
+`.opencode/plugins/` for auto-loading.
 
 ### Claude Code
 
@@ -442,7 +444,9 @@ Most configuration needs none. Two layers exist:
 
 - **Preferences the agent manages** live in
   `~/.config/thatch/config.json` (beside the database): notification mode,
-  voice, and sound. Ask your agent ("set notifications to banner only") or
+  voice, sound, and the automatic LLM alerts (pause / done / error, each
+  independently set to banner, voice, both, or none). Ask your agent ("set
+  notifications to banner only", "silence the done alert") or
   edit the file by hand. See [notifications.md](notifications.md).
 - **Environment variables** for infrastructure:
 

package/docs/user/notifications.md

@@ -2,11 +2,19 @@
 
 Thatch can notify you out-of-band when something happens worth leaving the
 terminal for: a CI run finishing, a merge or deploy completing, a watched PR
-receiving a comment. The notification is a desktop banner, a spoken voice
-announcement, or both, depending on your preferences.
+receiving a comment, or your LLM finishing its work while you are in another
+window. The notification is a desktop banner, a spoken voice announcement, or
+both, depending on your preferences.
 
-This works on every host (opencode, Claude Code, Cursor) because it is plain
-child processes, not host plumbing.
+Two mechanisms:
+
+- **Agent-initiated** (`thatch_notify_user`): the LLM decides something is
+  worth interrupting you for and calls the tool. Works on every host
+  (opencode, Claude Code, Cursor) because it is plain child processes, not
+  host plumbing.
+- **Automatic alerts** (opencode only): the plugin watches the session and
+  notifies you when the LLM pauses for your input or finishes a round of real
+  work -- no tool call required. See the Alerts section below.
 
 ## The tools
 
@@ -74,6 +82,48 @@ The agent can manage the whole file for you through `config_get` /
 `config_set`; edits merge at the field level, so the agent changing your
 voice cannot wipe your mode.
 
+## Alerts: notifications without a tool call
+
+On opencode, the plugin watches your session and alerts you automatically:
+
+| Alert | Fires when | Default |
+|-------|-----------|---------|
+| `pause` | The LLM asks you an interactive question, or requests a permission it needs approved. | banner |
+| `done` | A round of real work finishes -- meaning the turn started from a prompt you typed AND ran at least one real tool. | banner |
+| `error` | The session fails with nothing to recover it, or opencode's inactivity sweeper kills a still-running session (a project directory quiet for 60 minutes gets its executions interrupted). Failures opencode retries through are silent, and so are turns you aborted yourself. | banner |
+
+Rounds that stay silent even when they ran real tools: anything triggered by
+async agent activity rather than a prompt you typed -- thatch's own nudges,
+background-task completions, and watcher wake-ups. On opencode v2 those
+wakes are invisible by design (the injected message is hidden from the TUI,
+and plugin toasts are unavailable), so a watcher-driven round produces no
+visible feedback at all -- that is why the silence rule exists, and why the
+escape hatch matters: the LLM sees the watcher event in its context and can
+call `thatch_notify_user` when the outcome is worth interrupting you for.
+A round delegated entirely to subagents stays silent too (the dispatch is
+bookkeeping; the child sessions never alert).
+
+Banners carry the session title, so when you juggle concurrent sessions you
+know which one spoke. Voice is opt-in per alert: set the mode to `voice` or
+`both` on the events you want spoken.
+
+```json
+{
+  "alerts": {
+    "pause": { "mode": "both" },
+    "done": { "mode": "banner" },
+    "error": { "mode": "both" }
+  }
+}
+```
+
+Each event's `mode` takes the same values as `notifications.mode`. Configure
+them the same two ways -- ask your agent, or edit `config.json` directly.
+
+When you want the LLM itself to decide something is worth interrupting you
+for (a decision it cannot make alone), that is what `thatch_notify_user` is
+for -- the automatic alerts and the tool are independent channels.
+
 ## Limitations
 
 - Banners are best-effort by nature of the OS. The agent can only report
@@ -82,3 +132,12 @@ voice cannot wipe your mode.
   are short by design.
 - There is no debounce. If an agent polls a status in a tight loop, it should
   notify once at the end, not per poll.
+- Alerts are opencode-only. Claude Code and Cursor have no plugin event
+  stream to watch; their hosts can only notify through
+  `thatch_notify_user`.
+- Alerts cannot tell whether your terminal is focused. A `done` banner can
+  land while you are looking at the TUI; set the event's mode to `none` if
+  that bothers you more than an occasional redundant banner.
+- A plugin reload or restart mid-round (a v2 plugin upgrade, a save to a dev
+  shim tree) loses that round's in-memory state and stays silent. The next
+  round alerts normally.

package/docs/user/setup.md

@@ -40,6 +40,10 @@ Before publishing, use a file path:
 { "plugin": ["./path/to/thatch/src/index.ts"] }
 ```
 
+The same file loads on both opencode lines: opencode 1.x reads its `server`
+export, opencode 2.x reads its default export (the merged plugin
+definition). No path change when you switch opencode versions.
+
 Or place the thatch repo in `.opencode/plugins/` for auto-loading.
 
 ## Claude Code

package/docs/user/watchers.md

@@ -111,9 +111,21 @@ Other tools:
 
 ## Lifetime
 
-Watchers are in-memory and process-scoped:
-
-- Ending the opencode process (or restarting it) drops all watchers.
+Watchers poll from the plugin process, and their definitions survive
+restarts:
+
+- Ending the opencode process (or restarting it) stops the polling.
+  The watch definitions are kept, though: when you resume the session
+  that created them (session picker, or reopening the tab), the
+  watches re-arm automatically on the session's first message, and a
+  notice in the conversation says what was re-armed. There is no
+  re-registration step - the policy you stated when creating the
+  watch is still there.
+- Watch definitions whose 8-hour TTL expired while the session was
+  away are not re-armed; the re-arm notice reports how many expired.
+- If a watched session is never resumed, a live session in the same
+  project hears a one-line notice that the watch died with its
+  session, so a watch that will never fire is at least explained.
 - A watcher expires after 8 hours by default.
 - Each session can hold up to 5 active watchers (all sources share
   the budget).
@@ -123,10 +135,6 @@ Watchers are in-memory and process-scoped:
   are cancelled, expire, or the process ends. Command watches are
   always one-shot.
 
-If opencode restarts while a watch is active, re-register it - the
-session's conversation survives, so the policy you stated is still
-there.
-
 ## Requirements and limitations
 
 - **opencode only.** MCP hosts (Claude Code, Cursor) have no way for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.48",
+  "version": "0.2.0",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",
@@ -30,6 +30,8 @@
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.13",
     "@opencode-ai/sdk": "1.17.13",
+    "@opencode/client": "2.0.14",
+    "@opencode/plugin": "2.0.14",
     "@types/bun": "^1.3.14",
     "markdownlint-cli2": "^0.23.0",
     "typescript": "^5.7.0",