opencode-usage-report 0.5.0 → 0.6.1

package/README.md

@@ -71,11 +71,14 @@ Or add the plugin manually to each file and restart opencode:
 > `opencode plugin opencode-usage-report` prints `Detected server + tui targets`
 > when the resolution works.
 
-> **OpenCode 2.x (0.5.0).** The server entrypoint default-exports the V2
-> `{ id, setup }` definition and still carries the V1 `server` hook, so
-> OpenCode 1.18.29+ and 2.x both load it. Before 0.5.0 the module exported a
-> bare V1 function, which OpenCode 2 rejects. The TUI entrypoint is unchanged
-> in this release.
+> **OpenCode 2.x (0.6.0).** Both entrypoints now default-export a dual
+> definition. The server entrypoint exports `{ id, setup, server }` — V2 calls
+> `setup`, V1 calls `server`. The TUI entrypoint exports `{ id, setup, tui }` —
+> V2 calls `setup` (its `keymap.layer` runs from a headless `app`-slot
+> component), V1 calls `tui`. OpenCode 2's TUI loader rejects a default export
+> without a `setup` function (`Invalid V2 TUI plugin module`); before 0.6.0 the
+> TUI module exported only the V1 `tui` shape and failed to load on 2.x.
+> OpenCode 1.18.29+ and 2.x both load either entrypoint.
 
 Options can be passed in the tuple form, independently per entrypoint:
 
@@ -299,6 +302,12 @@ so a failing check blocks the stage.
 
 ## Changelog
 
+- **0.6.1** — Kimi Code adapter tracks the 2026-09 quota-model API change:
+  usage windows now come from the `usages.limit_5h` / `limit_7d` /
+  `limit_month_total` ratios (with a `limit_month_code` breakdown), and Extra
+  Usage is read from the camelCase `boosterWallet` (fixed-point `BOOSTER`
+  balance). The pre-2026-09 `usage` / `limits[]` / `totalQuota` /
+  `booster_wallet` shapes remain as fallbacks.
 - **0.4.1** — internal: shared provider HTTP plumbing (`src/providers/http.ts`)
   replaces the copy-pasted fetch/retry/error code; context estimates simplified;
   reset times render as `Wed, Sep 16`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-report",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "opencode plugin: /usage command showing subscription quota windows for configured providers",
   "keywords": [
     "kimi",

package/src/providers/kimi.ts

@@ -65,12 +65,17 @@ function findLimitDetail(limits: unknown, durationMinutes: number): unknown {
   return undefined;
 }
 
-function ratioWindow(kind: UsageWindow["kind"], label: string, value: unknown): UsageWindow {
+/** 0-100 percent from a quota entry's `used_ratio`, or null when it is absent/invalid. */
+function ratioPercent(value: unknown): number | null {
   const ratio = toNumber(pick(value, "used_ratio", "usedRatio"));
+  return ratio === null ? null : ratioToPercent(ratio);
+}
+
+function ratioWindow(kind: UsageWindow["kind"], label: string, value: unknown): UsageWindow {
   return {
     kind,
     label,
-    usedPercent: ratio !== null ? ratioToPercent(ratio) : null,
+    usedPercent: ratioPercent(value),
     used: null,
     limit: null,
     remaining: null,
@@ -88,6 +93,64 @@ function detailWindow(kind: UsageWindow["kind"], label: string, detail: unknown)
   });
 }
 
+/**
+ * Booster-wallet amounts are fixed-point integers in micro-cents
+ * (1_000_000 → 1 cent), matching the official kimi-code parser.
+ */
+const FIXED_POINT_CENTS = 1_000_000;
+
+function fixedPointToCents(value: unknown): number | null {
+  const raw = toNumber(value);
+  if (raw === null) return null;
+  const cents = raw / FIXED_POINT_CENTS;
+  if (cents > 0 && cents < 1) return 1;
+  return Math.round(cents);
+}
+
+function formatMoney(cents: number, currency: string): string {
+  return `$${(cents / 100).toFixed(2)} ${currency}`;
+}
+
+/** Currency for the wallet, taken from whichever money field carries one. */
+function walletCurrency(wallet: unknown): string {
+  for (const key of ["monthlyChargeLimit", "monthlyUsed"]) {
+    const currency = pick(pick(wallet, key), "currency");
+    if (typeof currency === "string" && currency !== "") return currency;
+  }
+  return "USD";
+}
+
+/**
+ * Renders the Extra Usage ("booster") wallet into `extras`. The post-2026-09
+ * quota model sends `boosterWallet.balance` as a `BOOSTER` descriptor with
+ * fixed-point micro-cents; the pre-2026-09 wire sent a scalar `booster_wallet.balance`.
+ */
+function parseBoosterWallet(body: unknown, extras: Record<string, string>): void {
+  const wallet = pick(body, "boosterWallet", "booster_wallet");
+  if (wallet === undefined) return;
+
+  const balance = pick(wallet, "balance");
+  const totalCents =
+    pick(balance, "type") === "BOOSTER" ? fixedPointToCents(pick(balance, "amount")) : null;
+  if (totalCents !== null && totalCents > 0) {
+    const left = fixedPointToCents(pick(balance, "amountLeft")) ?? 0;
+    extras["Booster wallet"] = formatMoney(left, walletCurrency(wallet));
+  } else if (typeof balance === "string" || typeof balance === "number") {
+    extras["Booster wallet"] = String(balance);
+  }
+
+  const monthlyUsed = pick(wallet, "monthlyUsed", "monthly_used");
+  const currency = pick(monthlyUsed, "currency");
+  const priceInCents = toNumber(pick(monthlyUsed, "priceInCents", "price_in_cents"));
+  if (
+    (typeof currency === "string" || typeof currency === "number") &&
+    String(currency) !== "" &&
+    priceInCents !== null
+  ) {
+    extras["Booster used this month"] = formatMoney(priceInCents, String(currency));
+  }
+}
+
 function parse(body: Record<string, unknown>, cred: Credential): AdapterResult {
   const windows: UsageWindow[] = [];
   const extras: Record<string, string> = {};
@@ -96,9 +159,9 @@ function parse(body: Record<string, unknown>, cred: Credential): AdapterResult {
   const usage = pick(body, "usage");
   const limits = pick(body, "limits");
 
-  // Count-based windows are authoritative; the `usages.limit_5h/limit_7d`
-  // ratios are legacy fields the live API returns as stale zeros even while
-  // real usage accrues, so they are only a fallback when counts are missing.
+  // Count-based windows are authoritative when present; the `usages.limit_*`
+  // ratios are the primary wire on the post-2026-09 quota model, where the
+  // absolute `usage`/`limits[]` rows were removed.
   const detail5h = findLimitDetail(limits, 300);
   if (detail5h !== undefined) {
     windows.push(detailWindow("5h", "5-hour", detail5h));
@@ -114,43 +177,36 @@ function parse(body: Record<string, unknown>, cred: Credential): AdapterResult {
     if (limit7d !== undefined) windows.push(ratioWindow("weekly", "Weekly", limit7d));
   }
 
+  // The monthly total joined the quota model; `totalQuota` is the legacy shape.
+  // `limit_month_code` is the code-typed share the official client shows as a
+  // breakdown under the monthly row.
+  const monthTotal = pick(usages, "limit_month_total");
+  if (monthTotal !== undefined) {
+    windows.push(ratioWindow("monthly", "Monthly", monthTotal));
+    const codePercent = ratioPercent(pick(usages, "limit_month_code"));
+    if (codePercent !== null) extras["Monthly code"] = `${codePercent}%`;
+  } else {
+    const totalQuota = pick(body, "totalQuota", "total_quota");
+    const quotaUsed = toNumber(pick(totalQuota, "used"));
+    if (totalQuota !== undefined && quotaUsed !== null && quotaUsed > 0) {
+      windows.push({
+        kind: "monthly",
+        label: "Monthly",
+        usedPercent: null,
+        used: quotaUsed,
+        limit: toNumber(pick(totalQuota, "limit")),
+        remaining: toNumber(pick(totalQuota, "remaining")),
+        resetsAt: toISODate(pick(totalQuota, "resetTime", "reset_time", "resetAt", "resetsAt")),
+        status: "frozen",
+      });
+    }
+  }
+
   const level = pick(pick(body, "user"), "membership");
   const membershipLevel = pick(level, "level");
   if (membershipLevel !== undefined) extras["Plan"] = String(membershipLevel);
 
-  const wallet = pick(body, "booster_wallet");
-
-  // `balance` is a wallet descriptor object on the live API; only render scalar values.
-  const balance = pick(wallet, "balance");
-  if (typeof balance === "string" || typeof balance === "number") {
-    extras["Booster wallet"] = String(balance);
-  }
-
-  const monthlyUsed = pick(wallet, "monthlyUsed", "monthly_used");
-  const currency = pick(monthlyUsed, "currency");
-  const priceInCents = toNumber(pick(monthlyUsed, "priceInCents", "price_in_cents"));
-  if (
-    (typeof currency === "string" || typeof currency === "number") &&
-    String(currency) !== "" &&
-    priceInCents !== null
-  ) {
-    extras["Booster used this month"] = `$${(priceInCents / 100).toFixed(2)} ${String(currency)}`;
-  }
-
-  const totalQuota = pick(body, "totalQuota", "total_quota");
-  const quotaUsed = toNumber(pick(totalQuota, "used"));
-  if (totalQuota !== undefined && quotaUsed !== null && quotaUsed > 0) {
-    windows.push({
-      kind: "monthly",
-      label: "Monthly",
-      usedPercent: null,
-      used: quotaUsed,
-      limit: toNumber(pick(totalQuota, "limit")),
-      remaining: toNumber(pick(totalQuota, "remaining")),
-      resetsAt: toISODate(pick(totalQuota, "resetTime", "reset_time", "resetAt", "resetsAt")),
-      status: "frozen",
-    });
-  }
+  parseBoosterWallet(body, extras);
 
   if (windows.length === 0) {
     throw new AdapterError(

package/src/tui.tsx

@@ -1,18 +1,16 @@
 /** @jsxImportSource @opentui/solid */
-import type {
-  TuiPlugin,
-  TuiPluginApi,
-  TuiPluginModule,
-  TuiSlotPlugin,
-} from "@opencode-ai/plugin/tui";
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui";
 import { For, createSignal } from "solid-js";
 import { DEFAULT_OPTIONS, collectReports } from "./report";
-import { coerceTuiOptions } from "./tui-format";
+import { coerceTuiOptions, type ResolvedTuiOptions } from "./tui-format";
 import { buildLines } from "./quota-lines";
 import { UsageDialog } from "./context/dialog";
 import { readCapture } from "./context/system";
 import type { SystemCapture } from "./context/types";
 import type { ProviderReport } from "./types";
+import { asV1Theme, createV2Api, v2ThemeColors, type V2Context } from "./v2-tui";
+
+type Theme = TuiPluginApi["theme"]["current"];
 
 /** Resolves the session the `/usage` dialog should describe, if any. */
 function activeSessionID(api: TuiPluginApi): string | null {
@@ -22,9 +20,11 @@ function activeSessionID(api: TuiPluginApi): string | null {
   return typeof id === "string" ? id : null;
 }
 
-export const tui: TuiPlugin = async (api, rawOptions) => {
-  const options = coerceTuiOptions(rawOptions);
-
+/**
+ * Shared panel state: the report cache, the refresh timer and the system-prompt
+ * capture. Built once per plugin load and driven by both the V1 and V2 halves.
+ */
+function createUsagePanel(getSessionID: () => string | null, options: ResolvedTuiOptions) {
   const [reports, setReports] = createSignal<ProviderReport[]>([]);
   const [inFlight, setInFlight] = createSignal(0);
   const [error, setError] = createSignal<string | null>(null);
@@ -32,10 +32,8 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
   const [capture, setCapture] = createSignal<SystemCapture | null>(null);
   const [scope, setScope] = createSignal(0);
   const [showJson, setShowJson] = createSignal(false);
-
-  const busy = (): boolean => inFlight() > 0;
-
   let disposed = false;
+
   const load = async (refresh = false): Promise<void> => {
     if (disposed) return;
     setInFlight((n) => n + 1);
@@ -60,10 +58,9 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
     }
   };
 
-  // Single timer: refreshes data, advances countdowns, reloads the capture.
   const refreshCapture = async (): Promise<void> => {
     if (disposed) return;
-    const sessionID = activeSessionID(api);
+    const sessionID = getSessionID();
     if (sessionID === null) {
       setCapture(null);
       return;
@@ -71,39 +68,108 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
     setCapture(await readCapture(sessionID));
   };
 
-  const intervalMs = Math.max(1, Math.floor(options.refreshIntervalSeconds)) * 1000;
   const refresh = (): void => {
     setTick(Date.now());
     void load();
     void refreshCapture();
   };
-  const timer = setInterval(refresh, intervalMs);
 
-  api.lifecycle.onDispose(() => {
-    disposed = true;
-    clearInterval(timer);
-  });
+  const timer = setInterval(
+    refresh,
+    Math.max(1, Math.floor(options.refreshIntervalSeconds)) * 1000,
+  );
+
+  return {
+    reports,
+    error,
+    tick,
+    capture,
+    scope,
+    showJson,
+    setScope,
+    setShowJson,
+    load,
+    refreshCapture,
+    refresh,
+    busy: (): boolean => inFlight() > 0,
+    isDisposed: (): boolean => disposed,
+    dispose: (): void => {
+      disposed = true;
+      clearInterval(timer);
+    },
+  };
+}
 
-  const offIdle = api.event.on("session.idle", refresh);
-  api.lifecycle.onDispose(offIdle);
+type UsagePanel = ReturnType<typeof createUsagePanel>;
+
+/** The sidebar quota panel; shared verbatim by the V1 and V2 halves. */
+function UsageSidebar(props: {
+  theme: () => Theme;
+  reports: () => ProviderReport[];
+  busy: () => boolean;
+  error: () => string | null;
+  tick: () => number;
+  barWidth: number;
+}) {
+  return (
+    <box flexDirection="column">
+      <text fg={props.theme().text}>
+        <b>Usage</b>
+      </text>
+      <For
+        each={buildLines(
+          props.theme(),
+          props.reports(),
+          props.busy(),
+          props.error(),
+          new Date(props.tick()),
+          props.barWidth,
+        )}
+      >
+        {(line) => (
+          <text>
+            {line.segments.map((seg) =>
+              seg.bold ? (
+                <b style={{ fg: seg.fg }}>{seg.text}</b>
+              ) : (
+                <span style={{ fg: seg.fg }}>{seg.text}</span>
+              ),
+            )}
+          </text>
+        )}
+      </For>
+    </box>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// OpenCode 1.x (V1) TUI plugin API.
+// ---------------------------------------------------------------------------
+
+export const tui: TuiPlugin = async (api, rawOptions) => {
+  const options = coerceTuiOptions(rawOptions);
+  const panel = createUsagePanel(() => activeSessionID(api), options);
+
+  api.lifecycle.onDispose(panel.dispose);
+  api.lifecycle.onDispose(api.event.on("session.idle", panel.refresh));
 
   const openDialog = (): void => {
     const sessionID = activeSessionID(api);
-    void refreshCapture().finally(() => {
-      if (disposed) return;
-      setScope(0);
-      setShowJson(false);
+    void panel.refreshCapture().finally(() => {
+      if (panel.isDisposed()) return;
+      panel.setScope(0);
+      panel.setShowJson(false);
       api.ui.dialog.replace(() => (
         <UsageDialog
           api={api}
           sessionID={sessionID}
-          reports={reports}
-          busy={busy}
-          error={error}
-          now={() => new Date(tick())}
-          system={capture}
-          scope={scope}
-          showJson={showJson}
+          reports={panel.reports}
+          busy={panel.busy}
+          error={panel.error}
+          now={() => new Date(panel.tick())}
+          system={panel.capture}
+          scope={panel.scope}
+          showJson={panel.showJson}
           barWidth={options.barWidth}
         />
       ));
@@ -121,7 +187,7 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
           category: "Plugin",
           namespace: "palette",
           run: () => {
-            void load(true);
+            void panel.load(true);
           },
         },
         {
@@ -143,17 +209,17 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
     api.keymap.registerLayer({
       mode: "modal",
       commands: [
-        { name: "usage.dialog.refresh", run: () => void load(true) },
+        { name: "usage.dialog.refresh", run: () => void panel.load(true) },
         {
           name: "usage.dialog.scope",
           run: () => {
-            setScope((n) => (n + 1) % Math.max(1, reports().length + 1));
+            panel.setScope((n) => (n + 1) % Math.max(1, panel.reports().length + 1));
           },
         },
         {
           name: "usage.dialog.json",
           run: () => {
-            setShowJson((v) => !v);
+            panel.setShowJson((v) => !v);
           },
         },
       ],
@@ -165,48 +231,157 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
     }),
   );
 
-  const slot: TuiSlotPlugin = {
+  api.slots.register({
     order: 150,
     slots: {
       sidebar_content(ctx) {
-        const theme = ctx.theme.current;
         return (
-          <box flexDirection="column">
-            <text fg={theme.text}>
-              <b>Usage</b>
-            </text>
-            <For
-              each={buildLines(
-                theme,
-                reports(),
-                busy(),
-                error(),
-                new Date(tick()),
-                options.barWidth,
-              )}
-            >
-              {(line) => (
-                <text>
-                  {line.segments.map((seg) =>
-                    seg.bold ? (
-                      <b style={{ fg: seg.fg }}>{seg.text}</b>
-                    ) : (
-                      <span style={{ fg: seg.fg }}>{seg.text}</span>
-                    ),
-                  )}
-                </text>
-              )}
-            </For>
-          </box>
+          <UsageSidebar
+            theme={() => ctx.theme.current}
+            reports={panel.reports}
+            busy={panel.busy}
+            error={panel.error}
+            tick={panel.tick}
+            barWidth={options.barWidth}
+          />
         );
       },
     },
+  });
+
+  void panel.load();
+};
+
+// ---------------------------------------------------------------------------
+// OpenCode 2.x (V2) TUI plugin API.
+// ---------------------------------------------------------------------------
+
+/**
+ * V2 command layer, mounted through a headless `app`-slot component because
+ * `keymap.layer` is a Solid context owned by the calling component: calling it
+ * from `setup` throws "Keymap.Provider is missing" and takes the whole plugin
+ * down. The layer is `global` so the palette/slash entry stays reachable.
+ */
+function V2CommandLayer(props: {
+  ctx: V2Context;
+  open: () => void;
+  refresh: () => void;
+  panel: UsagePanel;
+}) {
+  props.ctx.keymap.layer(() => ({
+    mode: "global",
+    commands: [
+      {
+        id: "usage.open",
+        title: "Usage: open report",
+        description: "Context usage and provider quota windows",
+        group: "Usage",
+        palette: true,
+        slash: { name: "usage" },
+        run: () => props.open(),
+      },
+      {
+        id: "usage.refresh",
+        title: "Usage: refresh now",
+        group: "Usage",
+        bind: "ctrl+shift+u",
+        run: () => props.refresh(),
+      },
+    ],
+  }));
+
+  // ponytail: best-effort in-dialog keys. V2 exposes no documented modal mode
+  // name, so r/tab/j bind only if the host names dialog input "modal".
+  props.ctx.keymap.layer(() => ({
+    mode: "modal",
+    commands: [
+      { id: "usage.dialog.refresh", bind: "r", run: () => props.refresh() },
+      {
+        id: "usage.dialog.scope",
+        bind: "tab",
+        run: () =>
+          props.panel.setScope((n) => (n + 1) % Math.max(1, props.panel.reports().length + 1)),
+      },
+      { id: "usage.dialog.json", bind: "j", run: () => props.panel.setShowJson((v) => !v) },
+    ],
+  }));
+
+  return null;
+}
+
+function setup(ctx: V2Context): () => void {
+  const options = coerceTuiOptions(ctx.options as Record<string, unknown> | undefined);
+  const api = createV2Api(ctx);
+  const panel = createUsagePanel(() => activeSessionID(api), options);
+
+  const offIdle = ctx.data.on("session.idle", () => panel.refresh());
+
+  const openDialog = (): void => {
+    const sessionID = activeSessionID(api);
+    void panel.refreshCapture().finally(() => {
+      if (panel.isDisposed()) return;
+      panel.setScope(0);
+      panel.setShowJson(false);
+      ctx.ui.dialog.show(() => (
+        <UsageDialog
+          api={api}
+          sessionID={sessionID}
+          reports={panel.reports}
+          busy={panel.busy}
+          error={panel.error}
+          now={() => new Date(panel.tick())}
+          system={panel.capture}
+          scope={panel.scope}
+          showJson={panel.showJson}
+          barWidth={options.barWidth}
+        />
+      ));
+      ctx.ui.dialog.set({ size: "xlarge" });
+    });
   };
 
-  api.slots.register(slot);
+  const offSidebar = ctx.ui.slot({
+    append: "sidebar.content",
+    render: () => (
+      <UsageSidebar
+        theme={() => asV1Theme(v2ThemeColors(ctx.theme))}
+        reports={panel.reports}
+        busy={panel.busy}
+        error={panel.error}
+        tick={panel.tick}
+        barWidth={options.barWidth}
+      />
+    ),
+  });
+
+  const offCommands = ctx.ui.slot({
+    append: "app",
+    render: () => (
+      <V2CommandLayer
+        ctx={ctx}
+        open={openDialog}
+        refresh={() => void panel.load(true)}
+        panel={panel}
+      />
+    ),
+  });
+
+  void panel.load();
+
+  return () => {
+    panel.dispose();
+    offIdle();
+    offSidebar();
+    offCommands();
+  };
+}
 
-  void load();
+// One default export serves both contracts: V1 reads `tui`, V2 reads `setup`
+// and discards the rest (Effect Schema strips undeclared keys).
+const plugin: TuiPluginModule & { id: string; setup: (ctx: V2Context) => () => void } = {
+  id: "usage-report",
+  tui,
+  setup,
 };
 
-const plugin: TuiPluginModule & { id: string } = { id: "usage-report", tui };
 export default plugin;

package/src/v2-tui.ts

@@ -0,0 +1,395 @@
+/**
+ * OpenCode 2.x TUI plugin glue.
+ *
+ * OpenCode 2's TUI host loads the `./tui` entrypoint and validates its default
+ * export as `{ id, setup }` — a module whose default lacks `setup` is rejected
+ * with "Invalid V2 TUI plugin module". V2 also replaced the old `api.*` surface
+ * (snake_case slots, `api.state`, `api.route`, `api.ui.dialog.replace`) with a
+ * dot-separated slot tree (`ui.slot`), a client-local store (`data`), and a
+ * `ui.dialog` stack. The types here are mirrored structurally from
+ * `@opencode/plugin@2.0.20` (`dist/tui/context.d.ts` / `@opencode/theme`) —
+ * the host injects the context, so this package must not resolve either
+ * package at runtime.
+ *
+ * Rather than fork every renderer, `createV2Api` adapts the V2 context back to
+ * the V1 `TuiPluginApi` shape the existing sidebar/dialog already consume.
+ */
+import type { Message, Part, Provider, Session } from "@opencode-ai/sdk/v2";
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { RGBA } from "@opentui/core";
+import { finiteOrNull, isRecord, safeString } from "./normalize";
+
+type V1ThemeCurrent = TuiPluginApi["theme"]["current"];
+
+// ---------------------------------------------------------------------------
+// Structural mirror of the V2 TUI context (subset actually consumed).
+// ---------------------------------------------------------------------------
+
+export interface V2ThemeFeedbackColor {
+  readonly base?: RGBA;
+  readonly muted?: RGBA;
+  /** Pre-2.0.8 spelling. */
+  readonly default?: RGBA;
+}
+
+export interface V2ThemeText {
+  readonly base?: RGBA;
+  readonly muted?: RGBA;
+  /** Pre-2.0.8 spellings. */
+  readonly default?: RGBA;
+  readonly subdued?: RGBA;
+  readonly feedback?: {
+    readonly error?: V2ThemeFeedbackColor;
+    readonly warning?: V2ThemeFeedbackColor;
+    readonly success?: V2ThemeFeedbackColor;
+    readonly info?: V2ThemeFeedbackColor;
+  };
+}
+
+export interface V2Theme {
+  readonly text: V2ThemeText;
+  readonly border?: { readonly base?: RGBA };
+  readonly hue?: {
+    readonly accent?: Readonly<Record<number, RGBA>>;
+    readonly interactive?: Readonly<Record<number, RGBA>>;
+  };
+}
+
+export interface V2Route {
+  readonly type: string;
+  readonly sessionID?: string;
+}
+
+export interface V2ModelRef {
+  readonly providerID?: string;
+  readonly modelID?: string;
+}
+
+export interface V2TokenUsage {
+  readonly input?: number;
+  readonly output?: number;
+  readonly cache?: { readonly read?: number; readonly write?: number };
+}
+
+export interface V2ToolState {
+  readonly input?: unknown;
+  readonly output?: unknown;
+  readonly time?: { readonly compacted?: number };
+}
+
+export interface V2ContentPart {
+  readonly type?: string;
+  readonly text?: string;
+  readonly filename?: string;
+  readonly mime?: string;
+  readonly state?: V2ToolState;
+}
+
+export interface V2AssistantMessage {
+  readonly id?: string;
+  readonly type: "assistant";
+  readonly model?: V2ModelRef;
+  readonly content?: readonly V2ContentPart[];
+  readonly tokens?: V2TokenUsage;
+  readonly time?: { readonly created?: number };
+}
+
+export interface V2UserFile {
+  readonly filename?: string;
+  readonly name?: string;
+  readonly mime?: string;
+}
+
+export interface V2UserMessage {
+  readonly id?: string;
+  readonly type: "user";
+  readonly text?: string;
+  readonly files?: readonly V2UserFile[];
+  readonly time?: { readonly created?: number };
+}
+
+export interface V2ProviderInfo {
+  readonly id: string;
+}
+
+export interface V2ModelInfo {
+  readonly id: string;
+  readonly modelID: string;
+  readonly providerID: string;
+  readonly name: string;
+  readonly limit?: { readonly context?: number };
+}
+
+export interface V2Data {
+  on(type: string, handler: (event: unknown) => void): () => void;
+  readonly session: {
+    cost(sessionID: string): number;
+    readonly message: { list(sessionID: string): readonly unknown[] };
+  };
+  readonly location: {
+    readonly provider: { list(): readonly V2ProviderInfo[] | undefined };
+    readonly model: { list(): readonly V2ModelInfo[] | undefined };
+  };
+}
+
+export interface V2Dialog {
+  show(render: () => unknown, onClose?: () => void): void;
+  set(options: {
+    readonly size?: "medium" | "large" | "xlarge";
+    readonly centered?: boolean;
+  }): void;
+  clear(): void;
+}
+
+export interface V2KeymapCommand {
+  readonly id?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly group?: string;
+  readonly palette?: true;
+  readonly bind?: false | string;
+  readonly slash?: { readonly name: string; readonly aliases?: readonly string[] };
+  readonly run: (input?: string, event?: unknown) => void | false | Promise<void>;
+}
+
+export interface V2KeymapLayer {
+  readonly mode?: string;
+  readonly commands?: readonly V2KeymapCommand[];
+  readonly bindings?: readonly string[];
+}
+
+export interface V2SlotClaim {
+  readonly render: (input: never) => unknown;
+  readonly append: string;
+  readonly prepend?: never;
+  readonly before?: never;
+  readonly after?: never;
+  readonly replace?: never;
+}
+
+export interface V2Context {
+  readonly options?: Readonly<Record<string, unknown>>;
+  readonly theme: V2Theme;
+  readonly data: V2Data;
+  readonly ui: {
+    readonly slot: (claim: V2SlotClaim) => () => void;
+    readonly dialog: V2Dialog;
+    readonly router: { current(): V2Route };
+  };
+  readonly keymap: { layer(input: () => V2KeymapLayer): void };
+}
+
+// ---------------------------------------------------------------------------
+// Theme adapter (V2 tokens -> the V1 names the renderers read).
+// ---------------------------------------------------------------------------
+
+/** The V1 theme keys `buildLines` / `buildContextLines` resolve by name. */
+export interface UsageThemeColors {
+  text: RGBA;
+  textMuted: RGBA;
+  accent: RGBA;
+  secondary: RGBA;
+  info: RGBA;
+  success: RGBA;
+  warning: RGBA;
+  error: RGBA;
+  borderSubtle: RGBA;
+}
+
+function feedbackBase(color: V2ThemeFeedbackColor | undefined, fallback: RGBA): RGBA {
+  return color?.base ?? color?.default ?? fallback;
+}
+
+/**
+ * Maps the V2 resolved theme onto the V1 color names. Reads both the 2.0.8+
+ * spelling (`base`/`muted`) and the earlier one (`default`/`subdued`), and
+ * falls back to the body text color so a rename upstream paints default
+ * foreground instead of nothing.
+ */
+export function v2ThemeColors(theme: V2Theme): UsageThemeColors {
+  const text = theme?.text ?? {};
+  const base = (text.base ?? text.default) as RGBA;
+  const muted = (text.muted ?? text.subdued) as RGBA;
+  const feedback = text.feedback ?? {};
+  const accent = (theme?.hue?.accent?.[500] ?? base) as RGBA;
+  const secondary = (theme?.hue?.interactive?.[500] ?? muted) as RGBA;
+  return {
+    text: base,
+    textMuted: muted,
+    accent,
+    secondary,
+    info: feedbackBase(feedback.info, base),
+    success: feedbackBase(feedback.success, base),
+    warning: feedbackBase(feedback.warning, base),
+    error: feedbackBase(feedback.error, base),
+    borderSubtle: (theme?.border?.base ?? muted) as RGBA,
+  };
+}
+
+/** Casts the adapter result for the V1-typed renderers. */
+export function asV1Theme(colors: UsageThemeColors): V1ThemeCurrent {
+  return colors as unknown as V1ThemeCurrent;
+}
+
+// ---------------------------------------------------------------------------
+// Data adapter (V2 messages -> the V1 message/part shape `collectContext` reads).
+// ---------------------------------------------------------------------------
+
+const ZERO_TOKENS = { input: 0, output: 0, cache: { read: 0, write: 0 } };
+
+function createdAt(message: { readonly time?: { readonly created?: number } }): {
+  created: number;
+} {
+  return { created: finiteOrNull(message.time?.created) ?? 0 };
+}
+
+/**
+ * Translates one V2 message into a V1-shaped record plus its inline parts.
+ * V2 assistant content already carries `text`/`reasoning`/`tool` parts; V2 user
+ * messages carry a single `text` and an optional file list, so those are
+ * synthesized into the same part shape.
+ */
+function translateMessage(raw: unknown): {
+  record: Record<string, unknown>;
+  parts: Array<Record<string, unknown>>;
+} {
+  if (!isRecord(raw)) return { record: {}, parts: [] };
+  const id = typeof raw.id === "string" ? raw.id : "";
+  if (raw.type === "assistant") {
+    const message = raw as unknown as V2AssistantMessage;
+    const tokens = isRecord(message.tokens) ? message.tokens : {};
+    const cache = isRecord(tokens.cache) ? tokens.cache : {};
+    const model = isRecord(message.model) ? message.model : {};
+    const parts = Array.isArray(message.content) ? message.content.filter(isRecord) : [];
+    return {
+      record: {
+        id,
+        role: "assistant",
+        providerID: safeString(model.providerID),
+        modelID: safeString(model.modelID),
+        time: createdAt(message),
+        tokens: {
+          input: finiteOrNull(tokens.input) ?? 0,
+          output: finiteOrNull(tokens.output) ?? 0,
+          cache: { read: finiteOrNull(cache.read) ?? 0, write: finiteOrNull(cache.write) ?? 0 },
+        },
+      },
+      parts: parts as Array<Record<string, unknown>>,
+    };
+  }
+  if (raw.type === "user") {
+    const message = raw as unknown as V2UserMessage;
+    const parts: Array<Record<string, unknown>> = [];
+    if (typeof message.text === "string" && message.text !== "") {
+      parts.push({ type: "text", text: message.text });
+    }
+    if (Array.isArray(message.files)) {
+      for (const file of message.files) {
+        if (!isRecord(file)) continue;
+        parts.push({
+          type: "file",
+          filename: safeString(file.filename ?? file.name),
+          mime: safeString(file.mime),
+        });
+      }
+    }
+    return {
+      record: { id, role: "user", time: createdAt(message), tokens: { ...ZERO_TOKENS } },
+      parts,
+    };
+  }
+  return { record: {}, parts: [] };
+}
+
+/** Provider list with the `{ id, models }` shape `UsageDialog` looks up. */
+export function v2ProviderModels(data: V2Data): Array<{
+  id: string;
+  models: Record<string, V2ModelInfo>;
+}> {
+  const byProvider = new Map<string, Record<string, V2ModelInfo>>();
+  for (const model of data.location.model.list() ?? []) {
+    const bucket = byProvider.get(model.providerID) ?? {};
+    bucket[model.modelID] = model;
+    byProvider.set(model.providerID, bucket);
+  }
+  return (data.location.provider.list() ?? []).map((provider) => ({
+    id: provider.id,
+    models: byProvider.get(provider.id) ?? {},
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Context -> V1 API facade.
+// ---------------------------------------------------------------------------
+
+/**
+ * Presents the V2 context through the slice of `TuiPluginApi` the sidebar and
+ * `/usage` dialog consume (`theme.current`, `route.current`, `state.*`,
+ * `ui.dialog`), so the existing renderers run unchanged.
+ *
+ * `state.config` is intentionally absent: OpenCode 2 does not expose the
+ * resolved config to TUI plugins, so the dialog loses the compaction-reserve
+ * nuance only (the token rows are unaffected).
+ */
+export function createV2Api(ctx: V2Context): TuiPluginApi {
+  const partsById = new Map<string, Array<Record<string, unknown>>>();
+
+  const api = {
+    theme: {
+      get current(): V1ThemeCurrent {
+        return asV1Theme(v2ThemeColors(ctx.theme));
+      },
+    },
+    route: {
+      get current(): { name: string; params?: Record<string, unknown> } {
+        const route = ctx.ui.router.current();
+        if (route.type === "session" && typeof route.sessionID === "string") {
+          return { name: "session", params: { sessionID: route.sessionID } };
+        }
+        return { name: route.type };
+      },
+    },
+    state: {
+      get provider(): ReadonlyArray<Provider> {
+        return v2ProviderModels(ctx.data) as unknown as ReadonlyArray<Provider>;
+      },
+      get config(): undefined {
+        return undefined;
+      },
+      session: {
+        messages(sessionID: string): ReadonlyArray<Message> {
+          const list = ctx.data.session.message.list(sessionID) ?? [];
+          const messages: Array<Record<string, unknown>> = [];
+          partsById.clear();
+          for (const raw of list) {
+            const { record, parts } = translateMessage(raw);
+            if (typeof record.id !== "string" || record.id === "") continue;
+            messages.push(record);
+            partsById.set(record.id, parts);
+          }
+          return messages as unknown as ReadonlyArray<Message>;
+        },
+        get(sessionID: string): Session {
+          return { cost: ctx.data.session.cost(sessionID) } as unknown as Session;
+        },
+      },
+      part(messageID: string): ReadonlyArray<Part> {
+        return (partsById.get(messageID) ?? []) as unknown as ReadonlyArray<Part>;
+      },
+    },
+    ui: {
+      dialog: {
+        replace(render: () => unknown, onClose?: () => void): void {
+          ctx.ui.dialog.show(render, onClose);
+        },
+        setSize(size: "medium" | "large" | "xlarge"): void {
+          ctx.ui.dialog.set({ size });
+        },
+        clear(): void {
+          ctx.ui.dialog.clear();
+        },
+      },
+    },
+  };
+  return api as unknown as TuiPluginApi;
+}