opencode-usage-report 0.2.0 → 0.4.0

package/src/context/format.ts

@@ -0,0 +1,272 @@
+/**
+ * Pure formatting for the context-usage block. Turns a `ContextBreakdown` into
+ * pre-colored text lines (theme color names, resolved by the TSX layer) in the
+ * same shape `buildLines` uses in `src/quota-lines.ts`.
+ */
+import type { ContextBreakdown, ContextRow, GridCell, RowKey } from "./types";
+
+/** Theme color names used by the context block. */
+export type ContextTone =
+  | "text"
+  | "textMuted"
+  | "borderSubtle"
+  | "info"
+  | "success"
+  | "secondary"
+  | "warning"
+  | "error";
+
+export interface Segment {
+  text: string;
+  fg: ContextTone;
+  bold?: boolean;
+}
+
+export interface Line {
+  segments: Segment[];
+}
+
+export interface BuildContextLinesOptions {
+  /** Fallback shown when `breakdown.modelName` is null (e.g. raw providerID/modelID). */
+  modelLabel?: string | null;
+}
+
+const GRID_ROWS = 6;
+const GRID_MAX_WIDTH = 116;
+const GRID_MAX_COLS = Math.floor(GRID_MAX_WIDTH / 2);
+const LEGEND_LABEL_WIDTH = 24;
+const LEGEND_COUNT_WIDTH = 9;
+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",
+  reasoning: "secondary",
+  tools: "warning",
+  system: "textMuted",
+  free: "borderSubtle",
+};
+
+const LEGEND_KEYS: readonly RowKey[] = ["user", "agent", "reasoning", "tools", "system", "free"];
+const BAND_TONES: Record<"ok" | "warning" | "error", ContextTone> = {
+  ok: "success",
+  warning: "warning",
+  error: "error",
+};
+
+const MONEY = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
+
+/** Locale-grouped integer token count; non-finite input renders as `0`. */
+export function formatTokens(n: number): string {
+  const value = typeof n === "number" && Number.isFinite(n) ? Math.round(n) : 0;
+  return value.toLocaleString("en-US");
+}
+
+/** USD currency string (e.g. `$0.42`); non-finite input renders as `$0.00`. */
+export function formatMoney(n: number): string {
+  const value = typeof n === "number" && Number.isFinite(n) ? n : 0;
+  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 "▒▒";
+  if (fill <= 0.75) return "▓▓";
+  return "██";
+}
+
+function toneForRowKey(key: unknown): ContextTone {
+  if (typeof key !== "string") return "borderSubtle";
+  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%`.
+ */
+export function formatPercent(percent: number): string {
+  const value = typeof percent === "number" && Number.isFinite(percent) ? percent : 0;
+  if (value > 0 && value < 0.1) return "<0.1%";
+  return `${Math.min(100, Math.max(0, value)).toFixed(1)}%`;
+}
+
+function headerMetric(breakdown: ContextBreakdown): string {
+  if (breakdown.ready !== true) return "0 (0.0%)";
+  const total = nonNegative(breakdown.total) ?? 0;
+  const limit = nonNegative(breakdown.limit);
+  if (limit === null || limit <= 0) return `${formatTokens(total)} tokens`;
+  const percent = (total / limit) * 100;
+  return `${formatTokens(total)} / ${formatTokens(limit)} tokens (${formatPercent(percent)})`;
+}
+
+function rowMap(breakdown: ContextBreakdown): Map<RowKey, ContextRow> {
+  const map = new Map<RowKey, ContextRow>();
+  const rows = Array.isArray(breakdown.rows) ? breakdown.rows : [];
+  for (const row of rows) {
+    if (row !== null && typeof row === "object" && typeof row.key === "string") {
+      map.set(row.key, row);
+    }
+  }
+  return map;
+}
+
+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 label = key === "system" && systemDerived ? `${baseLabel} (derived)` : baseLabel;
+  const tokens = nonNegative(row?.tokens);
+  const percent = nonNegative(row?.percent);
+  const percentText = percent === null ? "—" : formatPercent(percent);
+  return [
+    { text: "● ", fg: CATEGORY_TONES[key] },
+    { text: padLabel(label, LEGEND_LABEL_WIDTH), fg: "text" },
+    {
+      text: rightAlign(tokens === null ? "—" : formatTokens(tokens), LEGEND_COUNT_WIDTH),
+      fg: "text",
+    },
+    { text: " ", fg: "text" },
+    { text: rightAlign(percentText, LEGEND_PERCENT_WIDTH), fg: "textMuted" },
+  ];
+}
+
+function gridLines(breakdown: ContextBreakdown): Line[] {
+  const grid = breakdown.grid;
+  const cols = nonNegative(grid?.cols);
+  if (cols === null || cols <= 0) return [];
+  const requestedRows = nonNegative(grid?.rows);
+  const rows = requestedRows !== null && requestedRows >= 1 ? Math.floor(requestedRows) : GRID_ROWS;
+  const renderCols = Math.min(Math.floor(cols), GRID_MAX_COLS);
+  const cells: readonly GridCell[] = Array.isArray(grid?.cells) ? grid.cells : [];
+
+  const lines: Line[] = [];
+  for (let r = 0; r < rows; r++) {
+    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));
+      segments.push({ text: glyphFor(fill), fg: toneForRowKey(cell?.rowKey) });
+    }
+    lines.push({ segments });
+  }
+  return lines;
+}
+
+function headroomSegments(breakdown: ContextBreakdown): Segment[] {
+  const usable = nonNegative(breakdown.headroom?.usable);
+  if (usable === null || breakdown.ready !== true) return [];
+  const free = nonNegative(breakdown.headroom?.free) ?? 0;
+  const band = breakdown.headroom?.band;
+  const tone = band === "warning" || band === "error" ? BAND_TONES[band] : BAND_TONES.ok;
+  const segments: Segment[] = [
+    { text: `Auto-compacts at ${formatTokens(usable)} · ${formatTokens(free)} headroom`, fg: tone },
+  ];
+  const cost = nonNegative(breakdown.cost);
+  if (cost !== null && cost > 0) {
+    segments.push({ text: ` · ${formatMoney(cost)} spent`, fg: "textMuted" });
+  }
+  return segments;
+}
+
+/** Renders a context breakdown as pre-colored lines; empty until the first response. */
+export function buildContextLines(
+  breakdown: ContextBreakdown,
+  options: BuildContextLinesOptions = {},
+): Line[] {
+  const source = (breakdown ?? {}) as ContextBreakdown;
+  const lines: Line[] = [];
+
+  const modelName =
+    typeof source.modelName === "string" && source.modelName !== "" ? source.modelName : null;
+  const fallback =
+    typeof options.modelLabel === "string" && options.modelLabel !== "" ? options.modelLabel : null;
+  const name = modelName ?? fallback;
+
+  const header: Segment[] = [];
+  if (name !== null) {
+    header.push({ text: name, fg: "text", bold: true });
+    header.push({ text: " · ", fg: "textMuted" });
+  }
+  header.push({ text: headerMetric(source), fg: "text" });
+  lines.push({ segments: header });
+
+  if (source.ready !== true) {
+    lines.push({ segments: [{ text: "awaiting first response", fg: "textMuted" }] });
+  }
+
+  const limit = nonNegative(source.limit);
+  if (limit !== null && limit > 0) {
+    lines.push(...gridLines(source));
+  }
+
+  const rows = rowMap(source);
+  const derived = source.systemDerived === true;
+  for (let i = 0; i < LEGEND_KEYS.length / 2; i++) {
+    const leftKey = LEGEND_KEYS[i];
+    const rightKey = LEGEND_KEYS[i + COLUMNS_PER_LEGEND_ROW];
+    lines.push({
+      segments: [
+        ...legendEntry(leftKey, rows.get(leftKey), derived),
+        { text: LEGEND_GAP, fg: "text" },
+        ...legendEntry(rightKey, rows.get(rightKey), derived),
+      ],
+    });
+  }
+
+  const captured = nonNegative(source.systemCaptured);
+  if (captured !== null) {
+    const systemTokens = nonNegative(rows.get("system")?.tokens) ?? 0;
+    const framing = Math.max(0, systemTokens - captured);
+    const prefix = `↳ ${formatTokens(captured)} system prompt + `;
+    const suffix = `${formatTokens(framing)} tools & framing`;
+    lines.push({ segments: [{ text: prefix + suffix, fg: "textMuted" }] });
+  }
+
+  const headroom = headroomSegments(source);
+  if (headroom.length > 0) lines.push({ segments: headroom });
+
+  const pruned = nonNegative(source.prunedToolOutputs);
+  if (pruned !== null && pruned > 0) {
+    lines.push({
+      segments: [
+        { text: `${formatTokens(pruned)} tool outputs pruned from context`, fg: "textMuted" },
+      ],
+    });
+  }
+
+  return lines;
+}

package/src/context/grid.ts

@@ -0,0 +1,90 @@
+import type { ContextRow, GridCell, RowKey } from "./types";
+
+const GRID_ROWS_DEFAULT = 6;
+const MIN_COLS = 8;
+const MAX_COLS = 60;
+const CATEGORY_ORDER: readonly RowKey[] = ["user", "agent", "reasoning", "tools", "system"];
+
+export interface BuildGridInput {
+  rows: readonly ContextRow[];
+  limit: number | null;
+  total: number | null;
+  cols?: number | null;
+  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) {
+    if (row !== null && typeof row === "object" && row.key === key) {
+      const tokens = finiteOrNull(row.tokens);
+      return tokens !== null && tokens > 0 ? tokens : 0;
+    }
+  }
+  return 0;
+}
+
+function categoryAt(
+  ranges: readonly { key: RowKey; start: number; end: number }[],
+  position: number,
+): RowKey | null {
+  for (const range of ranges) {
+    if (position >= range.start && position < range.end) return range.key;
+  }
+  return null;
+}
+
+/**
+ * Lays out the grid of square cells from the five measured rows. Cells are in
+ * row-major order; only the cell straddling `total` is partial and free space
+ * is never materialised.
+ */
+export function buildGrid(input: BuildGridInput): {
+  cols: number;
+  rows: number;
+  cells: GridCell[];
+} {
+  const cols = clampCols(input.cols);
+  const rows = clampGridRows(input.gridRows);
+  const limit = finiteOrNull(input.limit);
+  if (limit === null || limit <= 0) return { cols, rows, cells: [] };
+
+  const total = Math.max(0, finiteOrNull(input.total) ?? 0);
+  const cellCount = cols * rows;
+  const tokensPerCell = limit / cellCount;
+
+  const ranges: { key: RowKey; start: number; end: number }[] = [];
+  let acc = 0;
+  for (const key of CATEGORY_ORDER) {
+    const value = rowTokens(input.rows, key);
+    ranges.push({ key, start: acc, end: acc + value });
+    acc += value;
+  }
+
+  const cells: GridCell[] = [];
+  for (let i = 0; i < cellCount; i++) {
+    const position = i * tokensPerCell;
+    if (total <= 0 || position >= total) {
+      cells.push({ rowKey: null, fill: 0 });
+      continue;
+    }
+    const key = categoryAt(ranges, position) ?? CATEGORY_ORDER[CATEGORY_ORDER.length - 1];
+    cells.push({ rowKey: key, fill: Math.min(1, Math.max(0, (total - position) / tokensPerCell)) });
+  }
+
+  return { cols, rows, cells };
+}

package/src/context/headroom.ts

@@ -0,0 +1,42 @@
+import type { Model } from "@opencode-ai/sdk/v2";
+
+export interface Headroom {
+  usable: number | null;
+  free: number | null;
+  band: "ok" | "warning" | "error";
+}
+
+export interface HeadroomInput {
+  limit: Model["limit"] | null | undefined;
+  total: number | null;
+  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;
+  const context = finiteOrNull(limit?.context);
+  const maxOutput = finiteOrNull(limit?.output);
+  if (context === null || maxOutput === null) return { usable: null, free: null, band: "ok" };
+
+  const reservedDefault = Math.min(20000, Math.max(0, maxOutput));
+  const configured = finiteOrNull(input.compaction?.reserved);
+  const reserved = configured !== null && configured >= 0 ? configured : reservedDefault;
+
+  const inputLimit = finiteOrNull(limit?.input);
+  const usable =
+    inputLimit !== null
+      ? Math.max(0, inputLimit - reserved)
+      : Math.max(0, context - Math.max(0, maxOutput));
+
+  const total = finiteOrNull(input.total);
+  if (total === null) return { usable, free: null, band: "ok" };
+
+  const free = usable - total;
+  const band = free <= usable * 0.05 ? "error" : free <= usable * 0.15 ? "warning" : "ok";
+  return { usable, free, band };
+}

package/src/context/system.ts

@@ -0,0 +1,147 @@
+/**
+ * System-prompt capture sidecar. The server plugin writes the fully joined
+ * system prompt's size once per request; the TUI reads it back to split the
+ * residual "System & tools" row. Every operation is best-effort and total:
+ * failures degrade to `null` and must never break a request.
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { SystemCapture } from "./types";
+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 : "";
+  const safe = raw.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_SESSION_ID_LENGTH) || "_";
+  return join(pluginStateDir(env), "context", `${safe}.json`);
+}
+
+/**
+ * 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,
+  env?: NodeJS.ProcessEnv,
+): Promise<SystemCapture | null> {
+  try {
+    if (typeof sessionID !== "string") return null;
+
+    const raw = await readFile(contextCapturePath(sessionID, env), "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (!isRecord(parsed)) return null;
+    if (parsed.version !== CAPTURE_VERSION) return null;
+    if (parsed.sessionID !== sessionID) return null;
+    if (typeof parsed.providerID !== "string" || parsed.providerID === "") return null;
+    if (typeof parsed.modelID !== "string" || parsed.modelID === "") return null;
+
+    const systemChars = nonNegative(parsed.systemChars);
+    const systemTokens = nonNegative(parsed.systemTokens);
+    const capturedAt = nonNegative(parsed.capturedAt);
+    if (systemChars === null || systemTokens === null || capturedAt === null) return null;
+
+    return {
+      version: CAPTURE_VERSION,
+      sessionID,
+      providerID: parsed.providerID,
+      modelID: parsed.modelID,
+      systemChars,
+      systemTokens,
+      capturedAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+export async function writeCapture(capture: SystemCapture, env?: NodeJS.ProcessEnv): Promise<void> {
+  try {
+    if (!isRecord(capture)) return;
+    const { sessionID, providerID, modelID } = capture;
+    if (typeof sessionID !== "string" || sessionID === "") return;
+    if (typeof providerID !== "string" || providerID === "") return;
+    if (typeof modelID !== "string" || modelID === "") return;
+    if (capture.version !== CAPTURE_VERSION) return;
+
+    const systemChars = nonNegative(capture.systemChars);
+    const systemTokens = nonNegative(capture.systemTokens);
+    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);
+    const normalized: SystemCapture = {
+      version: CAPTURE_VERSION,
+      sessionID,
+      providerID,
+      modelID,
+      systemChars,
+      systemTokens,
+      capturedAt,
+    };
+    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.
+  }
+}
+
+/**
+ * True only when the capture matches the session/provider/model and was taken
+ * at or after `since`.
+ */
+export function captureIsFresh(
+  capture: SystemCapture | null | undefined,
+  reference: { sessionID: string; providerID: string; modelID: string; since: number },
+): boolean {
+  if (!isRecord(capture)) return false;
+  const ref = isRecord(reference) ? reference : null;
+  if (ref === null) return false;
+  if (capture.sessionID !== ref.sessionID) return false;
+  if (capture.providerID !== ref.providerID) return false;
+  if (capture.modelID !== ref.modelID) return false;
+  const capturedAt = nonNegative(capture.capturedAt);
+  const since = nonNegative(ref.since);
+  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

@@ -0,0 +1,51 @@
+import type { Message, Model, Part } from "@opencode-ai/sdk/v2";
+
+export type RowKey = "user" | "agent" | "reasoning" | "tools" | "system" | "free";
+
+export interface ContextRow {
+  key: RowKey;
+  label: string;
+  tokens: number | null;
+  percent: number | null; // 0-100, null when the limit is unknown
+  exact: boolean;
+}
+
+export interface GridCell {
+  rowKey: RowKey | null; // null = free space
+  fill: number; // 0..1
+}
+
+export interface ContextBreakdown {
+  ready: boolean;
+  modelName: string | null;
+  total: number | null;
+  limit: number | null;
+  cost: number;
+  rows: ContextRow[];
+  grid: { cols: number; rows: number; cells: GridCell[] };
+  headroom: { usable: number | null; free: number | null; band: "ok" | "warning" | "error" };
+  systemDerived: boolean;
+  /** Measured system-prompt tokens when a valid capture was supplied, else null. */
+  systemCaptured: number | null;
+  prunedToolOutputs: number;
+}
+
+export interface SystemCapture {
+  version: 1;
+  sessionID: string;
+  providerID: string;
+  modelID: string;
+  systemChars: number;
+  systemTokens: number;
+  capturedAt: number;
+}
+
+export interface CollectInput {
+  messages: readonly Message[];
+  model: Model | null;
+  part?: ((messageID: string) => readonly Part[]) | null;
+  system?: SystemCapture | null;
+  sessionCost?: number;
+  cols?: number | null;
+  compaction?: { reserved?: number } | null;
+}

package/src/fallback.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
-import type { AdapterResult, UsageWindow } from "./types.js";
-import { dbPath } from "./paths.js";
+import type { AdapterResult, UsageWindow } from "./types";
+import { dbPath } from "./paths";
 
 const HOUR_MS = 60 * 60 * 1000;
 const DAY_MS = 24 * HOUR_MS;

package/src/index.ts

@@ -1,11 +1,13 @@
 import type { Plugin } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
-import { DEFAULT_OPTIONS, collectReports } from "./report.js";
-import { renderJson, renderText } from "./render.js";
-import { checkWarnings } from "./warn.js";
-import { toNumber } from "./normalize.js";
-import { adapters } from "./providers/index.js";
-import type { PluginOptions } from "./types.js";
+import { DEFAULT_OPTIONS, collectReports } from "./report";
+import { renderJson, renderText } from "./render";
+import { checkWarnings } from "./warn";
+import { toNumber } from "./normalize";
+import { adapters } from "./providers/index";
+import { estimateTokens } from "./context/estimate";
+import { writeCapture } from "./context/system";
+import type { PluginOptions } from "./types";
 
 const WARN_THROTTLE_MS = 10 * 60 * 1000;
 
@@ -13,9 +15,6 @@ const TOOL_DESCRIPTION =
   "Show subscription usage/quota windows (5h, weekly, monthly) for configured inference providers " +
   `(${adapters.map((adapter) => adapter.id).join(", ")})`;
 
-const COMMAND_TEMPLATE =
-  "Call the usage_report tool with these arguments: $ARGUMENTS and present the result verbatim.";
-
 /** Merges user plugin options over defaults, defensively ignoring malformed values. */
 export function coerceOptions(raw: Record<string, unknown> | undefined): PluginOptions {
   const opts: PluginOptions = { ...DEFAULT_OPTIONS };
@@ -91,12 +90,31 @@ const plugin: Plugin = async ({ client }, options) => {
       }),
     },
 
-    async config(cfg) {
-      cfg.command ??= {};
-      cfg.command.usage ??= {
-        description: "Show subscription usage/quota windows for configured providers",
-        template: COMMAND_TEMPLATE,
-      };
+    // `/usage` is owned by the TUI plugin so the slash command opens a local
+    // dialog instead of routing through the model. This hook's only job is to
+    // measure the assembled system prompt, which opencode never persists, so
+    // the TUI can split the "System & tools" residual (spec §9.1).
+    async "experimental.chat.system.transform"(input, output) {
+      try {
+        const sessionID = input?.sessionID;
+        if (typeof sessionID !== "string" || sessionID === "") return;
+        const model = input?.model;
+        if (model === undefined) return;
+        const system = Array.isArray(output?.system) ? output.system.join("\n") : "";
+        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 event({ event }) {

package/src/normalize.ts

@@ -1,4 +1,4 @@
-import type { UsageWindow, WindowKind } from "./types.js";
+import type { UsageWindow, WindowKind } from "./types";
 
 /** Accepts a number or a numeric string; anything else (including NaN/Infinity) yields null. */
 export function toNumber(v: unknown): number | null {