feat(opencode): add OpenCode v2 plugin adapter and setup opencode-v2 command

[ScorpionConMate]

🔍 Problem Description

OpenCode 2.x introduced a new plugin API. The OpenCode adapter installed by engram setup opencode targets the 1.x plugin API, so on OpenCode 2.x it fails to load at startup and every plugin feature is silently inactive:

level=WARN message="failed to load plugin" target=~/.config/opencode/plugins/engram.ts
cause="PluginModule.LoadError: Plugin must export a default definition with an id and an effect or setup function.
(cause: SchemaError(Missing key at [\"default\"]))"

OpenCode's migration guide is explicit: "V1 plugin implementations do not run in V2." A V2 plugin must export default Plugin.define({ id, setup }) (from @opencode/plugin) instead of exporting an async function from @opencode-ai/plugin. The current adapter does export const Engram: Plugin = async (ctx) => ({ event, "chat.message", "tool.execute.after", "experimental.chat.system.transform", "experimental.session.compacting" }), so the V2 loader finds no default export and rejects the module.

Impact on OpenCode 2.x: no Memory Protocol injection, no prompt capture, no session registration/tracking, no save nudges, no compaction context, no passive capture. The MCP server still connects (engram mcp), so manual memory tools keep working — which is why the regression is quiet.

Reproduced on opencode 2.0.4 (stable channel) / engram 1.20.0, at every server start and for every project location.

💡 Proposed Solution

Add a V2 adapter and a dedicated setup command, leaving the 1.x path untouched:

1. New adapter at plugin/opencode-v2/engram.ts, embedded through internal/setup/plugins/opencode-v2/ (same go:embed pattern as the current one).
2. New agent entry: engram setup opencode-v2, installed to the same destination ~/.config/opencode/plugins/engram.ts — OpenCode auto-discovers that path in both 1.x and 2.x. MCP registration needs a V2-aware injector: V2 config uses mcp.servers.<name> with disabled: false, while the current injectOpenCodeMCP() writes the 1.x shape (mcp.<name> with enabled: true).
3. engram setup opencode stays as-is for 1.x. Nice-to-have: each command detects the installed OpenCode version (opencode --version) and hints at the other command when it does not match.
4. Port the hooks to the V2 domain API:

1.x	V2
export const Engram: Plugin = async (ctx) => ...	export default Plugin.define({ id: "engram", async setup(ctx) { ... } })
event	ctx.event.subscribe() (cleanup via AbortController)
chat.message	ctx.session.hook("prompt", ...) — text comes from event.prompt.text
tool.execute.after	ctx.tool.hook("execute.after", ...)
experimental.chat.system.transform	ctx.session.hook("context", ...) — append to event.system
experimental.session.compacting	ctx.session.hook("compaction", ...) — exact injection point to validate
ctx.directory	ctx.location.directory

5. Avoid Bun globals in the V2 adapter (Bun.spawn, Bun.spawnSync, Bun.file, Bun.which) — use node:child_process / node:fs instead. See Plugin assumes a Bun runtime, but opencode's plugin host has no Bun global (plugin is silently inert) #1218: OpenCode's plugin host has no Bun global, so a Bun-based adapter would load but stay inert.
6. Add @opencode/plugin (matching the target OpenCode release, 2.0.4 today) as the adapter's type dependency.

Behavior parity to preserve: ensureSession(), prompt capture (truncate 2000, <private> stripping), ENGRAM_TOOLS filtering, Memory Protocol appended to the last system entry (single-system-block compatibility), nudge debounce, compaction context, passive capture, ENGRAM_PORT / ENGRAM_BIN / ENGRAM_NUDGE_COOLDOWN_SECS overrides, sub-agent session suppression (#116), and the ENGRAM_BIN absolute-path patch applied by the installer.

📦 Affected Area

CLI (commands, flags)

🔄 Alternatives Considered

• One adapter supporting both APIs: OpenCode 1.18.29+ accepts a default export with both setup() (V2) and server() (V1), but the two hook APIs are different domains and do not translate automatically — both implementations would still be needed in one file, and OpenCode < 1.18.29 would stop working. Two files + two commands is clearer and keeps the 1.x path frozen.
• Auto-detect inside engram setup opencode: no new command, but it silently changes the installed adapter for everyone; a dedicated command is more explicit and lets the V2 adapter evolve at its own pace.
• Do nothing: not viable; OpenCode 2.x is the current stable line and the V1 adapter already fails on every start.

📎 Additional Context

• OpenCode V2 plugin docs: https://opencode.ai/v2/docs/build/plugins · Migration guide: https://opencode.ai/v2/docs/build/plugins/migrate-v1
• Server log evidence from a fresh 2.0.4 start shows discovery still works (msg="loading plugin" entrypoint=file://<home>/.config/opencode/plugins/engram.ts) and only the module shape is rejected.
• Related but distinct: Plugin assumes a Bun runtime, but opencode's plugin host has no Bun global (plugin is silently inert) #1218 (V1 plugin host has no Bun global).
• I can open a PR with the V2 adapter and the opencode-v2 setup entry once this issue is approved.

[ScorpionConMate]

Implementation is ready on a fork: ScorpionConMate/engram → branch feat/opencode-v2-adapter (commit 6191ab2).

It adds the V2 adapter (plugin/opencode-v2/engram.ts), engram setup opencode-v2, V2 MCP registration under mcp.servers, tests, and docs. engram setup opencode and the 1.x adapter stay untouched. I'll open the PR as soon as this issue is approved — happy to adjust naming or scope first.

[Sam-Max]

One side effect of engram setup opencode not covered in the description.

The command also enables a third-party TUI plugin in tui.json:

Also enabled: opencode-subagent-statusline in tui.json — sub-agent activity in the sidebar/footer.

Reproduced in a throwaway HOME (HOME=/tmp/x engram setup opencode):

// ~/.config/opencode/tui.json
{ "plugin": ["opencode-subagent-statusline"] }

tui.json is a V1 file: V2 reads it only as a migration source into cli.json, whose plugin entries live under plugins (plural). So that registration lands in the wrong place for OpenCode 2.x.

Two related install behaviors I verified while checking this, on OpenCode 2.0.7 with node v22.23.2:

$ opencode plugin add opencode-subagent-statusline
Plugin "opencode-subagent-statusline" installed and added to <config>/opencode.json   # ok

$ opencode plugin add opencode-sdd-engram-manage
ERROR (#1): NpmInstallFailedError
    [cause]: Error: unable to resolve dependency tree

The differentiator is engines, not the peer range:

opencode-sdd-engram-manage@1.7.0    engines: { "node": ">=24 <25" }   -> fails here (node 22.23.2)
opencode-subagent-statusline@1.3.0  engines: { "node": ">=22.13" }    -> installs

Whether the statusline package loads and runs under V2 is unverified — installing is not loading, and I did not launch a TUI to test it. Worth checking when feat/opencode-v2-adapter lands.

The main report still reproduces on engram 2.0.0 stable and OpenCode 2.0.7.

[ScorpionConMate]

Hi @Sam-Max !
Thanks for the observation! opencode-subagent-statusline is a separate third-party plugin from this adapter. This PR just scopes the V2 works to the adapter and MCP registration, we can track the TUI plugin migration/adapter separately once its v2 runtime compatibility is verified

[juanvs23]

Data point for the V2 adapter: the hook mapping in this issue is correct, and it works on OpenCode 2.0.10.

I ported the installed 1.x adapter locally using exactly that table and verified end to end:

• 6/6 local plugins load with 0 failed to load plugin entries after a service restart
• execute.before and session.created both register sessions in Engram
• session.deleted closes them
• MCP mem_save works again

Three notes that may save a round of debugging:

1. ctx.event.subscribe() returns an AsyncIterable, not a callback-registration API. It must be consumed with for await (const event of ctx.event.subscribe({ signal })).
2. For "experimental.session.compacting" → ctx.session.hook("compaction"), the injected context belongs in event.system (SystemPart[]), not event.messages: messages is the transcript being summarized, so pushing there injects fake turns.
3. V2 has no session.updated event. A session that reveals a parentID only after creation therefore stays cached as a root, which is the session-inflation risk tracked in Session Counting Inflation: Task executions counted as user sessions (170x discrepancy) #116. The 1.x adapter handled this via session.updated; the port loses it.

[dnlrsls]

Design refinement for #1220 / #1240: keep a dedicated V2 adapter and engram setup opencode-v2. The V1 and V2 plugin APIs and MCP config shapes differ, so a cross-version adapter or generic installer framework would increase coupling without removing the version-specific behavior. The generated embedded copy is an installation artifact, not a second implementation.

Preserve the existing session ownership checks and durable inbox-based prompt deduplication: V2 can replay admission events, and an in-memory guard would not survive restart. Keep the V1 adapter and its config path unchanged. The only implementation cleanup in this follow-up is to remove the unused toolCounts bookkeeping from the V2 adapter (and regenerate its embedded copy); no behavior, schema, or hook changes. We can revisit the repeated installer file-copy plumbing if a third integration creates a real shared use case.

[dnlrsls]

Follow-up to the design refinement above: review of the full PR (separate from the small dead-counter cleanup) found two candidate-caused issues, now fixed in the V2 adapter. An admitted prompt is redacted before the 2,000-character truncation, preventing a private span crossing that boundary from reaching HTTP. The synchronous engram instance-id lookup now has a 2-second timeout so a stuck binary cannot block the plugin host indefinitely. Both changes have focused regression coverage in plugin/opencode-v2/engram.test.mjs; the V1 path remains untouched. This is still a targeted V2 correction, not a cross-version abstraction. Fix commit: 810708d.

[FR33TR1ST]

Still reproduces on OpenCode 2.0.18 with engram 2.2.1, so the version range in the description can be widened from 2.0.4 / 1.20.0.

Confirmed the 1.x template is still the one being shipped. Grepping the 2.2.1 binary finds export default { id: "engram", server: Engram } and zero Plugin.define occurrences, with @opencode-ai/plugin imported and no reference to @opencode/plugin. So engram setup opencode keeps writing the 1.x adapter on current releases, and gentle-ai sync regenerates the same file.

Data point for the adapter itself: installed plugin/opencode-v2/engram.ts from ScorpionConMate/engram@feat/opencode-v2-adapter on OpenCode 2.0.18, and all six local server plugins now load clean (every default export resolves to [id, setup], zero failed to load plugin entries). That matches what @juanvs23 reported on 2.0.10.

[dnlrsls]

Design checkpoint for #1220: I am revisiting my earlier preference for a dedicated V2 adapter in #1240. #1526 shows a smaller shared V1/V2 adapter may be viable: main already has a V1 default export, and the author reports real V2 plugin/MCP loading. This is a change in assessment, not a decision to replace the contributor work silently. Thanks to @ScorpionConMate for the V2 hook mapping and durable inbox-admission foundation.

Neither PR is ready for the merge queue. I requested changes on #1526 because its V2 prompt path drops the durable inbox ID and inherits a truncate-before-redact leak. #1240 retains inbox identity but still needs the installed ENGRAM_BIN path and delete/replay blockers resolved. We will compare corrected final heads against the same real-host V1/V2 and persistence criteria, credit the work, and merge only one validated implementation. No merge or PR closure now.

[dnlrsls]

Following the narrowed #1270 acceptance, please make the V2 adapter review prove the client boundary rather than just the hook callback: in isolated HOME/XDG/Engram storage, run an actual OpenCode V2 client → external Engram MCP tool → temporary SQLite write for two host sessions when a deterministic invocation path exists. #1485 already tests the V1 adapter against a real HTTP/store but manually forwards /observations, so it does not prove OpenCode MCP dispatch. If V2 cannot invoke a tool offline without a provider, document that limitation and an explicit operator verification step instead of claiming the simulated wrapper is end-to-end coverage. This is a proposed acceptance refinement for #1220, not a claim that V2 currently supports the V1 adapter.

[jorgehn98]

Still reproduces on the current pair: OpenCode 2.0.19 + engram 2.2.1.

failed to load plugin target=~/.config/opencode/plugins/engram.ts
Plugin must export a default definition with an id and an effect or setup function.
(cause: SchemaError(Missing key at ["default"]["effect"], ["default"]["setup"]))

One detail that makes this easy to under-prioritize: the MCP side keeps working. opencode mcp list reports engram connected and the memory protocol still reaches the model through the MCP server instructions. So the only visible symptom is the TUI banner, while session registration, prompt capture and compaction context are silently missing.

The only workaround users have today is moving the generated adapter out of plugins/ so the loader stops retrying it on every reload, and repeating that after each engram setup opencode.

Also confirmed: the opencode-subagent-statusline entry written into tui.json/tui.jsonc is a no-op on 2.x — V2 reads that file only as a migration source into cli.json, where plugins live under plugins and expect a { id, tui } entrypoint.

We have a clean 2.0.19 host and can test whichever candidate head you pick (#1240 or #1526) end to end: plugin load, session registration, compaction injection and prompt capture. If a real-host comparison is what is blocking the merge decision, say which head and we will run it.

[jorgehn98]

Ran the preferred candidate (#1526, head 4b89b89) against a clean host: OpenCode 2.0.19, node v24.18.0, engram 2.2.1, isolated HOME/XDG_*/ENGRAM_DATA_DIR and a private ENGRAM_PORT.

Local suites: engram.v2.test.mjs 23/23 pass; engram.test.mjs 88/89, the single failure being environmental (go build ENOENT — Go is not installed here), not a regression.

Real host, no provider needed (private opencode serve, isolated config with the branch adapter in plugins/):

• msg="loading plugin" ... engram.ts and zero failed to load plugin entries
• mcp connected server=engram tools=19
• session.created → row written to the isolated store with started_at
• session.deleted → same row gains ended_at
• prompt admission → prompt row in the isolated store with the right session_id/project
• MCP registration is accepted with both mcp.servers.engram and the V1 flat mcp.engram shape, so the docs/PLUGINS.md claim that one engram setup opencode covers both majors holds on 2.0.19

Two notes on the current blockers:

1. source_inbox_id cannot be validated against a released server: zero occurrences in the 2.2.1 binary and none in the branch's Go source, and chore(review): track prompt inbox identity foundation chain #1464 is still open. engram.v2.real-server.test.mjs asserts replay dedup and the 409-after-delete path against a real server, so it cannot pass against its own base — which is also why it is not in CI (node --test plugin/opencode/engram.test.mjs plugin/opencode/engram.v2.test.mjs). The adapter side does keep durable identity: it sends source_inbox_id and the unit suite covers replay, distinct-identical-text, and deleted identity. On 2.2.1 the doc's own caveat applies: capture works, dedup does not. Worth deciding explicitly whether that test is gated on chore(review): track prompt inbox identity foundation chain #1464 or dropped from the required set.
2. The redact-before-truncate concern is covered by the passing "redacts a private block that straddles the truncation limit" test.

Not covered here, per your acceptance note: the model-bound path (ctx.session.hook("context") protocol injection, compaction, tool hooks) and the client → Engram MCP tool → SQLite write. A private server without a provider cannot dispatch a tool. If you want that boundary proven, say which head to use and we will run it with a real provider in the same isolated layout and report the SQLite receipts.

[jorgehn98]

Follow-up: the model-bound boundary is covered on the same candidate (#1526, head 4b89b89), on the same isolated host (OpenCode 2.0.19, private opencode serve, isolated HOME/XDG_*/ENGRAM_DATA_DIR, private ENGRAM_PORT).

Two host sessions, each given one instruction to call the Engram MCP tool through Code Mode. Both turns ran on gpt-6-sol (agent build) and finished stop with DONE, with tool-calls in between.

SQLite receipts in the isolated store, correctly attributed per session:

• #3 discovery "V2 host session A" → session_id = ses_f125958bfffeyDKIDJbtuzQVs0
• #5 discovery "V2 host session B" → session_id = ses_f125958adffeyXBQFkkrBxcgqR
• the two session_summary rows, each bound to its own session

Both sessions registered with started_at, and zero failed to load plugin entries. The only remaining gap is the source_inbox_id replay/409 behavior, which still needs #1464.