You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c508fd4
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: docs/dev/README.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,7 @@
1
1
# Development
2
2
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
+
3
5
## Architecture
4
6
5
7
Thatch has three integration paths sharing a common core:
|`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). |
85
87
|`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. |
86
88
|`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. |
89
91
|`os-args.ts`| Pure argv / OS-command-line helpers for startup session resolution (`-s`/`-c`). SDK-free. |
|`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. |
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.
17
17
18
18
Key details:
19
19
-`id-token: write` permission lets npm authenticate through GitHub's OIDC exchange
Copy file name to clipboardExpand all lines: docs/dev/features/opencode-plugin.md
+26-13Lines changed: 26 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,31 +59,44 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
59
59
|---|---|---|---|
60
60
| 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) |
61
61
| 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|
| 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) |
65
65
| 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|
67
67
| 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) |
68
68
| synthetic wake deliveries |`promptAsync` with `synthetic` parts |`session.synthetic` endpoint | watcher + chat wake nudges route to v2's synthetic endpoint (TUI-hidden), matching v1 |
69
69
| 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) |
70
70
| session status |`client.session.status`| none | returns `{}`; the wake gate treats unknown as idle and the event-fed status map does the gating |
71
71
| 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) |
72
72
| 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) |
74
74
| toasts |`client.tui.showToast`| none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context) |
| 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)) |
76
76
| 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 |
77
77
78
-
## Smoke-test-gated unknowns
78
+
## Live verification and remaining unknowns
79
79
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
Copy file name to clipboardExpand all lines: docs/dev/features/session-lifecycle.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,7 @@
1
1
# Session Lifecycle Management (opencode)
2
2
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
+
3
5
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.
0 commit comments