pi-opencode-go-provider 1.0.23 → 1.0.25

package/README.md

@@ -21,6 +21,7 @@ _Go-optimized endpoints for lower latency — 14+ models for [pi](https://github
 - **Cost Tracking** with per-model pricing for budget management
 - **Reasoning Models** with thinking level maps for proper effort control
 - **Prompt-cache session affinity** — sends `x-opencode-session` and `x-opencode-client` so OpenCode Go can pin a session to the same cache node
+- **Usage widget** — shows how much of the OpenCode Go 5h / 7d / 30d budgets you have spent, below the editor (footer status line outside the TUI)
 
 ## Installation
 
@@ -110,6 +111,54 @@ Then select "opencode-go" as the provider and choose from the available models.
 
 The default model for this provider is `kimi-k2.6` (matching pi core's built-in default); use `/model` to pick another.
 
+## Usage Widget
+
+OpenCode Go meters the plan with three dollar budgets — a rolling 5-hour window,
+a weekly window and a monthly window. The extension polls
+`GET https://opencode.ai/zen/go/v1/usage` with your API key and shows how much of
+each budget is **left**, below the editor. When no terminal UI is attached (print
+or JSON mode) the same line goes to the footer status bar instead.
+
+```
+Usage: 5h: 63% · 7d: 41% · 30d: 12% · 5h ↺ 2h14m · 7d ↺ 3d20h · 30d ↺ 20d0h
+```
+
+The line matches the pi-better-openai usage line: the remaining percentages come
+first, then a countdown per window. Countdowns only — three windows with three
+wall-clock reset times run past the terminal width, and `/opencode-go-usage`
+lists the exact local reset time for each. Colours track what is left — green,
+amber at 30% or less, red at 10% or less or when a window reports
+`rate-limited` — and the widget only appears while an `opencode-go` model is
+selected. The Go API publishes no banked reset credits,
+so that trailing segment appears only if a response ever carries a
+`bankedResets` count.
+
+```
+/opencode-go-usage            # refresh and show the full breakdown
+/opencode-go-usage refresh    # same, but always re-reads the API
+/opencode-go-usage off        # hide the widget (persisted)
+/opencode-go-usage on         # show it again
+/opencode-go-usage debug      # config, last fetch/error, endpoint
+```
+
+Polling runs every 60 seconds, plus after every turn and whenever the selected
+model changes. Settings are read from `~/.pi/agent/opencode-go-provider.json`:
+
+```json
+{
+  "usage": {
+    "enabled": true,
+    "refreshIntervalMs": 60000,
+    "showOnlyOnProvider": true,
+    "showResetTimes": true,
+    "placement": "belowEditor"
+  }
+}
+```
+
+`placement` accepts `belowEditor` (default) or `aboveEditor`. Every key is
+optional; `/opencode-go-usage on|off` writes only `enabled`.
+
 ## Authentication
 
 The opencode-go API key can be configured in multiple ways. Credentials are resolved in this order:
@@ -126,7 +175,9 @@ The opencode-go API key can be configured in multiple ways. Credentials are reso
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `OPENCODE_API_KEY` | No | Your opencode.ai API key (fallback if not in auth.json) |
+| `OPENCODE_API_KEY` | No | Your opencode.ai API key (fallback if not in auth.json). Also used for usage requests |
+| `OPENCODE_GO_USAGE` | No | Set to `off`/`false`/`0` to disable the usage widget without editing the config file |
+| `OPENCODE_GO_USAGE_INTERVAL_MS` | No | Override the usage poll interval (clamped to 15s–10m) |
 
 ## Configuration
 

package/config.ts

@@ -0,0 +1,127 @@
+/**
+ * Persistent settings for the opencode-go provider extension.
+ *
+ * The file is deliberately tiny and optional: every field falls back to
+ * DEFAULT_USAGE_CONFIG, then an environment override wins. Written only by
+ * `/opencode-go-usage on|off` so the widget choice survives a restart.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const PROVIDER_ID = "opencode-go";
+export const CONFIG_BASENAME = "opencode-go-provider.json";
+/** Shared key so the widget and the status fallback never collide with other extensions. */
+export const USAGE_WIDGET_KEY = "opencode-go-usage";
+
+export type UsagePlacement = "aboveEditor" | "belowEditor";
+
+export interface UsageConfig {
+  /** Show the usage widget/status at all. */
+  enabled: boolean;
+  /** Poll interval while a session is open. */
+  refreshIntervalMs: number;
+  /** Only display usage while the selected model belongs to opencode-go. */
+  showOnlyOnProvider: boolean;
+  /** Include reset countdowns in the widget line. */
+  showResetTimes: boolean;
+  placement: UsagePlacement;
+}
+
+export const DEFAULT_USAGE_CONFIG: UsageConfig = {
+  enabled: true,
+  refreshIntervalMs: 60_000,
+  showOnlyOnProvider: true,
+  showResetTimes: true,
+  placement: "belowEditor",
+};
+
+export const MIN_USAGE_REFRESH_MS = 15_000;
+export const MAX_USAGE_REFRESH_MS = 10 * 60_000;
+
+const USAGE_PLACEMENTS: UsagePlacement[] = ["aboveEditor", "belowEditor"];
+const DISABLED_VALUES = new Set(["0", "false", "off", "no", "disable", "disabled"]);
+const ENABLED_VALUES = new Set(["1", "true", "on", "yes", "enable", "enabled"]);
+
+export function configPath(): string {
+  return path.join(getAgentDir(), CONFIG_BASENAME);
+}
+
+export function clampRefreshInterval(milliseconds: number): number {
+  if (!Number.isFinite(milliseconds)) return DEFAULT_USAGE_CONFIG.refreshIntervalMs;
+  return Math.max(MIN_USAGE_REFRESH_MS, Math.min(MAX_USAGE_REFRESH_MS, Math.round(milliseconds)));
+}
+
+function parseFlag(value: string | undefined): boolean | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) return undefined;
+  if (DISABLED_VALUES.has(normalized)) return false;
+  if (ENABLED_VALUES.has(normalized)) return true;
+  return undefined;
+}
+
+function readFileUsage(): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(configPath(), "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const usage = (parsed as Record<string, unknown>).usage;
+      if (usage && typeof usage === "object" && !Array.isArray(usage)) {
+        return usage as Record<string, unknown>;
+      }
+    }
+  } catch {
+    // Missing or unreadable config is the normal first-run state.
+  }
+  return {};
+}
+
+/**
+ * Resolve the effective usage config: defaults <- config file <- environment.
+ * Never throws; a broken config file degrades to defaults.
+ */
+export function readUsageConfig(env: NodeJS.ProcessEnv = process.env): UsageConfig {
+  const config = { ...DEFAULT_USAGE_CONFIG };
+  const file = readFileUsage();
+
+  if (typeof file.enabled === "boolean") config.enabled = file.enabled;
+  if (typeof file.showOnlyOnProvider === "boolean") config.showOnlyOnProvider = file.showOnlyOnProvider;
+  if (typeof file.showResetTimes === "boolean") config.showResetTimes = file.showResetTimes;
+  if (typeof file.refreshIntervalMs === "number") {
+    config.refreshIntervalMs = clampRefreshInterval(file.refreshIntervalMs);
+  }
+  if (USAGE_PLACEMENTS.includes(file.placement as UsagePlacement)) {
+    config.placement = file.placement as UsagePlacement;
+  }
+
+  const envEnabled = parseFlag(env.OPENCODE_GO_USAGE);
+  if (envEnabled !== undefined) config.enabled = envEnabled;
+  const envInterval = env.OPENCODE_GO_USAGE_INTERVAL_MS
+    ? Number(env.OPENCODE_GO_USAGE_INTERVAL_MS)
+    : undefined;
+  if (envInterval !== undefined) config.refreshIntervalMs = clampRefreshInterval(envInterval);
+
+  return config;
+}
+
+/** Merge a patch into the config file, preserving unrelated keys. */
+export function writeUsageConfig(patch: Partial<UsageConfig>): boolean {
+  try {
+    const file = configPath();
+    let document: Record<string, unknown> = {};
+    try {
+      const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        document = parsed as Record<string, unknown>;
+      }
+    } catch {
+      document = {};
+    }
+    document.usage = { ...readFileUsage(), ...patch };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(document, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/deprecated-models.json

@@ -27,5 +27,34 @@
     "contextWindow": 500000,
     "maxTokens": 128000,
     "deprecatedAt": "2026-09-10T06:11:15.915Z"
+  },
+  "deepseek-flash": {
+    "id": "deepseek-flash",
+    "name": "DeepSeek V4.1 Flash",
+    "api": "openai-completions",
+    "baseUrl": "https://opencode.ai/zen/go/v1",
+    "reasoning": true,
+    "thinkingLevelMap": {
+      "off": null,
+      "minimal": null,
+      "low": "low",
+      "medium": null,
+      "high": "high",
+      "xhigh": null,
+      "max": "max"
+    },
+    "input": [
+      "text",
+      "image"
+    ],
+    "cost": {
+      "input": 0.15,
+      "output": 0.6,
+      "cacheRead": 0.003,
+      "cacheWrite": 0
+    },
+    "contextWindow": 1000000,
+    "maxTokens": 384000,
+    "deprecatedAt": "2026-09-11T02:00:25.277Z"
   }
 }

package/format.ts

@@ -0,0 +1,84 @@
+/**
+ * Terminal text helpers for the usage widget.
+ *
+ * Kept dependency-free (no @earendil-works/pi-tui import) so the usage logic
+ * stays unit-testable with a bare Node test run and the extension keeps its
+ * single devDependency.
+ */
+
+const ANSI_PATTERN = "\u001B\\[[0-?]*[ -/]*[@-~]";
+const ANSI_SPLIT_REGEXP = new RegExp("(" + ANSI_PATTERN + ")");
+const ANSI_TEST_REGEXP = new RegExp(ANSI_PATTERN);
+
+export function stripAnsi(value: string): string {
+  return value.replace(new RegExp(ANSI_PATTERN, "g"), "");
+}
+
+/** Approximate terminal cell width of a single code point. */
+function charWidth(char: string): number {
+  const code = char.codePointAt(0) ?? 0;
+  if (code === 0) return 0;
+  // Combining marks and zero-width joiners occupy no cells.
+  if (code >= 0x0300 && code <= 0x036f) return 0;
+  if (code === 0x200d || code === 0xfe0f) return 0;
+  if (
+    (code >= 0x1100 && code <= 0x115f) ||
+    (code >= 0x2e80 && code <= 0xa4cf) ||
+    (code >= 0xac00 && code <= 0xd7a3) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xfe30 && code <= 0xfe6f) ||
+    (code >= 0xff00 && code <= 0xff60) ||
+    (code >= 0xffe0 && code <= 0xffe6) ||
+    (code >= 0x1f300 && code <= 0x1faff) ||
+    (code >= 0x20000 && code <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/** Visible width of a string, ignoring ANSI escape sequences. */
+export function visibleWidth(value: string): number {
+  let width = 0;
+  for (const char of stripAnsi(value)) width += charWidth(char);
+  return width;
+}
+
+/**
+ * Slice a possibly-colored string to a terminal width, appending an ellipsis.
+ * ANSI sequences before the cut are preserved and a reset is emitted so the
+ * ellipsis (and anything after it) keeps the caller's own styling.
+ */
+export function truncateToWidth(value: string, width: number, ellipsis = "\u2026"): string {
+  if (width <= 0) return "";
+  if (visibleWidth(value) <= width) return value;
+  const budget = Math.max(0, width - visibleWidth(ellipsis));
+  const tokens = value.split(ANSI_SPLIT_REGEXP);
+  let result = "";
+  let used = 0;
+  let truncated = false;
+  for (const token of tokens) {
+    if (token === "") continue;
+    if (ANSI_TEST_REGEXP.test(token)) {
+      result += token;
+      continue;
+    }
+    for (const char of token) {
+      const cellWidth = charWidth(char);
+      if (used + cellWidth > budget) {
+        truncated = true;
+        break;
+      }
+      result += char;
+      used += cellWidth;
+    }
+    if (truncated) break;
+  }
+  const reset = ANSI_TEST_REGEXP.test(value) ? "\u001B[0m" : "";
+  return result + reset + ellipsis;
+}
+
+/** Collapse whitespace so a multi-segment line survives a one-line status bar. */
+export function sanitizeStatusText(text: string): string {
+  return text.replace(/[ \r\n\t]+/g, " ").trim();
+}

package/index.ts

@@ -22,7 +22,17 @@
  * Then use /model to select from available models
  */
 
-import { getAgentDir, type ExtensionAPI, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+import {
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ModelRegistry,
+  type ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+import { USAGE_WIDGET_KEY, readUsageConfig, writeUsageConfig } from "./config.ts";
+import { sanitizeStatusText, truncateToWidth } from "./format.ts";
+import { usageSegments, type UsageSegment, type UsageSeverity } from "./usage.ts";
+import { UsageController } from "./usage-controller.ts";
 import modelsData from "./models.json" with { type: "json" };
 import customModelsData from "./custom-models.json" with { type: "json" };
 import patchData from "./patch.json" with { type: "json" };
@@ -402,12 +412,105 @@ export default function (pi: ExtensionAPI) {
     })),
   });
 
+  // Usage widget (5h / 7d / 30d).
+  // opencode-go meters the Go plan with a rolling 5h window, a weekly window and
+  // a monthly window. GET /zen/go/v1/usage publishes all three. The widget below
+  // the editor mirrors pi-better-openai's usage widget; the footer status line is
+  // the fallback when no terminal UI is attached.
+
+  let usageConfig = readUsageConfig();
+  let usageWidgetInstalled = false;
+  const usageController = new UsageController(() => usageConfig, updateUsageWidget);
+
+  const USAGE_SEVERITY_COLORS: Record<UsageSeverity, ThemeColor> = {
+    ok: "success",
+    warning: "warning",
+    critical: "error",
+    muted: "dim",
+  };
+
+  function usageSegmentsFor(ctx: ExtensionContext): UsageSegment[] | undefined {
+    const snapshot = usageController.snapshot;
+    if (!snapshot || !usageConfig.enabled || !usageController.isEligible(ctx)) return undefined;
+    const segments = usageSegments(snapshot, { showResetTimes: usageConfig.showResetTimes });
+    if (usageController.isStale()) segments.push({ text: " · stale", severity: "warning" });
+    return segments;
+  }
+
+  function updateUsageWidget(ctx: ExtensionContext): void {
+    try {
+      const segments = usageSegmentsFor(ctx);
+      if (!segments) {
+        if (usageWidgetInstalled) {
+          ctx.ui.setWidget(USAGE_WIDGET_KEY, undefined);
+          ctx.ui.setStatus(USAGE_WIDGET_KEY, undefined);
+          usageWidgetInstalled = false;
+        }
+        return;
+      }
+      if (ctx.mode === "tui") {
+        ctx.ui.setStatus(USAGE_WIDGET_KEY, undefined);
+        ctx.ui.setWidget(
+          USAGE_WIDGET_KEY,
+          (_tui, theme) => ({
+            invalidate() {},
+            render(width: number): string[] {
+              // Segments are captured per install, keeping render() free of the
+              // extension context so a stale ctx can never be touched mid-draw.
+              const line = segments
+                .map((segment) => theme.fg(USAGE_SEVERITY_COLORS[segment.severity], segment.text))
+                .join("");
+              return [truncateToWidth(line, width, theme.fg("dim", "\u2026"))];
+            },
+          }),
+          { placement: usageConfig.placement },
+        );
+      } else {
+        ctx.ui.setWidget(USAGE_WIDGET_KEY, undefined);
+        ctx.ui.setStatus(USAGE_WIDGET_KEY, sanitizeStatusText(segments.map((s) => s.text).join("")));
+      }
+      usageWidgetInstalled = true;
+    } catch {
+      // A stale extension context can surface here; the next session re-installs.
+    }
+  }
+
+  pi.registerCommand("opencode-go-usage", {
+    description: "Show, refresh, or toggle the OpenCode Go 5h / 7d / 30d usage widget",
+    handler: async (args, ctx) => {
+      const action = args.trim().toLowerCase();
+      if (action === "on" || action === "off") {
+        const enabled = action === "on";
+        usageConfig = { ...usageConfig, enabled };
+        const persisted = writeUsageConfig({ enabled });
+        const suffix = persisted ? "" : " for this session (could not write the config file)";
+        if (enabled) {
+          usageController.start(ctx);
+          ctx.ui.notify(`OpenCode Go usage widget enabled${suffix}.`, "info");
+        } else {
+          usageController.stop();
+          usageController.clear();
+          updateUsageWidget(ctx);
+          ctx.ui.notify(`OpenCode Go usage widget disabled${suffix}.`, "info");
+        }
+        return;
+      }
+      if (action === "debug") {
+        ctx.ui.notify(usageController.formatDebug(ctx), "info");
+        return;
+      }
+      // No argument (and "refresh") always re-reads the API and reports the breakdown.
+      await usageController.refresh(ctx, { notify: true, force: true });
+    },
+  });
+
   pi.on("before_provider_headers", (event, ctx) => {
     if (ctx.model?.provider !== PROVIDER_ID) return;
     applyOpenCodeSessionHeaders(event.headers, ctx.sessionManager.getSessionId());
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    usageController.start(ctx);
     revalidateAbort?.abort();
     revalidateAbort = new AbortController();
     const signal = revalidateAbort.signal;
@@ -438,7 +541,16 @@ export default function (pi: ExtensionAPI) {
     });
   });
 
+  pi.on("turn_end", (_event, ctx) => {
+    void usageController.refresh(ctx);
+  });
+
+  pi.on("model_select", (_event, ctx) => {
+    void usageController.refresh(ctx);
+  });
+
   pi.on("session_shutdown", () => {
     revalidateAbort?.abort();
+    usageController.shutdown();
   });
 }

package/models.json

@@ -239,6 +239,34 @@
     "contextWindow": 262144,
     "maxTokens": 262144
   },
+  {
+    "id": "deepseek-v4.1-flash",
+    "name": "DeepSeek V4.1 Flash",
+    "api": "openai-completions",
+    "baseUrl": "https://opencode.ai/zen/go/v1",
+    "reasoning": true,
+    "thinkingLevelMap": {
+      "off": null,
+      "minimal": null,
+      "low": "low",
+      "medium": null,
+      "high": "high",
+      "xhigh": null,
+      "max": "max"
+    },
+    "input": [
+      "text",
+      "image"
+    ],
+    "cost": {
+      "input": 0.15,
+      "output": 0.6,
+      "cacheRead": 0.003,
+      "cacheWrite": 0
+    },
+    "contextWindow": 1000000,
+    "maxTokens": 384000
+  },
   {
     "id": "hy3",
     "name": "Hy3",
@@ -580,34 +608,6 @@
     "contextWindow": 1000000,
     "maxTokens": 131072
   },
-  {
-    "id": "deepseek-flash",
-    "name": "DeepSeek V4.1 Flash",
-    "api": "openai-completions",
-    "baseUrl": "https://opencode.ai/zen/go/v1",
-    "reasoning": true,
-    "thinkingLevelMap": {
-      "off": null,
-      "minimal": null,
-      "low": "low",
-      "medium": null,
-      "high": "high",
-      "xhigh": null,
-      "max": "max"
-    },
-    "input": [
-      "text",
-      "image"
-    ],
-    "cost": {
-      "input": 0.15,
-      "output": 0.6,
-      "cacheRead": 0.003,
-      "cacheWrite": 0
-    },
-    "contextWindow": 1000000,
-    "maxTokens": 384000
-  },
   {
     "id": "mimo-v2.5",
     "name": "MiMo V2.5",

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "pi-opencode-go-provider",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "Opencode Go provider extension for pi - Fast, efficient GLM, Kimi, and MiniMax models through the opencode.ai API",
   "type": "module",
   "main": "index.ts",
   "scripts": {
     "clean": "echo 'nothing to clean'",
     "build": "echo 'nothing to build'",
-    "check": "echo 'nothing to check'",
-    "update-models": "node scripts/update-models.js"
+    "check": "npm run typecheck && npm run test",
+    "update-models": "node scripts/update-models.js",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "pi",
@@ -30,6 +32,8 @@
     ]
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1"
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "~22.19.0",
+    "typescript": "^6.0.3"
   }
 }

package/tests/format.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { sanitizeStatusText, stripAnsi, truncateToWidth, visibleWidth } from "../format.ts";
+
+const RED = "";
+const RESET = "";
+
+test("measures visible width without ANSI escapes", () => {
+  assert.equal(visibleWidth("abc"), 3);
+  assert.equal(visibleWidth(`${RED}abc${RESET}`), 3);
+  assert.equal(visibleWidth(""), 0);
+});
+
+test("strips ANSI escapes", () => {
+  assert.equal(stripAnsi(`${RED}abc${RESET}`), "abc");
+});
+
+test("truncates to a width with an ellipsis", () => {
+  assert.equal(truncateToWidth("abcdef", 10), "abcdef");
+  assert.equal(truncateToWidth("abcdef", 4), "abc…");
+  assert.equal(truncateToWidth("abcdef", 0), "");
+  assert.equal(truncateToWidth("abcdef", 4, "..."), "a...");
+});
+
+test("truncation keeps colour codes and stays within the width", () => {
+  const colored = `${RED}abcdef${RESET}`;
+  const cut = truncateToWidth(colored, 4);
+  assert.equal(cut.includes(RED), true);
+  assert.equal(visibleWidth(cut), 4);
+  assert.equal(stripAnsi(cut), "abc…");
+});
+
+test("collapses whitespace for the status bar", () => {
+  assert.equal(sanitizeStatusText("  a  \n  b \t c "), "a b c");
+});