Skip to content

feat!: port plugin to the OpenCode V2 plugin API - #5

Open
Ariche2 wants to merge 1 commit into
Howardzhangdqs:mainfrom
Ariche2:OpenCode-V2-port
Open

Ariche2 wants to merge 1 commit into
Howardzhangdqs:mainfrom
Ariche2:OpenCode-V2-port

Conversation

@Ariche2

@Ariche2 Ariche2 commented Nov 4, 2026

Copy link
Copy Markdown

Summary

OpenCode V2 replaced the plugin API, and V1 plugin implementations no longer load. In OpenCode 2.2.5 the current main fails at startup:

level=WARN message="failed to load plugin"
  target=".opencode\plugins\throughput.ts"
  cause="Cannot find package '@opencode-ai/plugin' imported from ..."

This ports the plugin to the V2 API: entrypoint, context, events, tool registration, and toasts. The metric math, the benchmark tool output, and the JSONL/Markdown log formats are unchanged, so existing ~/.opencode/throughput.jsonl history still aggregates correctly.

Changes

  • Entrypoint — Plugin.define({ id: "throughput", setup(ctx) }) from @opencode/plugin; the cleanup function aborts the event subscription. client.* / directory become ctx.* / ctx.location.directory.
  • Events — message.updated, message.part.updated, message.removed and session.error do not exist in V2. The tracker now consumes the step lifecycle: session.step.started (model ref + start time), session.text.started / session.reasoning.started / session.step.streamed (first output, for TTFT), session.step.ended (latency, tokens, cost, finish), session.step.failed, and session.execution.failed for cleanup.
  • Granularity — metrics are recorded per model step rather than per assistant message, so a turn with tool calls produces one entry per request instead of one aggregated entry.
  • Tool — tool() / tool.schema replaced by ctx.tool.transform(editor => editor.add({ ... })) with a JSON Schema input and a { content } result.
  • Toast — moved to a TUI part (ctx.data.on + ctx.ui.toast.show), because the V2 server context has no TUI client. client.app.log is replaced by console.log, which lands in opencode.log.
  • Layout — the local plugin is now a directory (.opencode/plugins/throughput/{index,tui}.ts), since configured local plugin paths must be directories in V2. Implementation is split into src/metrics.ts (tracker + formatting) and src/report.ts (log IO + aggregation) so it can be tested without the plugin loader.
  • Packaging — package.json depends on @opencode/plugin, exports ./tui, and is bumped to 2.0.0 because the V1 dependency and entrypoint are gone.
  • Tests — converted from bun:test to node:test (bun is not required to run them) and rewritten around the step events.

Verification

  • tsc --noEmit clean
  • npm test: 21/21 passing
  • Loaded in OpenCode 2.2.5: /api/plugin reports id: "throughput", features: { server: true, tui: true }, status: active, with no load errors in opencode.log
  • End-to-end on real traffic: entries written to ~/.opencode/throughput.jsonl and <project>/.opencode/throughput.md, e.g. TTFT 2.5s | TPS 84.5 tok/s | Latency 4.0s, and the benchmark tool returns aggregated stats from them

Breaking change

The package now targets OpenCode V2 and requires @opencode/plugin 2.x. The V1 implementation is removed rather than kept alongside; if V1 support is still needed, the documented dual-entrypoint shape (setup + server()) can be added back, at the cost of maintaining both.

OpenCode V2 replaces the V1 plugin API, so the V1 implementation no longer
loads (it failed with: Cannot find package '@opencode-ai/plugin').

- entrypoint: Plugin.define({ id, setup }) from @opencode/plugin, cleanup aborts
  the event subscription
- events: message.* / session.error are gone; metrics now come from the step
  lifecycle (session.step.started, session.text.started,
  session.reasoning.started, session.step.streamed, session.step.ended,
  session.step.failed, session.execution.failed)
- metrics are recorded per model step instead of per assistant message, so
  turns with tool calls produce one entry per request
- tool: tool()/tool.schema becomes ctx.tool.transform(editor => editor.add())
  with a JSON Schema input and a { content } result
- toast moves to a TUI part (ctx.data.on + ctx.ui.toast.show); the server
  context has no TUI client
- local plugin becomes a directory (.opencode/plugins/throughput/{index,tui}.ts)
- split metrics/report out of the plugin for testability
- tests converted from bun:test to node:test, rewritten for the step events
- package.json: @opencode/plugin dependency, ./tui export, version 2.0.0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant