Port server entry + orchestrator to v2 plugin contract

[frap129]

Question

Rework the server plugin entry (src/index.ts) and orchestrator (src/runtime/orchestrator.ts) to the v2 module contract: default export { id, setup(ctx) } instead of { id, server: async (input) => hooks }.

Key work:

• v2 loads only the default export; the __testOnly named-export workaround is dead code — retire it, moving test seams to wherever the v2 contract offers (constructor injection, or a separate export consumed only by tests via direct import, e.g. a createRuntime() factory in a non-entry module).
• Wire v2 hooks: ctx.tool.hook("execute.before"|"execute.after", ...) (payloads changed: before has mutable input, rejection via Tool.Error; after has { status, result?/error? } with mutable result), ctx.session.hook("context", ...) for transient injection, ctx.session.synthetic(...) for durable injection (replaces the chat.message hook path), and ctx.session.prompt(..., { resume: false }) for the awaited no-reply admission.
• pluginInput.client → the v2 plugin context is itself the client (ctx.session, etc.); adapt src/runtime/client-adapter.ts.
• Note: v2 synthetic messages do NOT run prompt hooks; check whether chat-capture.ts (which reads chat.message input for model/agent tracking) has a v2 source of truth (e.g. context hook event fields, or ctx.session.context).
• Keep hooks' registration signature aligned with packages/plugin/src/promise/{tool,session}.ts from the sst/opencode beta branch.

[frap129]

Resolution

The server entry and orchestrator now run on the v2 plugin contract (@opencode-ai/plugin@0.0.0-beta-18999, pinned to the npm beta dist-tag). Lint, tsc --noEmit, and all 547 tests pass; aube run build succeeds.

Entry port

• src/index.ts default-exports { id, setup(ctx) } satisfying Plugin.Plugin (Plugin is a namespace re-export, so the type is Plugin.Plugin). No named exports — the v2 loader imports only the default export.
• __testOnly is retired. Test seams moved to src/runtime/create-runtime.ts (createRuntime factory, direct-imported by tests) plus a rewritten src/test-fixtures.ts (createMockPluginInput returns a mock v2 context that records every registered hook).
• setup creates its own SessionStore/MatchedRulesStateStore (v1 module-level singletons gone) and returns runtime.wire(ctx)'s cleanup.

API mapping (v1 → v2)

v1	v2
tool.execute.before (input, output.args)	ctx.tool.hook('execute.before', input) — args are input.input; blockers throw Tool.Error (via @opencode-ai/plugin/promise/tool)
tool.execute.after (output.output)	ctx.tool.hook('execute.after', input) — status:'completed' gate; output text from result.content (string or Content[]) falling back to result.output
chat.message (durable parts appended to output.parts)	session prompt hook: evaluates durable rules, then publishes each built durable part via ctx.session.synthetic({ sessionID, id, text, metadata, delivery: 'steer' })
experimental.chat.messages.transform (transient injection)	session context hook: mutates input.messages in place (transient messages become ai-Messages {id: msg_rule_ephemeral_*, role:'user', content:[{type:'text', text, metadata}]})
client.session.messages + admission session.prompt({noReply:true})	session.context({sessionID}) for history (SessionMessageInfo[]); admission via session.prompt({..., resume: false}) with stable id msg_rule_admission_<identity> and metadata {ruleKeys, ruleAdmission:true}
client.tool.ids + client.mcp.status	gone: built-in tool IDs now come from the context hook's input.tools keys (cached per runtime) merged with ctx.mcp.list() → mcp_<sanitized> for connected servers
event hook (message.removed)	ctx.event.subscribe({signal}) loop: session.revert.staged/committed/cleared → ledger history-change invalidation; session.compaction.started/ended → markCompacted + projection rides the next context dispatch (placeholder; see below)
experimental.session.compacting (output.context)	no v2 channel — markCompacted fires on the compaction events; the Working-context projection is injected as a transient message on the next session-context dispatch

New/changed modules

• New src/runtime/create-runtime.ts (factory + test seam) and src/session/v2-messages.ts (fromContextMessages/fromSessionMessages adapters that normalize ai-Messages and SessionMessageInfo into the internal {info, parts} form so the codec/ledger needed almost no changes).
• chat-capture.ts rewritten: captureSessionPrompt (prompt hook → lastUserPrompt) and captureSessionContext (context hook → lastModelID/lastAgentType; SessionContext carries agent + model).
• client-adapter.ts calls session.context(...)/session.prompt(...) as method calls so SDK-style prototype methods keep their this receiver (regression-covered).
• mcp-tools.ts accepts both the legacy status map and the v2 McpServer[] shape.
• decodeRawHistory additionally reads message-level metadata.ruleKeys/hookKeys (v2 synthetic messages carry ledger keys at message level) — restart dedupe works.
• README/AGENTS.md updated for the new hook names, module list, and entry contract.

Divergences / notes for follow-ups

1. Durable injection timing: v1 appended parts to the user message (same-request visibility). v2 session.synthetic publishes a separate persisted message; it lands from the next request on. Port delivery engine to session.synthetic + context hook #72 should evaluate whether the current dispatch should also transiently include just-delivered durable rules for same-request visibility.
2. Compaction projection is a placeholder (degraded-then-healed per the map): the projection rides the next context dispatch after session.compaction.started. Redesign post-compaction ledger rebuild without a compaction hook #73 owns the real redesign.
3. First-turn model/agent capture: the prompt hook carries no model/agent; the context hook supplies them per dispatch. Model/agent-conditional durable rules evaluate with state from prior dispatches — on a session's very first dispatch they can miss. Port delivery engine to session.synthetic + context hook #72 should decide whether to evaluate durable rules on the context hook (which has full context) instead of the prompt hook.
4. Transient per-dispatch semantics: context-hook injections are request-scoped; per-turn dedup relies on the transientTurn anchor (latest real user message id). Verified working in tests; Port delivery engine to session.synthetic + context hook #72 should confirm against live opencode2 beta.
5. Deps: @opencode-ai/plugin devDep pinned to 0.0.0-beta-18999 (the beta dist-tag target — note the caret range resolved to an unrelated prerelease, so it is exact-pinned). @opencode-ai/schema/effect/zod are used transitively (Tool.Error via the plugin/promise/tool subpath); Update deps, versioning, and release workflow for v2 dist-tag #75 must add them explicitly and retarget peers to the beta line. Package manifest (oc-plugin, version, dist-tag workflow) also stays with Update deps, versioning, and release workflow for v2 dist-tag #75.
6. Dogfooding note: the repo ships no own opencode.json; v2 validation needs the consumer config key plugin → plugins (or local .opencode/plugin/ discovery) pointing at the built dist/src/index.js.
7. api-surface.typecheck.ts still enforces privacy; the orchestrator's options type remains internal, and createRuntime is not re-exported from the entry.