opencode-usage-report 0.3.0 → 0.4.0

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/index.ts

@@ -5,6 +5,8 @@ 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/quota-lines.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure line-building for the sidebar quota panel, extracted verbatim from
+ * `src/tui.tsx` so the formatting can be unit-tested and later reused by the
+ * `/usage` dialog. No JSX and no Solid imports (only the shared formatting
+ * helpers and types).
+ */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { ProviderReport, WindowKind } from "./types";
+import { bar, countdown, percentText, toneFor, windowLabel } from "./tui-format";
+
+type Theme = TuiPluginApi["theme"]["current"];
+type ThemeColor = Theme["text"];
+
+export interface Segment {
+  text: string;
+  fg: ThemeColor;
+  bold?: boolean;
+}
+
+export interface Line {
+  segments: Segment[];
+}
+
+export const NAMED_WIDTH = 14;
+export const EXTRAS_MAX_LENGTH = 80;
+
+/** Order windows for display; unknown kinds sort last. */
+export const WINDOW_ORDER: Record<WindowKind, number> = {
+  "5h": 0,
+  weekly: 1,
+  monthly: 2,
+  daily: 3,
+  other: 4,
+};
+
+export function windowRank(kind: WindowKind): number {
+  return WINDOW_ORDER[kind] ?? WINDOW_ORDER.other;
+}
+
+/** Collapses whitespace and truncates to a single-line label. */
+export function clip(value: string, max = 60): string {
+  const single = value.replace(/\s+/g, " ").trim();
+  if (single.length <= max) return single;
+  return single.slice(0, Math.max(0, max - 1)) + "…";
+}
+
+/** Pads a label to a fixed width, truncating (with a trailing space) when long. */
+export function alignLabel(label: string): string {
+  const text = label.length > NAMED_WIDTH ? label.slice(0, NAMED_WIDTH - 1) + " " : label;
+  return text.padEnd(NAMED_WIDTH);
+}
+
+/** Flattens provider reports into plain, pre-colored text lines. */
+export function buildLines(
+  theme: Theme,
+  reports: ProviderReport[],
+  busy: boolean,
+  error: string | null,
+  now: Date,
+  barWidth: number,
+): Line[] {
+  const lines: Line[] = [];
+
+  if (error !== null) {
+    lines.push({
+      segments: [{ text: `api error: ${clip(error)}`, fg: theme.error }],
+    });
+  }
+
+  if (reports.length === 0 && busy) {
+    lines.push({
+      segments: [{ text: "loading…", fg: theme.textMuted }],
+    });
+  }
+
+  for (const report of reports) {
+    const nameColor = report.source === "error" ? theme.textMuted : theme.accent;
+    const segments: Segment[] = [{ text: report.displayName, fg: nameColor, bold: true }];
+    if (report.stale) segments.push({ text: " (stale)", fg: theme.textMuted });
+    if (report.source === "local-estimate") {
+      segments.push({ text: " (est)", fg: theme.textMuted });
+    }
+    lines.push({ segments });
+
+    if (report.source === "error") {
+      lines.push({
+        segments: [{ text: clip(report.error ?? "unknown error"), fg: theme.error }],
+      });
+      continue;
+    }
+
+    const windows = report.windows.toSorted((a, b) => windowRank(a.kind) - windowRank(b.kind));
+    for (const w of windows) {
+      const tone = toneFor(w.usedPercent, w.status);
+      const row: Segment[] = [
+        { text: alignLabel(windowLabel(w.kind, w.label)), fg: theme.textMuted },
+        { text: bar(w.usedPercent, barWidth), fg: theme[tone] },
+        { text: " ", fg: theme.text },
+        { text: percentText(w), fg: theme.text },
+      ];
+      const reset = countdown(w.resetsAt, now);
+      if (reset !== null) {
+        row.push({ text: ` resets in ${reset}`, fg: theme.textMuted });
+      }
+      lines.push({ segments: row });
+    }
+
+    for (const [key, value] of Object.entries(report.extras)) {
+      lines.push({
+        segments: [{ text: clip(`${key}: ${value}`, EXTRAS_MAX_LENGTH), fg: theme.textMuted }],
+      });
+    }
+  }
+
+  return lines;
+}

package/src/tui.tsx

@@ -7,114 +7,19 @@ import type {
 } from "@opencode-ai/plugin/tui";
 import { For, createSignal } from "solid-js";
 import { DEFAULT_OPTIONS, collectReports } from "./report";
-import { bar, coerceTuiOptions, countdown, percentText, toneFor, windowLabel } from "./tui-format";
-import type { ProviderReport, WindowKind } from "./types";
-
-type Theme = TuiPluginApi["theme"]["current"];
-type ThemeColor = Theme["text"];
-
-interface Segment {
-  text: string;
-  fg: ThemeColor;
-  bold?: boolean;
-}
-
-interface Line {
-  segments: Segment[];
-}
-
-const NAMED_WIDTH = 14;
-const EXTRAS_MAX_LENGTH = 80;
-
-/** Order windows for display; unknown kinds sort last. */
-const WINDOW_ORDER: Record<WindowKind, number> = {
-  "5h": 0,
-  weekly: 1,
-  monthly: 2,
-  daily: 3,
-  other: 4,
-};
-
-function windowRank(kind: WindowKind): number {
-  return WINDOW_ORDER[kind] ?? WINDOW_ORDER.other;
-}
-
-/** Collapses whitespace and truncates to a single-line label. */
-function clip(value: string, max = 60): string {
-  const single = value.replace(/\s+/g, " ").trim();
-  if (single.length <= max) return single;
-  return single.slice(0, Math.max(0, max - 1)) + "…";
-}
-
-/** Pads a label to a fixed width, truncating (with a trailing space) when long. */
-function alignLabel(label: string): string {
-  const text = label.length > NAMED_WIDTH ? label.slice(0, NAMED_WIDTH - 1) + " " : label;
-  return text.padEnd(NAMED_WIDTH);
-}
-
-/** Flattens the current signal state into plain, pre-colored text lines. */
-function buildLines(
-  theme: Theme,
-  reports: ProviderReport[],
-  busy: boolean,
-  error: string | null,
-  now: Date,
-  barWidth: number,
-): Line[] {
-  const lines: Line[] = [];
-
-  if (error !== null) {
-    lines.push({
-      segments: [{ text: `api error: ${clip(error)}`, fg: theme.error }],
-    });
-  }
-
-  if (reports.length === 0 && busy) {
-    lines.push({
-      segments: [{ text: "loading…", fg: theme.textMuted }],
-    });
-  }
-
-  for (const report of reports) {
-    const nameColor = report.source === "error" ? theme.textMuted : theme.accent;
-    const segments: Segment[] = [{ text: report.displayName, fg: nameColor, bold: true }];
-    if (report.stale) segments.push({ text: " (stale)", fg: theme.textMuted });
-    if (report.source === "local-estimate") {
-      segments.push({ text: " (est)", fg: theme.textMuted });
-    }
-    lines.push({ segments });
-
-    if (report.source === "error") {
-      lines.push({
-        segments: [{ text: clip(report.error ?? "unknown error"), fg: theme.error }],
-      });
-      continue;
-    }
-
-    const windows = report.windows.toSorted((a, b) => windowRank(a.kind) - windowRank(b.kind));
-    for (const w of windows) {
-      const tone = toneFor(w.usedPercent, w.status);
-      const row: Segment[] = [
-        { text: alignLabel(windowLabel(w.kind, w.label)), fg: theme.textMuted },
-        { text: bar(w.usedPercent, barWidth), fg: theme[tone] },
-        { text: " ", fg: theme.text },
-        { text: percentText(w), fg: theme.text },
-      ];
-      const reset = countdown(w.resetsAt, now);
-      if (reset !== null) {
-        row.push({ text: ` resets in ${reset}`, fg: theme.textMuted });
-      }
-      lines.push({ segments: row });
-    }
-
-    for (const [key, value] of Object.entries(report.extras)) {
-      lines.push({
-        segments: [{ text: clip(`${key}: ${value}`, EXTRAS_MAX_LENGTH), fg: theme.textMuted }],
-      });
-    }
-  }
-
-  return lines;
+import { coerceTuiOptions } 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";
+
+/** Resolves the session the `/usage` dialog should describe, if any. */
+function activeSessionID(api: TuiPluginApi): string | null {
+  const route = api.route.current;
+  if (route.name !== "session") return null;
+  const id: unknown = route.params?.sessionID;
+  return typeof id === "string" ? id : null;
 }
 
 export const tui: TuiPlugin = async (api, rawOptions) => {
@@ -124,11 +29,13 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
   const [inFlight, setInFlight] = createSignal(0);
   const [error, setError] = createSignal<string | null>(null);
   const [tick, setTick] = createSignal(Date.now());
+  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);
@@ -153,11 +60,22 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
     }
   };
 
-  // Single timer: refreshes data and advances countdowns.
+  // Single timer: refreshes data, advances countdowns, reloads the capture.
+  const refreshCapture = async (): Promise<void> => {
+    if (disposed) return;
+    const sessionID = activeSessionID(api);
+    if (sessionID === null) {
+      setCapture(null);
+      return;
+    }
+    setCapture(await readCapture(sessionID));
+  };
+
   const intervalMs = Math.max(1, Math.floor(options.refreshIntervalSeconds)) * 1000;
   const timer = setInterval(() => {
     setTick(Date.now());
     void load();
+    void refreshCapture();
   }, intervalMs);
 
   api.lifecycle.onDispose(() => {
@@ -168,9 +86,35 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
   const offIdle = api.event.on("session.idle", () => {
     setTick(Date.now());
     void load();
+    void refreshCapture();
   });
   api.lifecycle.onDispose(offIdle);
 
+  const openDialog = (): void => {
+    const sessionID = activeSessionID(api);
+    void refreshCapture().finally(() => {
+      if (disposed) return;
+      setScope(0);
+      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}
+          barWidth={options.barWidth}
+        />
+      ));
+      // Must follow replace(): the stack resets the size to "medium".
+      api.ui.dialog.setSize("xlarge");
+    });
+  };
+
   api.lifecycle.onDispose(
     api.keymap.registerLayer({
       commands: [
@@ -183,11 +127,47 @@ export const tui: TuiPlugin = async (api, rawOptions) => {
             void load(true);
           },
         },
+        {
+          name: "usage.open",
+          title: "Usage: open report",
+          description: "Context usage and provider quota windows",
+          category: "Plugin",
+          namespace: "palette",
+          slashName: "usage",
+          run: openDialog,
+        },
       ],
       bindings: [{ key: "ctrl+shift+u", cmd: "usage.refresh", desc: "Refresh usage panel" }],
     }),
   );
 
+  // Scoped to the dialog's "modal" mode so these keys only fire while it is open.
+  api.lifecycle.onDispose(
+    api.keymap.registerLayer({
+      mode: "modal",
+      commands: [
+        { name: "usage.dialog.refresh", run: () => void load(true) },
+        {
+          name: "usage.dialog.scope",
+          run: () => {
+            setScope((n) => (n + 1) % Math.max(1, reports().length + 1));
+          },
+        },
+        {
+          name: "usage.dialog.json",
+          run: () => {
+            setShowJson((v) => !v);
+          },
+        },
+      ],
+      bindings: [
+        { key: "r", cmd: "usage.dialog.refresh", desc: "Refresh usage report" },
+        { key: "tab", cmd: "usage.dialog.scope", desc: "Cycle provider scope" },
+        { key: "j", cmd: "usage.dialog.json", desc: "Toggle raw JSON" },
+      ],
+    }),
+  );
+
   const slot: TuiSlotPlugin = {
     order: 150,
     slots: {