opencode-usage-report 0.2.0 → 0.4.0

package/src/context/collect.ts

@@ -0,0 +1,251 @@
+import type { AssistantMessage, Part } from "@opencode-ai/sdk/v2";
+import type { CollectInput, ContextBreakdown, ContextRow, RowKey, SystemCapture } from "./types";
+import { estimateJson, estimateTokens } from "./estimate";
+import { buildGrid } from "./grid";
+import { computeHeadroom } from "./headroom";
+
+const ROW_LABELS: Record<RowKey, string> = {
+  user: "User messages",
+  agent: "Agent responses",
+  reasoning: "Reasoning",
+  tools: "Tool calls",
+  system: "System & tools",
+  free: "Free space",
+};
+
+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";
+}
+
+function readParts(accessor: CollectInput["part"], messageID: string): readonly Part[] {
+  if (typeof accessor !== "function") return [];
+  try {
+    const parts = accessor(messageID);
+    return Array.isArray(parts) ? parts : [];
+  } catch {
+    return [];
+  }
+}
+
+function lastReportingAssistant(messages: readonly unknown[]): AssistantMessage | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!isAssistant(message)) continue;
+    const output = finiteOrNull(isRecord(message.tokens) ? message.tokens.output : undefined);
+    if (output !== null && output > 0) return message;
+  }
+  return null;
+}
+
+function summaryStartIndex(messages: readonly unknown[]): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (isAssistant(message) && message.summary === true) return i + 1;
+  }
+  return 0;
+}
+
+function isUsableCapture(capture: SystemCapture | null | undefined): capture is SystemCapture {
+  if (!isRecord(capture)) return false;
+  const tokens = finiteOrNull(capture.systemTokens);
+  return capture.version === 1 && tokens !== null && tokens >= 0;
+}
+
+/**
+ * Scales `values` so they sum to `target` by the largest-remainder method; the
+ * result never exceeds `target`. Used when raw `chars/4` estimates overshoot.
+ */
+function largestRemainderScale(
+  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;
+}
+
+function makeRow(
+  key: RowKey,
+  tokens: number | null,
+  exact: boolean,
+  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 };
+}
+
+function emptyRows(limit: number | null): ContextRow[] {
+  return [...MEASURED_KEYS, "free" as RowKey].map((key) =>
+    makeRow(key, null, key === "free", limit),
+  );
+}
+
+/**
+ * Builds a `ContextBreakdown` from session messages. Exact prompt totals come
+ * from the last reporting assistant message; the remaining rows are `chars/4`
+ * estimates normalized against that total. Never throws and never emits NaN.
+ */
+export function collectContext(input: CollectInput): ContextBreakdown {
+  const source = (isRecord(input) ? input : {}) as CollectInput;
+  const messages: readonly unknown[] = Array.isArray(source.messages) ? source.messages : [];
+  const limit = finiteOrNull(source.model?.limit?.context);
+  const modelName = typeof source.model?.name === "string" ? source.model.name : null;
+  const cost = finiteOrNull(source.sessionCost) ?? 0;
+  const systemDerived = !isUsableCapture(source.system);
+  const systemCaptured = systemDerived ? null : (source.system as SystemCapture).systemTokens;
+  const cols = typeof source.cols === "number" && Number.isFinite(source.cols) ? source.cols : null;
+
+  const last = lastReportingAssistant(messages);
+  if (last === null) {
+    const rows = emptyRows(limit);
+    return {
+      ready: false,
+      modelName,
+      total: null,
+      limit,
+      cost,
+      rows,
+      grid: buildGrid({ rows, limit, total: null, cols }),
+      headroom: computeHeadroom({
+        limit: source.model?.limit ?? null,
+        total: null,
+        compaction: source.compaction ?? null,
+      }),
+      systemDerived,
+      systemCaptured,
+      prunedToolOutputs: 0,
+    };
+  }
+
+  const tokens: Record<string, unknown> = isRecord(last.tokens) ? last.tokens : {};
+  const cache: Record<string, unknown> = isRecord(tokens.cache) ? tokens.cache : {};
+  const total = Math.max(
+    0,
+    (finiteOrNull(tokens.input) ?? 0) +
+      (finiteOrNull(cache.read) ?? 0) +
+      (finiteOrNull(cache.write) ?? 0),
+  );
+
+  let userTokens = 0;
+  let agentTokens = 0;
+  let reasoningTokens = 0;
+  let toolsTokens = 0;
+  let prunedToolOutputs = 0;
+
+  const start = summaryStartIndex(messages);
+  for (let i = start; i < messages.length; i++) {
+    const message = messages[i];
+    if (!isRecord(message)) continue;
+    const role = message.role;
+    if (role !== "user" && role !== "assistant") continue;
+    const messageID = typeof message.id === "string" ? message.id : "";
+
+    for (const part of readParts(source.part, messageID)) {
+      if (!isRecord(part)) continue;
+      const type = part.type;
+
+      if (type === "text") {
+        const estimated = estimateTokens(safeString(part.text));
+        if (role === "user") userTokens += estimated;
+        else agentTokens += estimated;
+      } else if (type === "reasoning") {
+        if (role === "assistant") reasoningTokens += estimateTokens(safeString(part.text));
+      } else if (type === "file") {
+        if (role === "user") {
+          userTokens += estimateTokens(safeString(part.filename) + safeString(part.mime));
+        }
+      } else if (type === "tool") {
+        const state = part.state;
+        const stateRecord: Record<string, unknown> = isRecord(state) ? state : {};
+        const timeRecord: Record<string, unknown> = isRecord(stateRecord.time)
+          ? stateRecord.time
+          : {};
+        if (timeRecord.compacted !== undefined && timeRecord.compacted !== null) {
+          prunedToolOutputs += 1;
+          continue;
+        }
+        toolsTokens +=
+          estimateJson(stateRecord.input) + estimateTokens(safeString(stateRecord.output));
+      }
+      // step-start, step-finish, snapshot and every other part type are skipped.
+    }
+  }
+
+  const estimatedSum = userTokens + agentTokens + reasoningTokens + toolsTokens;
+  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).
+  if (estimatedSum > total) {
+    const scaled = largestRemainderScale(
+      [userTokens, agentTokens, reasoningTokens, toolsTokens, systemTokens],
+      total,
+      estimatedSum,
+    );
+    userTokens = scaled[0];
+    agentTokens = scaled[1];
+    reasoningTokens = scaled[2];
+    toolsTokens = scaled[3];
+    systemTokens = scaled[4];
+  }
+
+  const measured = [userTokens, agentTokens, reasoningTokens, toolsTokens, systemTokens];
+  const rows = MEASURED_KEYS.map((key, index) => makeRow(key, measured[index], false, limit));
+  const freeTokens = limit !== null ? Math.max(0, limit - total) : null;
+  rows.push(makeRow("free", freeTokens, true, limit));
+
+  return {
+    ready: true,
+    modelName,
+    total,
+    limit,
+    cost,
+    rows,
+    grid: buildGrid({ rows, limit, total, cols }),
+    headroom: computeHeadroom({
+      limit: source.model?.limit ?? null,
+      total,
+      compaction: source.compaction ?? null,
+    }),
+    systemDerived,
+    systemCaptured,
+    prunedToolOutputs,
+  };
+}

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