Skip to content

feat: support OpenCode V2 alongside V1 (and report the prompt-cache hit rate) - #1

Merged
jashjacob merged 8 commits into
jashjacob:mainfrom
zhicheng233:feat/v2-support
Nov 16, 2026
Merged

jashjacob merged 8 commits into
jashjacob:mainfrom
zhicheng233:feat/v2-support

Conversation

@zhicheng233

Copy link
Copy Markdown
Contributor

Summary

Adds OpenCode V2 support alongside the existing V1 support, from the same package.

V2's TUI plugin API differs enough from V1 that the current build cannot load at all — the failure is real and observable:

msg="loading plugin" ... /src/index.tsx
level=WARN message="failed to load plugin" target=opencode-token-metrics
  cause="Environment variable \"OPENTUI_FORCE_UNICODE\" is already registered with different configuration"

This PR ports the plugin so one package works on both generations, and also adds a prompt-cache hit rate.

What changed

Structure

Measurement logic is split from the transport so it can serve two APIs:

  • src/meter.ts — pure measurement.
  • src/controller.ts — platform-agnostic core over a normalized event union (turn/delta/segment/done/drop).
  • src/v1.ts — thin V1 adapter (message.updated, message.part.delta, message.part.updated, session.deleted).
  • src/v2.ts — thin V2 adapter over the session.* event bus.
  • src/tui.tsx (was src/index.tsx) — one dual-shape default export: { id, setup(ctx) } for V2 and { tui(api, options) } for V1.
  • src/server.ts — no-op V2 server entry, required so V2 can resolve the package.

V2 renders into prompt.footer.status; V1 keeps session_prompt_right. Both share one <MeterLine> component; only the palette source differs (ctx.theme.* vs api.theme.current.*).

V2 event mapping

V2 event Normalized
session.step.started turn (incl. TTFT start)
session.text.delta / session.reasoning.delta delta
session.tool.called segment (graph stays continuous across the pause)
session.step.ended / .failed accumulate exact provider tokens
session.execution.succeeded / .failed / .interrupted done
session.compaction.started turn (compaction is its own generation)
session.compaction.delta delta
session.compaction.ended / .failed done with the reported tokens
session.deleted drop

Compaction

Compaction streams a summary and reports its own token usage, but emits none of the step/execution events, so it would otherwise be invisible to the meter. It is now counted as its own generation.

A compacting guard skips execution.* completions that land mid-compaction; otherwise both sides would call settle and rescaleBuckets would be applied twice, distorting the VU graph.

Prompt-cache hit rate

Providers report cache.read / cache.write alongside the output tokens, which the adapters previously discarded. The counters are now read in both adapters and accumulated across a V2 execution's steps, and a cache <n>% segment is appended on settle:

tok/s ▁▃▅ 36.0 ▲9% · avg 41.0 · pk 45.0 · ttft 0.6s · cache 87%

The share is read / (input + read + write). It is omitted when the provider reports no prompt tokens (rather than showing a misleading 0%), and it clears once the next turn starts generating. input and cache are read defensively — some providers omit them entirely. New showCache option, default true.

Configuration

V2 options are read from the CLI config (~/.config/opencode/cli.json), not opencode.json:

// cli.json
{
  "plugins": [
    { "package": "opencode-token-metrics", "options": { "alwaysShow": true } }
  ]
}

Options in opencode.json are delivered to server plugins and never reach ctx.options. Keep the entry in only one of the two files. V1 keeps its tui.json tuple form.

Verification

  • npm test — 114 tests, 0 fail (12 suites)
  • npm run typecheck — clean
  • npm run smoke — OK
  • Loaded on a real OpenCode v2.0.30 install: stage=load entrypoint=.../src/tui.tsx → stage=setup plugin=opencode-token-metrics, zero errors. A deliberately-throwing plugin in the same run confirms the log distinguishes success from failure.
  • Confirmed rendering in the live V2 TUI, and that cli.json options reach ctx.options.

Notes

  • session.compaction.started carries no timestamp in the V2 schema, so its arrival time is used as the TTFT start. TTFT is therefore measured from event arrival, not model start.
  • The V1 install path is unchanged; tui.json behavior is untouched.

Move event translation out of the controller so it no longer imports the V1 plugin API. The core now takes normalized MeterEvents and returns whether state changed; src/v1.ts owns the V1 message.*/session.deleted wiring and the TUI layer keeps only rendering.
Map the V2 session.* event stream onto the shared meter core: step.started opens a turn (TTFT start), text/reasoning deltas feed the rate, tool.called starts a new segment, step.ended/failed accumulate exact provider tokens, and execution.succeeded/failed/interrupted settle the turn with the summed total.
Ship a dual-shape default export so one package serves both generations: V1 reads 'tui', V2 reads 'id' + 'setup' and renders into the prompt.footer.status slot with the resolved V2 theme. Add a no-op server entry so the V2 server never loads OpenTUI, and rename the entrypoint to src/tui.tsx.

Bump to 0.3.0 with @opencode/plugin and OpenTUI dev dependencies, and update the packed-package smoke test for the new entrypoints (also fixing its Windows invocations).
Split the install section by generation (V1 tui.json tuple options vs V2 plugins object options), add the V2 agent procedure, and describe both event mappings in the how-it-works section.
TUI plugin options are read from cli.json, not opencode.json; options in
opencode.json go to server plugins and never reach ctx.options. Document the
real install path and drop the incorrect no-hot-reload claim.
Compaction streams a summary and reports its own tokens through
session.compaction.*, which emits none of the step/execution events the
adapter listened for, so the whole generation went uncounted.

Map the compaction lifecycle to a turn and guard execution completions that
land mid-compaction, so the graph is not rescaled twice.
Providers report cache.read / cache.write alongside the output tokens, and
both adapters discarded them, so a cached prompt was invisible in the meter.

Read the counters in both adapters, accumulate them across a V2 execution's
steps, and surface `cache <n>%` on the frozen frame. The share is
read / (input + read + write). It is omitted when the provider reports no
prompt tokens, and clears once the next turn starts generating.
Copilot AI balanced review requested due to automatic review settings October 16, 2026 04:46

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@jashjacob jashjacob self-assigned this Nov 16, 2026
Later steps in one execution keep the same meter. Compaction drops the
previous execution's provider totals. The server entry exports server()
so the V1 installer can load it, and npm ci accepts the existing peer set.
@jashjacob
jashjacob merged commit 164f913 into jashjacob:main Nov 16, 2026
@zhicheng233
zhicheng233 deleted the feat/v2-support branch November 18, 2026 03:01
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.

3 participants