opencode-usage-report 0.3.0 → 0.4.1

package/src/context/types.ts

@@ -0,0 +1,50 @@
+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
+}
+
+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,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

@@ -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/normalize.ts

@@ -1,5 +1,3 @@
-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 {
   if (typeof v === "number") {
@@ -45,31 +43,23 @@ export function pick(obj: unknown, ...keys: string[]): unknown {
   return undefined;
 }
 
-/** Converts a 0-1 ratio into a 0-100 percent, clamped to [0,100] and rounded to 1 decimal. */
-export function ratioToPercent(ratio: number): number {
-  const rounded = Math.round(ratio * 1000) / 10;
-  return Math.min(100, Math.max(0, rounded));
+/** Finite number or null; numeric strings are not coerced. */
+export function finiteOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** Finite number >= 0 or null. */
+export function nonNegative(value: unknown): number | null {
+  const n = finiteOrNull(value);
+  return n !== null && n >= 0 ? n : null;
+}
+
+/** Plain-object guard: null and arrays are not records. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Builds a window from tolerant count fields, deriving usedPercent only when used and a positive limit are known. */
-export function windowFromCounts(
-  kind: WindowKind,
-  label: string,
-  detail: { limit?: unknown; used?: unknown; remaining?: unknown; reset?: unknown },
-): UsageWindow {
-  const used = toNumber(detail.used);
-  const limit = toNumber(detail.limit);
-  const remaining = toNumber(detail.remaining);
-  const usedPercent =
-    used !== null && limit !== null && limit > 0 ? Math.round((used / limit) * 100) : null;
-  return {
-    kind,
-    label,
-    usedPercent,
-    used,
-    limit,
-    remaining,
-    resetsAt: toISODate(detail.reset),
-    status: "ok",
-  };
+/** Tolerant string coercion; null and undefined become "". */
+export function safeString(value: unknown): string {
+  return String(value ?? "");
 }

package/src/providers/chatgpt.ts

@@ -9,17 +9,10 @@ import type {
 import { AdapterError } from "../types";
 import { toISODate, toNumber } from "../normalize";
 import { redact } from "../auth";
+import { asRecord, handleError, readBody, request } from "./http";
 
-const VERSION = "0.3.0";
-const USER_AGENT = "opencode-usage-report/" + VERSION;
 const ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
 
-function asRecord(v: unknown): Record<string, unknown> | null {
-  return v !== null && typeof v === "object" && !Array.isArray(v)
-    ? (v as Record<string, unknown>)
-    : null;
-}
-
 /** "foo_bar-baz" -> "Foo Bar Baz". */
 function titleCase(v: string): string {
   return v
@@ -54,74 +47,6 @@ function windowKind(seconds: number | null): { kind: WindowKind; label: string }
   return { kind: "other", label: "Other" };
 }
 
-/** Reads the body once as text and best-effort parses JSON, so error and success paths share it. */
-async function readBody(res: Response): Promise<{ text: string; json: unknown }> {
-  const text = await res.text().catch(() => "");
-  let json: unknown = null;
-  try {
-    json = JSON.parse(text);
-  } catch {
-    json = null;
-  }
-  return { text, json };
-}
-
-async function attempt(cred: Credential, accountId: string, opts: FetchOptions): Promise<Response> {
-  return fetch(ENDPOINT, {
-    method: "GET",
-    headers: {
-      Authorization: "Bearer " + cred.key,
-      "ChatGPT-Account-Id": accountId,
-      Accept: "application/json",
-      "User-Agent": USER_AGENT,
-    },
-    signal: AbortSignal.timeout(opts.timeoutMs),
-  });
-}
-
-/** Exactly one retry on a network throw or 5xx; 4xx is returned immediately (never retried). */
-async function request(cred: Credential, accountId: string, opts: FetchOptions): Promise<Response> {
-  try {
-    const first = await attempt(cred, accountId, opts);
-    if (first.status < 500) return first;
-  } catch {
-    // fall through to the single retry
-  }
-
-  try {
-    return await attempt(cred, accountId, opts);
-  } catch (err) {
-    throw new AdapterError(
-      "network",
-      redact(
-        `ChatGPT request failed: ${err instanceof Error ? err.message : String(err)}`,
-        cred.key,
-      ),
-    );
-  }
-}
-
-async function handleError(res: Response, cred: Credential): Promise<never> {
-  const { text } = await readBody(res);
-
-  if (res.status === 401) {
-    throw new AdapterError("auth", redact("invalid ChatGPT login", cred.key));
-  }
-  if (res.status === 403) {
-    throw new AdapterError("no-plan", redact("ChatGPT is not enabled for this account", cred.key));
-  }
-  if (res.status === 429) {
-    throw new AdapterError("rate-limited", redact("ChatGPT rate limit reached", cred.key));
-  }
-  if (res.status >= 500) {
-    throw new AdapterError("network", redact(`ChatGPT server error ${res.status}`, cred.key));
-  }
-  throw new AdapterError(
-    "bad-response",
-    redact(`ChatGPT unexpected status ${res.status}: ${text.slice(0, 200)}`, cred.key),
-  );
-}
-
 export const chatgptAdapter: ProviderAdapter = {
   id: "openai",
   displayName: "ChatGPT",
@@ -130,8 +55,29 @@ export const chatgptAdapter: ProviderAdapter = {
       throw new AdapterError("auth", "ChatGPT account id missing (re-run: opencode auth login)");
     }
 
-    const res = await request(cred, cred.accountId, opts);
-    if (!res.ok) return handleError(res, cred);
+    const res = await request(cred, opts, {
+      endpoint: ENDPOINT,
+      label: "ChatGPT request failed",
+      headers: { "ChatGPT-Account-Id": cred.accountId },
+    });
+    if (!res.ok) {
+      return handleError(res, cred, (status, { text }) => {
+        if (status === 401) return { kind: "auth", message: "invalid ChatGPT login" };
+        if (status === 403) {
+          return { kind: "no-plan", message: "ChatGPT is not enabled for this account" };
+        }
+        if (status === 429) {
+          return { kind: "rate-limited", message: "ChatGPT rate limit reached" };
+        }
+        if (status >= 500) {
+          return { kind: "network", message: `ChatGPT server error ${status}` };
+        }
+        return {
+          kind: "bad-response",
+          message: `ChatGPT unexpected status ${status}: ${text.slice(0, 200)}`,
+        };
+      });
+    }
 
     const { json } = await readBody(res);
     const body = asRecord(json);

package/src/providers/copilot.ts

@@ -8,9 +8,8 @@ import type {
 import { AdapterError } from "../types";
 import { toISODate, toNumber } from "../normalize";
 import { redact } from "../auth";
+import { asRecord, handleError, readBody, request } from "./http";
 
-const VERSION = "0.3.0";
-const USER_AGENT = "opencode-usage-report/" + VERSION;
 const ENDPOINT = "https://api.github.com/copilot_internal/user";
 
 /** Snapshot keys in display order, paired with their human-readable labels. */
@@ -20,12 +19,6 @@ const SNAPSHOTS: Array<{ key: string; label: string }> = [
   { key: "premium_interactions", label: "Premium interactions" },
 ];
 
-function asRecord(v: unknown): Record<string, unknown> | null {
-  return v !== null && typeof v === "object" && !Array.isArray(v)
-    ? (v as Record<string, unknown>)
-    : null;
-}
-
 /** "foo_bar-baz" -> "Foo Bar Baz". */
 function titleCase(v: string): string {
   return v
@@ -60,88 +53,37 @@ export function copilotTier(sku: unknown, plan: unknown): string {
   return "Copilot";
 }
 
-/** Reads the body once as text and best-effort parses JSON, so error and success paths share it. */
-async function readBody(res: Response): Promise<{ text: string; json: unknown }> {
-  const text = await res.text().catch(() => "");
-  let json: unknown = null;
-  try {
-    json = JSON.parse(text);
-  } catch {
-    json = null;
-  }
-  return { text, json };
-}
-
-async function attempt(cred: Credential, opts: FetchOptions): Promise<Response> {
-  return fetch(ENDPOINT, {
-    method: "GET",
-    headers: {
-      Authorization: "Bearer " + cred.key,
-      Accept: "application/json",
-      "User-Agent": USER_AGENT,
-    },
-    signal: AbortSignal.timeout(opts.timeoutMs),
-  });
-}
-
-/** Exactly one retry on a network throw or 5xx; 4xx is returned immediately (never retried). */
-async function request(cred: Credential, opts: FetchOptions): Promise<Response> {
-  try {
-    const first = await attempt(cred, opts);
-    if (first.status < 500) return first;
-  } catch {
-    // fall through to the single retry
-  }
-
-  try {
-    return await attempt(cred, opts);
-  } catch (err) {
-    throw new AdapterError(
-      "network",
-      redact(
-        `GitHub Copilot request failed: ${err instanceof Error ? err.message : String(err)}`,
-        cred.key,
-      ),
-    );
-  }
-}
-
-async function handleError(res: Response, cred: Credential): Promise<never> {
-  const { text } = await readBody(res);
-
-  if (res.status === 401 || res.status === 404) {
-    throw new AdapterError(
-      "auth",
-      redact("GitHub Copilot login invalid or not available for this account", cred.key),
-    );
-  }
-  if (res.status === 403) {
-    throw new AdapterError(
-      "no-plan",
-      redact("GitHub Copilot is not enabled for this account", cred.key),
-    );
-  }
-  if (res.status === 429) {
-    throw new AdapterError("rate-limited", redact("GitHub Copilot rate limit reached", cred.key));
-  }
-  if (res.status >= 500) {
-    throw new AdapterError(
-      "network",
-      redact(`GitHub Copilot server error ${res.status}`, cred.key),
-    );
-  }
-  throw new AdapterError(
-    "bad-response",
-    redact(`GitHub Copilot unexpected status ${res.status}: ${text.slice(0, 200)}`, cred.key),
-  );
-}
-
 export const copilotAdapter: ProviderAdapter = {
   id: "github-copilot",
   displayName: "GitHub Copilot",
   async fetch(cred: Credential, opts: FetchOptions): Promise<AdapterResult> {
-    const res = await request(cred, opts);
-    if (!res.ok) return handleError(res, cred);
+    const res = await request(cred, opts, {
+      endpoint: ENDPOINT,
+      label: "GitHub Copilot request failed",
+    });
+    if (!res.ok) {
+      return handleError(res, cred, (status, { text }) => {
+        if (status === 401 || status === 404) {
+          return {
+            kind: "auth",
+            message: "GitHub Copilot login invalid or not available for this account",
+          };
+        }
+        if (status === 403) {
+          return { kind: "no-plan", message: "GitHub Copilot is not enabled for this account" };
+        }
+        if (status === 429) {
+          return { kind: "rate-limited", message: "GitHub Copilot rate limit reached" };
+        }
+        if (status >= 500) {
+          return { kind: "network", message: `GitHub Copilot server error ${status}` };
+        }
+        return {
+          kind: "bad-response",
+          message: `GitHub Copilot unexpected status ${status}: ${text.slice(0, 200)}`,
+        };
+      });
+    }
 
     const { json } = await readBody(res);
     const body = asRecord(json);

package/src/providers/http.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared HTTP plumbing for provider adapters. Every adapter performs the same
+ * authenticated GET with one retry, so the fetch, body-reading and error-mapping
+ * helpers live here instead of being copy-pasted per provider.
+ */
+import type { AdapterErrorKind, Credential, FetchOptions } from "../types";
+import { AdapterError } from "../types";
+import { redact } from "../auth";
+
+/** Sent as the User-Agent on every provider request; keep in sync with package.json. */
+export const USER_AGENT = "opencode-usage-report/0.4.1";
+
+export function asRecord(v: unknown): Record<string, unknown> | null {
+  return v !== null && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : null;
+}
+
+export interface Body {
+  text: string;
+  json: unknown;
+}
+
+/** Reads the body once as text and best-effort parses JSON, so error and success paths share it. */
+export async function readBody(res: Response): Promise<Body> {
+  const text = await res.text().catch(() => "");
+  let json: unknown = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    json = null;
+  }
+  return { text, json };
+}
+
+export interface RequestSpec {
+  endpoint: string;
+  /** Prefix of the thrown network error, e.g. "Kimi API network error". */
+  label: string;
+  headers?: Record<string, string>;
+}
+
+function attempt(cred: Credential, opts: FetchOptions, spec: RequestSpec): Promise<Response> {
+  return fetch(spec.endpoint, {
+    method: "GET",
+    headers: {
+      Authorization: "Bearer " + cred.key,
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+      ...spec.headers,
+    },
+    signal: AbortSignal.timeout(opts.timeoutMs),
+  });
+}
+
+/** Exactly one retry on a network throw or 5xx; 4xx is returned immediately (never retried). */
+export async function request(
+  cred: Credential,
+  opts: FetchOptions,
+  spec: RequestSpec,
+): Promise<Response> {
+  let lastError: unknown = null;
+  for (let i = 0; i < 2; i++) {
+    try {
+      const res = await attempt(cred, opts, spec);
+      if (res.status >= 500 && i === 0) continue;
+      return res;
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  const detail = lastError instanceof Error ? lastError.message : String(lastError);
+  throw new AdapterError("network", redact(`${spec.label}: ${detail}`, cred.key));
+}
+
+export interface ErrorResolution {
+  kind: AdapterErrorKind;
+  message: string;
+}
+
+/** Reads the error body, asks the adapter to map it, and throws the resulting AdapterError. */
+export async function handleError(
+  res: Response,
+  cred: Credential,
+  resolve: (status: number, body: Body) => ErrorResolution,
+): Promise<never> {
+  const body = await readBody(res);
+  const { kind, message } = resolve(res.status, body);
+  throw new AdapterError(kind, redact(message, cred.key));
+}

package/src/providers/kimi.ts

@@ -4,12 +4,12 @@ import type {
   FetchOptions,
   ProviderAdapter,
   UsageWindow,
+  WindowKind,
 } from "../types";
 import { AdapterError } from "../types";
-import { pick, ratioToPercent, toISODate, toNumber, windowFromCounts } from "../normalize";
+import { pick, toISODate, toNumber } from "../normalize";
 import { redact } from "../auth";
-
-const VERSION = "0.3.0";
+import { handleError, readBody, request } from "./http";
 
 /**
  * Kimi Code is split by region in opencode/models.dev: the global plan lives on
@@ -23,39 +23,33 @@ export interface KimiAdapterConfig {
   baseUrl: string;
 }
 
-function request(cred: Credential, opts: FetchOptions, endpoint: string): Promise<Response> {
-  return fetch(endpoint, {
-    method: "GET",
-    headers: {
-      Authorization: "Bearer " + cred.key,
-      Accept: "application/json",
-      "User-Agent": "opencode-usage-report/" + VERSION,
-    },
-    signal: AbortSignal.timeout(opts.timeoutMs),
-  });
+/** Converts a 0-1 ratio into a 0-100 percent, clamped to [0,100] and rounded to 1 decimal. */
+function ratioToPercent(ratio: number): number {
+  const rounded = Math.round(ratio * 1000) / 10;
+  return Math.min(100, Math.max(0, rounded));
 }
 
-/** One retry on network throw or 5xx; 4xx and 2xx return immediately. */
-async function fetchWithRetry(
-  cred: Credential,
-  opts: FetchOptions,
-  endpoint: string,
-): Promise<Response> {
-  let lastError: unknown = null;
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try {
-      const res = await request(cred, opts, endpoint);
-      if (res.status >= 500) {
-        lastError = new Error(`HTTP ${res.status}`);
-        continue;
-      }
-      return res;
-    } catch (err) {
-      lastError = err;
-    }
-  }
-  const detail = lastError instanceof Error ? lastError.message : String(lastError);
-  throw new AdapterError("network", redact(`Kimi API network error: ${detail}`, cred.key));
+/** Builds a window from tolerant count fields, deriving usedPercent only when used and a positive limit are known. */
+function windowFromCounts(
+  kind: WindowKind,
+  label: string,
+  detail: { limit?: unknown; used?: unknown; remaining?: unknown; reset?: unknown },
+): UsageWindow {
+  const used = toNumber(detail.used);
+  const limit = toNumber(detail.limit);
+  const remaining = toNumber(detail.remaining);
+  const usedPercent =
+    used !== null && limit !== null && limit > 0 ? Math.round((used / limit) * 100) : null;
+  return {
+    kind,
+    label,
+    usedPercent,
+    used,
+    limit,
+    remaining,
+    resetsAt: toISODate(detail.reset),
+    status: "ok",
+  };
 }
 
 function findLimitDetail(limits: unknown, durationMinutes: number): unknown {
@@ -174,39 +168,33 @@ export function createKimiAdapter(config: KimiAdapterConfig): ProviderAdapter {
     id: config.id,
     displayName: config.displayName,
     async fetch(cred: Credential, opts: FetchOptions): Promise<AdapterResult> {
-      const res = await fetchWithRetry(cred, opts, endpoint);
-
-      if (res.status === 401) {
-        throw new AdapterError("auth", redact("invalid Kimi API key", cred.key));
-      }
-      if (res.status === 429) {
-        throw new AdapterError("rate-limited", redact("Kimi API rate limit exceeded", cred.key));
-      }
-      if (res.status < 200 || res.status >= 300) {
-        throw new AdapterError(
-          "bad-response",
-          redact(`Kimi API returned HTTP ${res.status}`, cred.key),
-        );
-      }
-
-      let body: unknown;
-      try {
-        body = await res.json();
-      } catch {
-        throw new AdapterError(
-          "bad-response",
-          redact("Kimi API returned a non-JSON response", cred.key),
-        );
+      const res = await request(cred, opts, {
+        endpoint,
+        label: "Kimi API network error",
+      });
+
+      if (!res.ok) {
+        return handleError(res, cred, (status) => {
+          if (status === 401) return { kind: "auth", message: "invalid Kimi API key" };
+          if (status === 429) {
+            return { kind: "rate-limited", message: "Kimi API rate limit exceeded" };
+          }
+          if (status >= 500) {
+            return { kind: "network", message: `Kimi API network error: HTTP ${status}` };
+          }
+          return { kind: "bad-response", message: `Kimi API returned HTTP ${status}` };
+        });
       }
 
-      if (body === null || typeof body !== "object" || Array.isArray(body)) {
+      const { json } = await readBody(res);
+      if (json === null || typeof json !== "object" || Array.isArray(json)) {
         throw new AdapterError(
           "bad-response",
           redact("Kimi API returned an unexpected response shape", cred.key),
         );
       }
 
-      return parse(body as Record<string, unknown>, cred);
+      return parse(json as Record<string, unknown>, cred);
     },
   };
 }