Skip to content

Commit 07ecf87

Browse files
committed
v2 wrap-up actions, bridge toasts, and extraction-child cleanup
The opencode v2 adapter now carries the wrap-up completion actions, TUI toasts, and extraction-child cleanup that v1 reached through its TUI client routes. Wrap-ups: /thatch/compact calls session.compact on the promise domain (upstream #52385, in v2.0.22+; runtime-guarded because the pinned dev types predate the surface, so an older host degrades to a logged no-op). /thatch/exit records the session's watcher deaths synchronously BEFORE the chat unregister - onSessionDeath places the death row via the session's chat row, so the order is load-bearing - then emits the session-tab bridge's exit-tab-closed event, a TUI-only close of the session's own tab (the anomalyco/opencode#50984 ask; the v2 daemon hosts every tab, so app.exit would take down unrelated sessions). The exit template leaves the chat directory via the plugin-side unregister only: a model-side thatch_chat_unregister mid-turn would delete the chat row before the death placement can use it. Toasts: every runtime toast call site (alerts, extraction metrics, chat registration, blocked wrap-ups, watcher rearm notices) rides the bridge's new toast event to the TUI plugin's ui.toast.show. The pump never translates it; a TUI-less environment (headless run) shows nothing - best-effort by contract. Extraction-child cleanup: sessionDelete calls session.remove (upstream #52387, in v2.0.22+; same runtime guard), so fact-extractor child sessions are deleted when they finish - the session picker stays clean and -c resume cannot land in one. Older 2.x hosts keep the documented gap, degrading silently. Also: empty-targets watcher deaths write no death row (the runtime_state upsert would erase an earlier placed row for the same session); the wrap-up resolution and the death-notice delivery check disposed before journal writes; the QA v2-adapter harness lives in tests/mocks/v2-harness.ts; UC-103 gains the v2 leg (compact greenlight, exit greenlight, SDK floors, blocked toast) and UC-120 pins the child cleanup; docs updated across both tiers (opencode-plugin capability table, session-lifecycle, session-tabs, cross-session-chat, mcp-parity, READMEs).
1 parent efc95fc commit 07ecf87

24 files changed

Lines changed: 1202 additions & 185 deletions

‎README.md‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,11 @@ synchronously (fire-and-forget) instead of asynchronously.
4444

4545
The v2 plugin API is missing a few surfaces the v1 API had. On 2.x:
4646

47-
- **No toasts.** Toasts are dropped on v2 (no publish surface). The
48-
model-facing nudges they accompanied - watcher and chat wake nudges -
49-
still arrive; the extraction-result and other TUI-only toasts have no
50-
replacement.
47+
- **Toasts ride the session-tab bridge.** Every plugin toast (extraction
48+
metrics, alerts, chat registration, blocked wrap-ups) travels the
49+
session-tab rpc bridge to the TUI plugin's `ui.toast.show`. A TUI-less
50+
environment (headless run, still connecting) shows nothing - toasts are
51+
best-effort by design.
5152
- **Plugin state survives reloads.** Editing the plugin (or `opencode
5253
plugin update`) reloads it, but extraction buffers, watcher
5354
registrations, and armed wrap-ups are journaled and restored; a process
@@ -56,14 +57,23 @@ The v2 plugin API is missing a few surfaces the v1 API had. On 2.x:
5657
such a session re-arms its watches on the first message (expired ones
5758
are dropped and reported), and a live session in the same project gets a
5859
one-line notice that a dead session's watch will re-arm if resumed.
59-
- **Extraction children are visible.** The fact-extractor child sessions are
60-
top-level sessions the host cannot delete, so they accumulate in the
61-
session picker, and "continue last session" (`-c`) can land in one after
62-
any session that triggered extraction.
63-
- **`/thatch/compact` does not auto-compact.** The checklist and memory
64-
flush run, but the compaction itself cannot be triggered from the plugin
65-
API - run `/compact` yourself after the wrap-up completes. `/thatch/exit`
66-
cannot auto-exit for the same reason.
60+
- **Extraction children are visible on older 2.x builds.** Upstream exposed
61+
`session.remove` on the plugin API (v2.0.22), so the fact-extractor
62+
child sessions are deleted when they finish - the session picker stays
63+
clean. On an older 2.x build (pre-`session.remove`) the deletion
64+
degrades silently: children accumulate in the session picker, and
65+
"continue last session" (`-c`) can land in one after any session that
66+
triggered extraction.
67+
- **Wrap-up actions need a new host (compact) or an open tab (exit).** The
68+
compaction trigger rides `session.compact` on the plugin API (upstream
69+
added it in v2.0.22); on an older 2.x build the checklist and memory
70+
flush run but the compaction itself is skipped - run `/compact` yourself
71+
there. `/thatch/exit` closes the session's own tab over the session-tab
72+
bridge; with no tab open (headless run, tabs off) nothing visible happens,
73+
but the session still unregisters from chat and its watches are
74+
cancelled - on either host, and reopening or resuming the session does
75+
not re-arm them. Re-create watches you still want with
76+
`thatch_watch_create`.
6777
- **No `-c` session listing.** The chat resume listing degrades.
6878

6979
Everything else - tools, memory, nudges, chat, watchers - behaves the
@@ -210,8 +220,10 @@ Thatch gives your agent:
210220
the agent flushes pending fact extraction, finishes promised memory
211221
writes, and surfaces todos or follow-ups it never addressed. It ends its
212222
response with a greenlight token only when the checklist is clean; thatch
213-
then triggers the compaction or quits opencode. With items outstanding,
214-
the agent lists them and nothing fires -- you decide when to retry.
223+
then triggers the compaction or closes the session (its tab on opencode
224+
2, the whole app on opencode 1 - either way its watches are cancelled).
225+
With items outstanding, the agent lists them and nothing fires -- you
226+
decide when to retry.
215227
- **Notifications + user config** -- the agent can ping you out-of-band when a
216228
long-running outcome lands: a desktop banner, a spoken voice
217229
announcement, or both (macOS and Linux). On opencode, thatch also watches

‎docs/dev/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ bin/thatch → CLI: stores|list|show|forget|search|mcp|reminder|hygi
9191
| `index.ts` | Dual-shape OpenCode plugin entry: the merged default export (`{ id, setup, server }`) loads on opencode v1 (reads `default.server`) and v2 (reads `default.setup`, strips excess keys). Lazy-imports the host adapter so each host's SDK resolves only under its own runtime. |
9292
| `opencode/v1.ts` + `opencode/v2.ts` | Host adapters. v1 builds HostCapabilities from the PluginInput client and returns the hooks object; v2 registers through the promise-context domains (ToolEditor, session.hook, event.subscribe) and degrades the surfaces v2 lacks. v2 also wires the session-tab host flow (create -> move -> chat-register -> rpc emit -> prompt) through the `CoreContext.sessionTabHost` seam. |
9393
| `opencode/tui-plugin.ts` | The v2 TUI CLI plugin (the package's `./tui` entrypoint): listens for `rpc.thatch-tabs.tab-opened` and `rpc.thatch-tabs.tab-closed` events and opens/closes the subordinate session's tab via `ui.tabs.open`/`ui.tabs.close`. See [features/session-tabs.md](features/session-tabs.md). |
94-
| `capabilities.ts` | The `HostCapabilities` seam: the host operations the shared runtime needs (session create/prompt/get/list/messages/delete, toast, compaction trigger, app exit). `capabilitiesFromClient` bridges the v1 SDK client. |
94+
| `capabilities.ts` | The `HostCapabilities` seam: the host operations the shared runtime needs (session create/prompt/get/list/messages/delete, toast, compaction trigger, session close-out - app exit on v1, the session's own tab on v2). `capabilitiesFromClient` bridges the v1 SDK client. |
9595
| `runtime.ts` | Shared plugin runtime: wires DB, model, extraction; the nudge tiers, system prompt injection, session event handling, child-session bookkeeping, wrap-up resolution. Host-agnostic: consumed by both adapters. |
9696
| `os-args.ts` | Pure argv / OS-command-line helpers for startup session resolution (`-s`/`-c`). SDK-free. |
9797
| `setup.ts` | `thatch setup --claude` / `--cursor` installer. Writes MCP config (`.mcp.json` / `.cursor/mcp.json`), appends to CLAUDE.md / AGENTS.md (idempotent), installs hooks in settings.json / hooks.json, installs skills. |
@@ -129,7 +129,7 @@ methods. The v1 hook shapes:
129129
|------|-------------|
130130
| `experimental.chat.system.transform` | Appends the thatch system prompt (store names, usage rules). |
131131
| `experimental.session.compacting` | Marks the session as compacting and appends re-familiarization context so a compacted session still knows thatch exists. |
132-
| `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the TUI action (`session_compact` via `executeCommand`, `app.exit` via `publish`; the exit path unregisters the session from the chat directory first). See [features/session-lifecycle.md](features/session-lifecycle.md). |
132+
| `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the host action (compact: v1 `session_compact` via `executeCommand`, v2 `session.compact` on the promise domain; exit: record the session's watcher deaths, unregister it from chat, then v1 `app.exit` via `publish` or v2 the exit-tab-closed rpc event closing the session's own tab). See [features/session-lifecycle.md](features/session-lifecycle.md). |
133133
| `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
134134
| `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. For `thatch_chat_*` tool calls, builds the transcript echo (`chatEchoText`) and posts it as a visible non-synthetic `noReply` part. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
135135
| `chat.message` | Recall nudge: embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges fire independently in separate try/catch blocks with separate synthetic parts. There is deliberately NO extraction nudge here - extraction is plugin-driven at session idle (see the extraction feature doc); the old model-driven handshake raced its own state machine and was removed. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation), and for task-dispatched sub-agent sessions (`childToParent` without `extractionChildren`) - their tool lists may exclude the thatch tools and their work is driven by the dispatch prompt. |
@@ -268,14 +268,16 @@ extraction cycle
268268
→ MCP path (Claude Code/Cursor): unchanged — no SDK client, no child
269269
sessions; extract-queue.ts + flush-tools drives the nudge via hooks
270270
271-
toast notifications (opencode-only, TUI-rendered)
271+
toast notifications (opencode-only, TUI-rendered; the bridge's toast
272+
event -> the TUI plugin's ui.toast.show on v2)
272273
→ client.tui.showToast — best-effort, silently ignored if TUI not
273274
connected (headless mode); model-invisible (goes to the user only,
274275
not the conversation history — the inverse of synthetic nudge parts,
275276
which are model-visible but TUI-hidden)
276277
→ extraction metrics: `[thatch] new: N, updated: M, deleted: K` (success
277-
variant, 4s) — fires when an extraction child goes idle; no-save runs
278-
show `[thatch] extraction complete — nothing to save` (info variant)
278+
variant, 4s) — fires when an extraction child goes idle, but ONLY when
279+
memories were actually written; no-save runs show nothing (no
280+
notification fatigue)
279281
→ recall matches: `[thatch] recalled N memories` (info variant, 3s) —
280282
fires when chat.message matches stored memories
281283
→ prediction matches: `[thatch] N predictions surfaced` (info variant,

‎docs/dev/features/cross-session-chat.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -146,10 +146,10 @@ mechanical barrier, a documented trust posture.
146146
### Leave tombstones
147147

148148
Every exit path - `chat_unregister`, `session.deleted`, and a greenlit
149-
`/thatch/exit` (the plugin unregisters the exiting session before
150-
publishing `app.exit`, so the roster stops advertising a host that is
151-
about to vanish; the exit template's checklist step asks the model to do
152-
the same earlier) - writes a
149+
`/thatch/exit` (the plugin unregisters the exiting session before the
150+
host close-out - v1 publishes `app.exit`, v2 closes the session's own
151+
tab - so the roster stops advertising a host that is about to vanish)
152+
- writes a
153153
`chat_leave_tombstones` row in the same transaction that deletes the
154154
directory row. The tombstone is what makes a leave stick: all
155155
registration paths consult it (the plugin's idle and prompt auto-registerers are

0 commit comments

Comments
 (0)