opencode-usage-report 0.4.0 → 0.5.0

package/README.md

@@ -71,6 +71,12 @@ 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.
+
 Options can be passed in the tuple form, independently per entrypoint:
 
 ```jsonc
@@ -283,7 +289,7 @@ Releases are **staged**, not published directly. Pushing a `v*` tag triggers
 the staged release with 2FA:
 
 ```sh
-git tag v0.4.0 && git push origin main v0.4.0
+git tag v0.4.1 && git push origin main v0.4.1
 npm stage list                    # find the stage id
 npm stage approve <stage-id>      # 2FA prompt; or approve in the npm UI
 ```
@@ -293,6 +299,9 @@ so a failing check blocks the stage.
 
 ## Changelog
 
+- **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`.
 - **0.4.0** — context usage panel (`/usage` now shows context breakdown, grid,
   compaction headroom and cost); `/usage` became a local TUI command that costs
   no model tokens; sidebar rendering extracted to `src/quota-lines.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-report",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "opencode plugin: /usage command showing subscription quota windows for configured providers",
   "keywords": [
     "kimi",
@@ -49,7 +49,6 @@
   "devDependencies": {
     "@opencode-ai/plugin": "^1.0.0",
     "@opentui/core": "^0.5.11",
-    "@opentui/keymap": "^0.5.11",
     "@opentui/solid": "^0.5.11",
     "@types/node": "^26.6.2",
     "oxfmt": "^0.70.0",

package/src/context/collect.ts

@@ -1,6 +1,7 @@
 import type { AssistantMessage, Part } from "@opencode-ai/sdk/v2";
 import type { CollectInput, ContextBreakdown, ContextRow, RowKey, SystemCapture } from "./types";
 import { estimateJson, estimateTokens } from "./estimate";
+import { finiteOrNull, isRecord, safeString } from "../normalize";
 import { buildGrid } from "./grid";
 import { computeHeadroom } from "./headroom";
 
@@ -15,24 +16,6 @@ const ROW_LABELS: Record<RowKey, string> = {
 
 const MEASURED_KEYS: readonly RowKey[] = ["user", "agent", "reasoning", "tools", "system"];
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function finiteOrNull(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function safeString(value: unknown): string {
-  if (typeof value === "string") return value;
-  if (value === null || value === undefined) return "";
-  try {
-    return String(value);
-  } catch {
-    return "";
-  }
-}
-
 function isAssistant(value: unknown): value is AssistantMessage {
   return isRecord(value) && value.role === "assistant";
 }
@@ -72,49 +55,25 @@ function isUsableCapture(capture: SystemCapture | null | undefined): capture is
 }
 
 /**
- * Scales `values` so they sum to `target` by the largest-remainder method; the
- * result never exceeds `target`. Used when raw `chars/4` estimates overshoot.
+ * Scales `values` proportionally so they sum to at most `target`; each row is an
+ * estimate, so flooring may leave the five rows a few tokens short of the total.
  */
-function largestRemainderScale(
-  values: readonly number[],
-  target: number,
-  divisor: number,
-): number[] {
+function scaleToTotal(values: readonly number[], target: number, divisor: number): number[] {
   if (!Number.isFinite(divisor) || divisor <= 0) return values.map(() => 0);
   const total = Math.max(0, Math.round(target));
-  const scaled = values.map((value) => (value > 0 ? (value * total) / divisor : 0));
-  const rounded = scaled.map((value) => Math.floor(value));
-  let deficit = total - rounded.reduce((sum, value) => sum + value, 0);
-  if (deficit <= 0) return rounded;
-
-  const order = scaled
-    .map((value, index) => ({ index, fraction: value - Math.floor(value) }))
-    .sort((a, b) => b.fraction - a.fraction);
-  for (const { index } of order) {
-    if (deficit <= 0) break;
-    rounded[index] += 1;
-    deficit -= 1;
-  }
-  return rounded;
+  return values.map((value) => (value > 0 ? Math.floor((value * total) / divisor) : 0));
 }
 
-function makeRow(
-  key: RowKey,
-  tokens: number | null,
-  exact: boolean,
-  limit: number | null,
-): ContextRow {
+function makeRow(key: RowKey, tokens: number | null, limit: number | null): ContextRow {
   const percent =
     tokens !== null && limit !== null && limit > 0
       ? Math.min(100, Math.max(0, Math.round((tokens / limit) * 100)))
       : null;
-  return { key, label: ROW_LABELS[key], tokens, percent, exact };
+  return { key, label: ROW_LABELS[key], tokens, percent };
 }
 
 function emptyRows(limit: number | null): ContextRow[] {
-  return [...MEASURED_KEYS, "free" as RowKey].map((key) =>
-    makeRow(key, null, key === "free", limit),
-  );
+  return [...MEASURED_KEYS, "free" as RowKey].map((key) => makeRow(key, null, limit));
 }
 
 /**
@@ -212,9 +171,9 @@ export function collectContext(input: CollectInput): ContextBreakdown {
   let systemTokens = Math.max(0, total - estimatedSum);
 
   // chars/4 is an estimate in both directions; when it overshoots the exact
-  // total, scale all five measured rows down so they sum to `total` (6.5).
+  // total, scale all five measured rows down so they sum to at most `total` (6.5).
   if (estimatedSum > total) {
-    const scaled = largestRemainderScale(
+    const scaled = scaleToTotal(
       [userTokens, agentTokens, reasoningTokens, toolsTokens, systemTokens],
       total,
       estimatedSum,
@@ -227,9 +186,9 @@ export function collectContext(input: CollectInput): ContextBreakdown {
   }
 
   const measured = [userTokens, agentTokens, reasoningTokens, toolsTokens, systemTokens];
-  const rows = MEASURED_KEYS.map((key, index) => makeRow(key, measured[index], false, limit));
+  const rows = MEASURED_KEYS.map((key, index) => makeRow(key, measured[index], limit));
   const freeTokens = limit !== null ? Math.max(0, limit - total) : null;
-  rows.push(makeRow("free", freeTokens, true, limit));
+  rows.push(makeRow("free", freeTokens, limit));
 
   return {
     ready: true,

package/src/context/estimate.ts

@@ -5,32 +5,7 @@ export function estimateTokens(text: string): number {
   return Math.max(0, Math.round(value.length / 4));
 }
 
-const MAX_JSON_CHARS = 2_000_000;
-
-/**
- * Estimates tokens for the JSON serialization of an arbitrary value. Circular
- * references and unserializable values are handled without throwing, and the
- * serialized prefix is capped so allocation stays bounded.
- */
+/** Estimates tokens for the JSON serialization of a value that came from JSON. */
 export function estimateJson(value: unknown): number {
-  let json: string;
-  try {
-    const seen = new WeakSet<object>();
-    json =
-      JSON.stringify(value, (_key, val) => {
-        if (typeof val === "bigint") return val.toString();
-        if (typeof val === "object" && val !== null) {
-          if (seen.has(val)) return "[Circular]";
-          seen.add(val);
-        }
-        return val;
-      }) ?? "";
-  } catch {
-    try {
-      json = String(value);
-    } catch {
-      json = "";
-    }
-  }
-  return estimateTokens(json.length > MAX_JSON_CHARS ? json.slice(0, MAX_JSON_CHARS) : json);
+  return estimateTokens(JSON.stringify(value) ?? "");
 }

package/src/context/format.ts

@@ -4,6 +4,8 @@
  * same shape `buildLines` uses in `src/quota-lines.ts`.
  */
 import type { ContextBreakdown, ContextRow, GridCell, RowKey } from "./types";
+import { finiteOrNull, nonNegative } from "../normalize";
+import { padLabel } from "../tui-format";
 
 /** Theme color names used by the context block. */
 export type ContextTone =
@@ -40,15 +42,6 @@ const LEGEND_PERCENT_WIDTH = 6;
 const LEGEND_GAP = "   ";
 const COLUMNS_PER_LEGEND_ROW = 3;
 
-const ROW_LABELS: Record<RowKey, string> = {
-  user: "User messages",
-  agent: "Agent responses",
-  reasoning: "Reasoning",
-  tools: "Tool calls",
-  system: "System & tools",
-  free: "Free space",
-};
-
 const CATEGORY_TONES: Record<RowKey, ContextTone> = {
   user: "info",
   agent: "success",
@@ -79,15 +72,6 @@ export function formatMoney(n: number): string {
   return MONEY.format(value);
 }
 
-function finite(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function nonNegative(value: unknown): number | null {
-  const n = finite(value);
-  return n !== null && n >= 0 ? n : null;
-}
-
 function glyphFor(fill: number): string {
   if (fill <= 0) return "░░";
   if (fill <= 0.25) return "▒▒";
@@ -100,19 +84,6 @@ function toneForRowKey(key: unknown): ContextTone {
   return CATEGORY_TONES[key as RowKey] ?? "borderSubtle";
 }
 
-function truncateLabel(label: string, width: number): string {
-  if (label.length <= width) return label;
-  return label.slice(0, Math.max(0, width - 1)) + "…";
-}
-
-function padLabel(label: string, width: number): string {
-  return truncateLabel(label, width).padEnd(width);
-}
-
-function rightAlign(value: string, width: number): string {
-  return value.length >= width ? value : " ".repeat(width - value.length) + value;
-}
-
 /**
  * One-decimal percentage. A non-zero share that would round to `0.0%` reads as
  * "nothing at all", so anything under a tenth of a percent collapses to `<0.1%`.
@@ -144,10 +115,7 @@ function rowMap(breakdown: ContextBreakdown): Map<RowKey, ContextRow> {
 }
 
 function legendEntry(key: RowKey, row: ContextRow | undefined, systemDerived: boolean): Segment[] {
-  const baseLabel =
-    row !== undefined && typeof row.label === "string" && row.label !== ""
-      ? row.label
-      : ROW_LABELS[key];
+  const baseLabel = row?.label ?? key;
   const label = key === "system" && systemDerived ? `${baseLabel} (derived)` : baseLabel;
   const tokens = nonNegative(row?.tokens);
   const percent = nonNegative(row?.percent);
@@ -156,11 +124,11 @@ function legendEntry(key: RowKey, row: ContextRow | undefined, systemDerived: bo
     { text: "● ", fg: CATEGORY_TONES[key] },
     { text: padLabel(label, LEGEND_LABEL_WIDTH), fg: "text" },
     {
-      text: rightAlign(tokens === null ? "—" : formatTokens(tokens), LEGEND_COUNT_WIDTH),
+      text: (tokens === null ? "—" : formatTokens(tokens)).padStart(LEGEND_COUNT_WIDTH, " "),
       fg: "text",
     },
     { text: " ", fg: "text" },
-    { text: rightAlign(percentText, LEGEND_PERCENT_WIDTH), fg: "textMuted" },
+    { text: percentText.padStart(LEGEND_PERCENT_WIDTH, " "), fg: "textMuted" },
   ];
 }
 
@@ -178,7 +146,7 @@ function gridLines(breakdown: ContextBreakdown): Line[] {
     const segments: Segment[] = [];
     for (let c = 0; c < renderCols; c++) {
       const cell = cells[r * cols + c] as GridCell | undefined;
-      const fill = cell === undefined ? 0 : Math.min(1, Math.max(0, finite(cell.fill) ?? 0));
+      const fill = cell === undefined ? 0 : Math.min(1, Math.max(0, finiteOrNull(cell.fill) ?? 0));
       segments.push({ text: glyphFor(fill), fg: toneForRowKey(cell?.rowKey) });
     }
     lines.push({ segments });

package/src/context/grid.ts

@@ -1,8 +1,8 @@
 import type { ContextRow, GridCell, RowKey } from "./types";
+import { finiteOrNull } from "../normalize";
 
 const GRID_ROWS_DEFAULT = 6;
-const MIN_COLS = 8;
-const MAX_COLS = 60;
+const GRID_COLS_DEFAULT = 8;
 const CATEGORY_ORDER: readonly RowKey[] = ["user", "agent", "reasoning", "tools", "system"];
 
 export interface BuildGridInput {
@@ -13,20 +13,6 @@ export interface BuildGridInput {
   gridRows?: number | null;
 }
 
-function finiteOrNull(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function clampCols(value: number | null | undefined): number {
-  const n = finiteOrNull(value);
-  return Math.min(MAX_COLS, Math.max(MIN_COLS, n === null ? MIN_COLS : Math.floor(n)));
-}
-
-function clampGridRows(value: number | null | undefined): number {
-  const n = finiteOrNull(value);
-  return n !== null && Math.floor(n) >= 1 ? Math.floor(n) : GRID_ROWS_DEFAULT;
-}
-
 function rowTokens(rows: readonly ContextRow[], key: RowKey): number {
   if (!Array.isArray(rows)) return 0;
   for (const row of rows) {
@@ -58,8 +44,8 @@ export function buildGrid(input: BuildGridInput): {
   rows: number;
   cells: GridCell[];
 } {
-  const cols = clampCols(input.cols);
-  const rows = clampGridRows(input.gridRows);
+  const cols = finiteOrNull(input.cols) ?? GRID_COLS_DEFAULT;
+  const rows = finiteOrNull(input.gridRows) ?? GRID_ROWS_DEFAULT;
   const limit = finiteOrNull(input.limit);
   if (limit === null || limit <= 0) return { cols, rows, cells: [] };
 

package/src/context/headroom.ts

@@ -1,4 +1,5 @@
 import type { Model } from "@opencode-ai/sdk/v2";
+import { finiteOrNull } from "../normalize";
 
 export interface Headroom {
   usable: number | null;
@@ -12,10 +13,6 @@ export interface HeadroomInput {
   compaction?: { reserved?: number } | null;
 }
 
-function finiteOrNull(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
 /** Compaction headroom, mirroring opencode's overflow check; nulls when unusable. */
 export function computeHeadroom(input: HeadroomInput): Headroom {
   const limit = input.limit;

package/src/context/system.ts

@@ -7,23 +7,12 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { SystemCapture } from "./types";
+import { isRecord, nonNegative } from "../normalize";
 import { pluginStateDir } from "../paths";
 
 const CAPTURE_VERSION = 1;
-const WRITE_THROTTLE_MS = 60_000;
 const MAX_SESSION_ID_LENGTH = 200;
 
-/** sessionID -> epoch ms of the last successful write, for throttling. */
-const writeThrottle = new Map<string, number>();
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function nonNegative(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
-}
-
 /** <pluginStateDir>/context/<sanitized-sessionID>.json */
 export function contextCapturePath(sessionID: string, env?: NodeJS.ProcessEnv): string {
   const raw = typeof sessionID === "string" ? sessionID : "";
@@ -35,10 +24,6 @@ export function contextCapturePath(sessionID: string, env?: NodeJS.ProcessEnv):
  * Reads and validates a capture. Returns null for a missing/unreadable file,
  * invalid JSON, an unsupported version, a session mismatch, non-string
  * provider/model, or non-finite/negative sizes and timestamps.
- *
- * Deliberately independent of the write-throttle map: the server plugin writes
- * and the TUI plugin reads in separate processes, so a reader can never have a
- * throttle entry of its own.
  */
 export async function readCapture(
   sessionID: string,
@@ -74,10 +59,7 @@ export async function readCapture(
   }
 }
 
-/**
- * Atomically persists a capture (temp file + rename), throttled to at most one
- * write per session per 60 s unless the provider/model changed. Never throws.
- */
+/** Atomically persists a capture (temp file + rename). Never throws. */
 export async function writeCapture(capture: SystemCapture, env?: NodeJS.ProcessEnv): Promise<void> {
   try {
     if (!isRecord(capture)) return;
@@ -92,14 +74,6 @@ export async function writeCapture(capture: SystemCapture, env?: NodeJS.ProcessE
     const capturedAt = nonNegative(capture.capturedAt);
     if (systemChars === null || systemTokens === null || capturedAt === null) return;
 
-    const previous = await readCapture(sessionID, env);
-    const modelChanged =
-      previous === null || previous.providerID !== providerID || previous.modelID !== modelID;
-
-    const now = Date.now();
-    const last = writeThrottle.get(sessionID);
-    if (!modelChanged && typeof last === "number" && now - last < WRITE_THROTTLE_MS) return;
-
     const directory = join(pluginStateDir(env), "context");
     await mkdir(directory, { recursive: true });
     const file = contextCapturePath(sessionID, env);
@@ -115,7 +89,6 @@ export async function writeCapture(capture: SystemCapture, env?: NodeJS.ProcessE
     const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
     await writeFile(tmp, JSON.stringify(normalized), "utf8");
     await rename(tmp, file);
-    writeThrottle.set(sessionID, now);
   } catch {
     // Capture writes are best-effort; a failure must never break a request.
   }
@@ -140,8 +113,3 @@ export function captureIsFresh(
   if (capturedAt === null || since === null) return false;
   return capturedAt >= since;
 }
-
-/** Clears the write-throttle map so tests can reset between cases. */
-export function resetCaptureThrottle(): void {
-  writeThrottle.clear();
-}

package/src/context/types.ts

@@ -7,7 +7,6 @@ export interface ContextRow {
   label: string;
   tokens: number | null;
   percent: number | null; // 0-100, null when the limit is unknown
-  exact: boolean;
 }
 
 export interface GridCell {

package/src/fallback.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import type { AdapterResult, UsageWindow } from "./types";
 import { dbPath } from "./paths";
+import { asRecord } from "./providers/http";
 
 const HOUR_MS = 60 * 60 * 1000;
 const DAY_MS = 24 * HOUR_MS;
@@ -15,12 +16,6 @@ interface SqliteDatabase {
 }
 type DatabaseSyncCtor = new (path: string, options?: { readOnly?: boolean }) => SqliteDatabase;
 
-function asRecord(value: unknown): Record<string, unknown> | null {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
 function toNum(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { Plugin } from "@opencode-ai/plugin";
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
 import { DEFAULT_OPTIONS, collectReports } from "./report";
 import { renderJson, renderText } from "./render";
@@ -39,12 +39,16 @@ export function coerceOptions(raw: Record<string, unknown> | undefined): PluginO
   return opts;
 }
 
-const plugin: Plugin = async ({ client }, options) => {
-  const opts = coerceOptions(options);
+/**
+ * Throttled warning pass shared by the V1 and V2 plugin APIs (spec §3.6/§3.7).
+ * Every failure is swallowed (spec §4): it must never throw into the event bus.
+ */
+function makeWarnRunner(
+  opts: PluginOptions,
+  notify: (message: string) => Promise<unknown> | unknown,
+): () => Promise<void> {
   let lastWarnCheck = 0;
-
-  /** Throttled warning pass (spec §3.7). Every failure is swallowed (spec §4). */
-  const runWarnCheck = async (): Promise<void> => {
+  return async (): Promise<void> => {
     try {
       if (Date.now() - lastWarnCheck < WARN_THROTTLE_MS) return;
       lastWarnCheck = Date.now();
@@ -53,9 +57,7 @@ const plugin: Plugin = async ({ client }, options) => {
       const hits = await checkWarnings(reports, opts.thresholdPercent);
       for (const hit of hits) {
         try {
-          await client.tui.showToast({
-            body: { title: "Usage warning", message: hit.message, variant: "warning" },
-          });
+          await notify(hit.message);
         } catch {
           // Toast delivery is best-effort; it is unavailable in headless/server mode.
         }
@@ -64,6 +66,159 @@ const plugin: Plugin = async ({ client }, options) => {
       // Never throw into the event bus.
     }
   };
+}
+
+async function runUsageReport(
+  args: Record<string, unknown> | undefined,
+  opts: PluginOptions,
+): Promise<{ content: string }> {
+  const reports = await collectReports({
+    providers: args?.provider ? [String(args.provider)] : undefined,
+    refresh: args?.refresh === true,
+    options: opts,
+  });
+  return { content: args?.json === true ? renderJson(reports) : renderText(reports) };
+}
+
+const TOOL_INPUT_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    provider: { type: "string" },
+    json: { type: "boolean" },
+    refresh: { type: "boolean" },
+  },
+  additionalProperties: false,
+};
+
+// ---------------------------------------------------------------------------
+// OpenCode 2.x (V2) plugin API.
+//
+// The harness decodes the module's default export against `{ id, setup }` or
+// `{ id, effect }` and otherwise fails with "Plugin must export a default
+// definition with an id and an effect or setup function" (err_b890e30e). The
+// context types are declared locally so the package needs no runtime dependency
+// on the V2 SDK; opencode erases `import type` anyway.
+// ---------------------------------------------------------------------------
+
+interface V2ToolDefinition {
+  name: string;
+  description: string;
+  input: Record<string, unknown>;
+  execute: (args: Record<string, unknown> | undefined) => Promise<{ content: string }>;
+}
+
+interface V2ToolEditor {
+  add(definition: V2ToolDefinition): void;
+}
+
+interface V2ContextEvent {
+  sessionID?: string;
+  model?: { providerID?: string; id?: string };
+  system?: Array<{ type?: string; text?: string } | string>;
+}
+
+interface V2PluginContext {
+  options?: Record<string, unknown>;
+  tool: { transform: (callback: (editor: V2ToolEditor) => void) => Promise<unknown> };
+  session: {
+    hook: (name: "context", handler: (event: V2ContextEvent) => unknown) => Promise<unknown>;
+  };
+  event: { subscribe: (options: { signal: AbortSignal }) => AsyncIterable<{ type?: string }> };
+  /** Not part of the V2 server context; present only if the runtime exposes it. */
+  tui?: { showToast?: (input: unknown) => Promise<unknown> };
+}
+
+/** Joins V2 system parts (text parts plus plain strings) into one prompt string. */
+function joinSystem(event: V2ContextEvent | undefined): string {
+  if (!Array.isArray(event?.system)) return "";
+  return event.system
+    .map((part) => (typeof part === "string" ? part : (part?.text ?? "")))
+    .join("\n");
+}
+
+/** Best-effort capture of the assembled system prompt size (spec §9.1). */
+async function captureSystemFromContext(event: V2ContextEvent | undefined): Promise<void> {
+  try {
+    const sessionID = event?.sessionID;
+    const model = event?.model;
+    if (typeof sessionID !== "string" || sessionID === "") return;
+    if (
+      model === undefined ||
+      typeof model.providerID !== "string" ||
+      typeof model.id !== "string"
+    ) {
+      return;
+    }
+
+    const system = joinSystem(event);
+    if (system === "") return;
+
+    await writeCapture({
+      version: 1,
+      sessionID,
+      providerID: model.providerID,
+      modelID: model.id,
+      systemChars: system.length,
+      systemTokens: estimateTokens(system),
+      capturedAt: Date.now(),
+    });
+  } catch {
+    // Best-effort: an experimental hook must never be able to break a request.
+  }
+}
+
+async function setup(ctx: V2PluginContext): Promise<() => void> {
+  const opts = coerceOptions(ctx?.options);
+
+  await ctx.tool.transform((editor) => {
+    editor.add({
+      name: "usage_report",
+      description: TOOL_DESCRIPTION,
+      input: TOOL_INPUT_SCHEMA,
+      execute: (args) => runUsageReport(args, opts),
+    });
+  });
+
+  await ctx.session.hook("context", (event) => captureSystemFromContext(event));
+
+  const runWarnCheck = makeWarnRunner(opts, (message) => {
+    const showToast = ctx.tui?.showToast;
+    if (typeof showToast !== "function") return;
+    return showToast({ body: { title: "Usage warning", message, variant: "warning" } });
+  });
+
+  // Spec §3.6: one throttled warning check at startup, fire-and-forget.
+  setTimeout(() => {
+    void runWarnCheck();
+  }, 0);
+
+  const controller = new AbortController();
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        if (event?.type === "session.idle") await runWarnCheck();
+      }
+    } catch {
+      // Subscription aborted on unload, or the event transport failed.
+    }
+  })();
+
+  return () => controller.abort();
+}
+
+// ---------------------------------------------------------------------------
+// OpenCode 1.x (V1) plugin API. Kept from the previous release so packages can
+// serve both APIs during the V2 migration; V2 calls `setup`, V1 calls `server`.
+// ---------------------------------------------------------------------------
+
+async function server({ client }: PluginInput, options?: Record<string, unknown>): Promise<Hooks> {
+  const opts = coerceOptions(options);
+
+  const runWarnCheck = makeWarnRunner(opts, (message) =>
+    client.tui.showToast({
+      body: { title: "Usage warning", message, variant: "warning" },
+    }),
+  );
 
   // Spec §3.6: one throttled warning check at startup, fire-and-forget.
   setTimeout(() => {
@@ -80,12 +235,7 @@ const plugin: Plugin = async ({ client }, options) => {
           refresh: tool.schema.boolean().optional(),
         },
         async execute(args) {
-          const reports = await collectReports({
-            providers: args.provider ? [args.provider] : undefined,
-            refresh: args.refresh === true,
-            options: opts,
-          });
-          return args.json ? renderJson(reports) : renderText(reports);
+          return (await runUsageReport(args, opts)).content;
         },
       }),
     },
@@ -126,6 +276,12 @@ const plugin: Plugin = async ({ client }, options) => {
       }
     },
   };
+}
+
+const definition = {
+  id: "opencode-usage-report",
+  setup,
+  server,
 };
 
-export default plugin;
+export default definition;