Skip to content

Commit c508fd4

Browse files
committed
Round-2 review: degrades, casts, docs, and cleanup
- compaction trigger: verified unreachable (the promise domain has no session.compact, and the built-in /compact is a TUI palette action calling the server endpoint directly - the command registry only knows config/plugin-registered names); PR body and plan now say degraded - session capabilities typed against the SDK's SessionDomain instead of as-casts; tsc then surfaced that the promise client returns unwrapped values (SessionInfo, SessionMessageInfo[]) - envelope peeking removed - event pump narrowed to the fields it consumes instead of any - tool buffering: deriveTitle supplies entry titles (v2's Tool.Result has no title; the doc row claiming the buffer derives one was wrong - deriveTitle only ran on the MCP host path) - wrap-up args: function replacer so dollar sequences in user text survive; contract test covers the $$ case - armWrapUp folded into onCommandExecuteBefore; tuiExecuteCommand/ tuiPublish renamed to compactSession/exitHost (no string protocol in the adapters) - @opencode/plugin moved to devDependencies (type-only usage; the host supplies the context) - stale comments/docs corrected: v2 adapter header (all SMOKE TEST markers replaced with verified findings), capabilities docstrings, runtime comments, dev doc rows, README 2.x caveats section, plans doc status; stale line citations switched to symbol names - publish.yml: the test job now runs the full CI gate (the tag push does not trigger ci.yml) and the publish job no longer re-runs tests - new isolation probe: a subprocess test loads the v2 adapter with @opencode-ai/plugin throwing on require (simulated absence on v2 user installs); negative control verified the probe detects a violation
1 parent 8604a6d commit c508fd4

23 files changed

Lines changed: 362 additions & 216 deletions

‎.github/workflows/publish.yml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,9 @@ permissions:
1313
issues: write
1414

1515
jobs:
16-
# Mirror CI's dual-runtime matrix: a release must not ship on a runtime
17-
# the plugin will actually run under (opencode v2 embeds Bun 1.4.2).
16+
# Release gate: the same checks CI runs (the tag push itself does not
17+
# trigger ci.yml), across the dual-runtime matrix a release must pass on
18+
# (opencode v1 embeds Bun 1.3.14; v2 embeds 1.4.2).
1819
test:
1920
runs-on: ubuntu-latest
2021
strategy:
@@ -26,7 +27,9 @@ jobs:
2627
with:
2728
bun-version: ${{ matrix.bun-version }}
2829
- run: bun install
30+
- run: bunx tsc -p tsconfig.check.json
2931
- run: bun test tests/*.test.ts
32+
- run: bunx markdownlint-cli2
3033

3134
publish:
3235
needs: test
@@ -37,7 +40,6 @@ jobs:
3740
with:
3841
bun-version: "1.3.14"
3942
- run: bun install
40-
- run: bun test tests/*.test.ts
4143
# OIDC publish needs npm >= 11.5.1. setup-node installs into the
4244
# user-writable tool cache (the runner's stock node in /usr/local is
4345
# root-owned, so npm can't self-upgrade there). Deliberately NO

‎README.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,8 @@ everything runs on your machine.
2222

2323
On next start, OpenCode npm-installs thatch and its tools are available
2424
immediately. Works with both opencode 1.x and 2.x (the same package supports
25-
both plugin APIs). Note: the published npm release must be >= the first
26-
version with v2 support -- until the next release ships, npm's `latest`
27-
still targets 1.x only. For async extraction (child sessions run in the
25+
both plugin APIs). Until the next release ships, npm's `latest` still
26+
targets 1.x only. For async extraction (child sessions run in the
2827
background):
2928

3029
```bash
@@ -34,6 +33,25 @@ export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
3433
Without this env var, extraction still works - the child session runs
3534
synchronously (fire-and-forget) instead of asynchronously.
3635

36+
### What works in opencode 2.x
37+
38+
The v2 plugin API is missing a few surfaces the v1 API had. On 2.x:
39+
40+
- **No toasts.** Notifications (extraction results, watcher events) land in
41+
the conversation instead of the TUI's toast area.
42+
- **Extraction children are visible.** The fact-extractor child sessions are
43+
top-level sessions the host cannot delete, so they accumulate in the
44+
session picker, and "continue last session" (`-c`) can land in one after
45+
any session that triggered extraction.
46+
- **`/thatch/compact` does not auto-compact.** The checklist and memory
47+
flush run, but the compaction itself cannot be triggered from the plugin
48+
API - run `/compact` yourself after the wrap-up completes. `/thatch/exit`
49+
cannot auto-exit for the same reason.
50+
- **No `-c` session listing.** The chat resume listing degrades.
51+
52+
Everything else - tools, memory, nudges, chat, watchers - behaves the same
53+
on both versions.
54+
3755
Then **prime your project memory** by running `thatch prime` in your project directory.
3856
This launches an `opencode` session to build an initial map of the code base
3957
and seed the memory.

‎bun.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/dev/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Development
22

3+
Feature docs describe behavior in opencode v1 `client.*` terms; the opencode v2 equivalents and degrades are catalogued in [features/opencode-plugin.md](features/opencode-plugin.md).
4+
35
## Architecture
46

57
Thatch has three integration paths sharing a common core:
@@ -84,8 +86,8 @@ bin/thatch → CLI: stores|list|show|forget|search|mcp|reminder|hygi
8486
| `mcp.ts` | Stdio JSON-RPC 2.0 server. Compiles zod schemas to JSON Schema via `z.toJSONSchema()` for `tools/list`. Validates args via `z.object().parse()` in `tools/call`. All logging to stderr (stdout is the transport). |
8587
| `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. |
8688
| `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. |
87-
| `capabilities.ts` | The `HostCapabilities` seam: the host operations the shared runtime needs (session create/prompt/get/list/messages/delete, toast, TUI actions). `capabilitiesFromClient` bridges the v1 SDK client. |
88-
| `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. |
89+
| `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. |
90+
| `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. |
8991
| `os-args.ts` | Pure argv / OS-command-line helpers for startup session resolution (`-s`/`-c`). SDK-free. |
9092
| `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. |
9193
| `hygiene.ts` | Hygiene report: pending dedup pairs, stale count, orphaned branch memories. Shared by the plugin's session-start hook and the CLI's `thatch reminder` command. |

‎docs/dev/features/cicd.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ The CI gate is the never-merge-broken guard before a release. All three must pas
1313

1414
## Publish pipeline (.github/workflows/publish.yml)
1515

16-
Triggered by pushing a `v*` tag. Publishes to npm via OIDC trusted publishing — no stored npm token.
16+
Triggered by pushing a `v*` tag. Publishes to npm via OIDC trusted publishing — no stored npm token. The tag push does not trigger ci.yml, so the publish workflow re-runs the full CI gate (typecheck, tests, markdownlint) across the same dual-Bun matrix as its own release gate.
1717

1818
Key details:
1919
- `id-token: write` permission lets npm authenticate through GitHub's OIDC exchange

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Cross-Session Chat
22

3+
Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
4+
35
Cross-session chat lets independent opencode sessions on one machine message
46
each other through thatch: sessions join a shared directory (automatically,
57
under assigned names), see each other in the list, and messages land in

‎docs/dev/features/hygiene.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Hygiene System
22

3+
Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
4+
35
Store maintenance signals surfaced at session start. The plugin never deletes
46
memories itself — it surfaces problems and lets the agent tend the store.
57

‎docs/dev/features/nudge-pipeline.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Per-Message Nudge Pipeline
22

3+
Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
4+
35
Runs on every user message. Four priority tiers share one embedding
46
computation. The pipeline injects *synthetic parts*---text the model sees in
57
the conversation but the user does not see in the TUI. This is the inverse of

‎docs/dev/features/opencode-plugin.md‎

Lines changed: 26 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -59,31 +59,44 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
5959
|---|---|---|---|
6060
| bus events | `event` hook | `event.subscribe` (raw SSE) | client-side location filter; location-less events resolve via `session.get` (`{sessionID}` input) and drop unresolvable (mirrors v1's server-side filter); events for plugin-created extraction children pass by ID (they live in the project directory, which differs from the instance directory on below-root launches) |
6161
| incoming message | `chat.message` hook | `session.hook("prompt")` | the hook awaits the runtime; nudge injections append to the OUTBOUND request's last user message in the generate hook (v2 wire `Message` carries parts in `content`, not `parts`) |
62-
| system prompt | `experimental.chat.system.transform` | `session.hook("context")` | mutates the request's system array; the runtime pushes a raw string where v2 types SystemPart (smoke-test-gated) |
62+
| system prompt | `experimental.chat.system.transform` | `session.hook("context")` | mutates the request's system array; the runtime's plain strings convert to `{type: "text", text}` SystemPart objects at the boundary |
6363
| compaction | `experimental.session.compacting` + `.autocontinue` + `session.compacted` | `session.hook("compaction")` | flag lands; context-injection surface unverified |
64-
| wrap-up commands | `command.execute.before` + command files | `command.transform` + `CommandEditor.add` | registered in code: `execute` arms the greenlight check (`armWrapUp`) and delivers the same prompt body the v1 file carries, substituting the invocation's prompt text for `$ARGUMENTS` (v2's `session.prompt` does no template expansion); the runtime installs only ACTION command files on v2 and REMOVES stale wrap-up files from earlier v1 runs (a file and a registered command with the same name would collide) |
64+
| wrap-up commands | `command.execute.before` + command files | `command.transform` + `CommandEditor.add` | registered in code: `execute` arms the greenlight check (`onCommandExecuteBefore`) and delivers the same prompt body the v1 file carries, substituting the invocation's prompt text for `$ARGUMENTS` (v2's `session.prompt` does no template expansion); the runtime installs only ACTION command files on v2 and REMOVES stale wrap-up files from earlier v1 runs (a file and a registered command with the same name would collide) |
6565
| tools | `hooks.tool` map via `tool()` | `tool.transform` + `ToolEditor.add` | zod shapes pre-converted to JSON Schema with our own zod (v2's `instanceof $ZodType` detection fails for ours and drops the schema); results wrap as `{ content }` |
66-
| tool buffering | `tool.execute.after` hook | `tool.hook("execute.after")` | wired: feeds the same extraction buffer; `Tool.Result.content` is flattened (string passes through, content-part arrays contribute their text parts), title is left empty (the buffer's `deriveTitle` synthesizes one) |
66+
| tool buffering | `tool.execute.after` hook | `tool.hook("execute.after")` | wired: feeds the same extraction buffer; `Tool.Result.content` is flattened (string passes through, content-part arrays contribute their text parts); the title is derived from the tool name and args (`deriveTitle`), since v2's `Tool.Result.output` is a typed output value, not a title |
6767
| noReply deliveries | `promptAsync` with `noReply` | none | gated off via `HostCapabilities.noReplyDelivery` -- chat echoes and the session-start reminder are skipped on v2 (delivering them would start real model turns: a feedback loop) |
6868
| synthetic wake deliveries | `promptAsync` with `synthetic` parts | `session.synthetic` endpoint | watcher + chat wake nudges route to v2's synthetic endpoint (TUI-hidden), matching v1 |
6969
| child sessions | `client.session.create/promptAsync/prompt/delete` | `session.create/prompt` | create+prompt supported (a missing id throws into the extraction fallback); delete degrades (extraction children are not cleaned up on v2 -- the session picker accumulates one `thatch-extraction` entry per extraction, and `-c` "continue last session" logic that picks the newest top-level session will land in an extraction child after any session that triggered extraction) |
7070
| session status | `client.session.status` | none | returns `{}`; the wake gate treats unknown as idle and the event-fed status map does the gating |
7171
| session messages | `client.session.messages` | `session.context` | mapped into the v1 `{info: {role}, parts}` shape, so the wrap-up greenlight check works (the promise domain has no `message` accessor) |
7272
| session list | `client.session.list` | none | degrade (`-c` resume listing loses its data source) |
73-
| compaction trigger | `client.tui.executeCommand("session_compact")` | none | degrade (the promise domain's SessionDomain Pick has no `session.compact`; the wrap-up checklist and flush still run, only the automatic compaction is skipped) |
73+
| compaction trigger | `client.tui.executeCommand("session_compact")` | none | degrade (no `session.compact` on the promise domain's Pick, and the built-in `/compact` is a TUI palette action calling the server endpoint directly - the server command registry only knows config/plugin-registered names; the wrap-up checklist and flush still run, the automatic compaction is skipped) |
7474
| toasts | `client.tui.showToast` | none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context) |
75-
| TUI actions | `client.tui.executeCommand/publish` | none | degrade (except the compaction trigger, handled above) |
75+
| TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the process exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984)) |
7676
| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges |
7777

78-
## Smoke-test-gated unknowns
78+
## Live verification and remaining unknowns
7979

80-
The v2 adapter was written against tagged source (v2.0.9) without a live
81-
binary. Items marked SMOKE TEST in src/opencode/v2.ts were verified against
82-
a real v2.0.15 binary on 2026-09-23: merged-default loading, tool schemas
83-
(via pre-converted JSON Schema - see the gotcha), event shapes, the
84-
execution-lifecycle idle signal, synthetic wake delivery, and command
85-
registration all work. The app-exit gap (no server-side publish surface for
86-
`tui.command.execute`) is upstream:
80+
The v2 adapter was written against tagged source (v2.0.9) before a live
81+
binary was available, then verified against a real v2.0.15 binary on
82+
2026-09-23: merged-default loading, tool schemas (via pre-converted JSON
83+
Schema - see the gotcha), event shapes, the execution-lifecycle idle signal,
84+
synthetic wake delivery, and command registration all work; the full QA
85+
suite runs green against a v2 serve.
86+
87+
Still unverified against the live binary (static analysis only):
88+
89+
- Whether `session.hook("prompt")` fires for `session.synthetic` inbox
90+
items. If it does not, `pendingInjections` from the prior real turn gets
91+
appended to the synthetic turn's outbound request.
92+
- Whether `SessionGenerate.messages` are fresh objects per model call within
93+
a turn. If not, the generate hook pushes duplicate nudges on every tool
94+
round trip.
95+
- An npm-installed copy (not the dev checkout, which has devDependencies
96+
present) loading under v2 - the isolation rule's real-world proof.
97+
98+
The app-exit gap (no server-side publish surface for `tui.command.execute`)
99+
is upstream:
87100
[anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984).
88101
Install opencode-v2 (brew formula `anomalyco/tap/opencode-v2`; conflicts
89102
with the v1 formula's binary name, so it cannot coexist) and re-run the QA

‎docs/dev/features/session-lifecycle.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Session Lifecycle Management (opencode)
22

3+
Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
4+
35
opencode emits bus events for session lifecycle changes. Thatch subscribes to these events to manage the extraction pipeline, send session-start reminders, handle child session cleanup, and resolve wrap-up commands.
46

57
## What it does

0 commit comments

Comments
 (0)