opencode-usage-report 0.3.0 → 0.4.0

package/src/context/dialog.tsx

@@ -0,0 +1,184 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { AssistantMessage, Model } from "@opencode-ai/sdk/v2";
+import { For, Show, createMemo } from "solid-js";
+import { buildContextLines, type ContextTone } from "./format";
+import { collectContext } from "./collect";
+import { captureIsFresh } from "./system";
+import type { ContextBreakdown, SystemCapture } from "./types";
+import { buildLines } from "../quota-lines";
+import type { ProviderReport } from "../types";
+
+type Theme = TuiPluginApi["theme"]["current"];
+
+const GRID_COLS = 48;
+
+export interface UsageDialogProps {
+  api: TuiPluginApi;
+  sessionID: string | null;
+  /** Accessors, not values: the dialog must stay live while the dialog is open. */
+  reports: () => ProviderReport[];
+  busy: () => boolean;
+  error: () => string | null;
+  now: () => Date;
+  system: () => SystemCapture | null;
+  scope: () => number;
+  showJson: () => boolean;
+  barWidth: number;
+}
+
+/**
+ * A rendered line. `fg` is either a theme color name (context block) or an
+ * already-resolved RGBA (quota block), so both feeds share one renderer.
+ */
+interface RenderedLine {
+  segments: { text: string; fg: unknown; bold?: boolean }[];
+}
+
+function resolveColor(theme: Theme, fg: unknown) {
+  return typeof fg === "string" ? theme[fg as ContextTone] : fg;
+}
+
+/** Renders pre-colored lines; shared by the context, quota and raw blocks. */
+function Lines(props: { lines: RenderedLine[]; theme: Theme }) {
+  return (
+    <For each={props.lines}>
+      {(line) => (
+        <text>
+          {line.segments.map((seg) => {
+            const color = resolveColor(props.theme, seg.fg);
+            return seg.bold ? (
+              <b style={{ fg: color }}>{seg.text}</b>
+            ) : (
+              <span style={{ fg: color }}>{seg.text}</span>
+            );
+          })}
+        </text>
+      )}
+    </For>
+  );
+}
+
+function jsonLines(value: unknown): RenderedLine[] {
+  let text: string;
+  try {
+    text = JSON.stringify(value, null, 2) ?? "";
+  } catch {
+    text = "{}";
+  }
+  return text.split("\n").map((row) => ({ segments: [{ text: row, fg: "textMuted" as const }] }));
+}
+
+/** The `/usage` dialog: context usage on top, the existing quota output below. */
+export function UsageDialog(props: UsageDialogProps) {
+  const theme = () => props.api.theme.current;
+
+  const messages = createMemo(() =>
+    props.sessionID === null ? [] : props.api.state.session.messages(props.sessionID),
+  );
+  const reference = createMemo(() =>
+    messages().findLast(
+      (item): item is AssistantMessage => item.role === "assistant" && item.tokens.output > 0,
+    ),
+  );
+  const model = createMemo<Model | undefined>(() => {
+    const last = reference();
+    if (last === undefined) return undefined;
+    return props.api.state.provider.find((item) => item.id === last.providerID)?.models[
+      last.modelID
+    ];
+  });
+
+  /** The capture only counts when it matches this message's session, model and turn. */
+  const freshCapture = createMemo<SystemCapture | null>(() => {
+    const last = reference();
+    const capture = props.system();
+    if (last === undefined || capture === null) return null;
+    const ok = captureIsFresh(capture, {
+      sessionID: last.sessionID,
+      providerID: last.providerID,
+      modelID: last.modelID,
+      since: last.time?.created ?? 0,
+    });
+    return ok ? capture : null;
+  });
+
+  const scopedReports = createMemo(() => {
+    const all = props.reports();
+    if (props.scope() <= 0) return all;
+    const target = all[props.scope() - 1];
+    return target === undefined ? all : [target];
+  });
+
+  const breakdown = createMemo<ContextBreakdown>(() =>
+    collectContext({
+      messages: messages(),
+      model: model() ?? null,
+      part: (messageID) => props.api.state.part(messageID),
+      system: freshCapture(),
+      sessionCost:
+        props.sessionID === null ? 0 : (props.api.state.session.get(props.sessionID)?.cost ?? 0),
+      cols: GRID_COLS,
+      compaction: props.api.state.config?.compaction ?? null,
+    }),
+  );
+
+  const modelLabel = createMemo(() => {
+    const last = reference();
+    return last === undefined ? null : `${last.providerID}/${last.modelID}`;
+  });
+
+  const contextLines = createMemo(() =>
+    buildContextLines(breakdown(), { modelLabel: modelLabel() }),
+  );
+  const quotaLines = createMemo(() =>
+    buildLines(theme(), scopedReports(), props.busy(), props.error(), props.now(), props.barWidth),
+  );
+  const rawLines = createMemo(() => jsonLines({ context: breakdown(), reports: scopedReports() }));
+
+  const footer = createMemo(() => {
+    const hints = ["esc close"];
+    if (props.reports().length > 1) {
+      const current = props.scope() <= 0 ? "all" : (scopedReports()[0]?.provider ?? "?");
+      hints.push(`tab scope: ${current}`);
+    }
+    hints.push("r refresh", "j json");
+    return hints.join("  ·  ");
+  });
+
+  return (
+    <box paddingLeft={2} paddingRight={2} paddingBottom={1} flexDirection="column" gap={1}>
+      <box flexDirection="row" justifyContent="space-between">
+        <text fg={theme().text}>
+          <b>Usage</b>
+        </text>
+        <text fg={theme().textMuted}>{footer()}</text>
+      </box>
+
+      <Show
+        when={!props.showJson()}
+        fallback={
+          <box flexDirection="column" gap={1}>
+            <text fg={theme().accent}>
+              <b>Raw</b>
+            </text>
+            <Lines lines={rawLines()} theme={theme()} />
+          </box>
+        }
+      >
+        <box flexDirection="column">
+          <text fg={theme().accent}>
+            <b>Context</b>
+          </text>
+          <Lines lines={contextLines()} theme={theme()} />
+        </box>
+
+        <text fg={theme().borderSubtle}>{"─".repeat(100)}</text>
+
+        <box flexDirection="column">
+          <Lines lines={quotaLines()} theme={theme()} />
+        </box>
+      </Show>
+    </box>
+  );
+}

package/src/context/estimate.ts

@@ -0,0 +1,36 @@
+/** Mirrors opencode's `chars/4` estimator: non-string input yields 0, never NaN. */
+export function estimateTokens(text: string): number {
+  const value: unknown = text;
+  if (typeof value !== "string") return 0;
+  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.
+ */
+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);
+}

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 };
+}