pi-opencode-go-provider 1.0.24 → 1.1.0

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). Each account carries its own budgets, so when [pi-multiprovider](https://github.com/monotykamary/pi-multiprovider) 0.8.0+ pools several `opencode-go` accounts the widget bills the session's active one and repaints on every switch or resume.
 
 ## Installation
 
@@ -110,6 +111,65 @@ 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`.
+
+### Pooled accounts
+
+When [pi-multiprovider](https://github.com/monotykamary/pi-multiprovider)
+0.8.0+ pools several `opencode-go` accounts, usage reads bill the session's
+active account instead of Pi's default credential: every account has its own
+5h / 7d / 30d budgets. The widget also repaints when the account changes,
+including when a resumed session restores the account last chosen with
+`/switch-account`, rather than showing the previous account until the next
+poll. Without pi-multiprovider nothing changes: the widget bills the key from
+the resolution order above.
+
 ## Authentication
 
 The opencode-go API key can be configured in multiple ways. Credentials are resolved in this order:
@@ -126,7 +186,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/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,23 @@
  * 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 {
+  isMultiproviderService,
+  MULTIPROVIDER_SERVICE_EVENT,
+  setActiveMultiproviderService,
+  type MultiproviderService,
+} from "./multiprovider.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 +418,134 @@ 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);
+  let usageContext: ExtensionContext | undefined;
+
+  // Follow pi-multiprovider's active pooled account. Usage is per-account, so a
+  // switch — and a resume, which replays the account the session last switched
+  // to — must repaint the widget instead of waiting for the next poll. Without
+  // pi-multiprovider nothing here activates and resolution stays unchanged.
+  let multiproviderService: MultiproviderService | undefined;
+  let unsubscribeMultiprovider: (() => void) | undefined;
+  const refreshUsageForActiveAccount = (ctx: ExtensionContext | undefined): void => {
+    if (ctx === undefined) return;
+    void usageController.refresh(ctx, { force: true });
+  };
+  if (typeof pi.events?.on === "function") {
+    pi.events.on(MULTIPROVIDER_SERVICE_EVENT, (value: unknown) => {
+      if (!isMultiproviderService(value)) return;
+      if (value !== multiproviderService) {
+        unsubscribeMultiprovider?.();
+        multiproviderService = value;
+        setActiveMultiproviderService(value);
+        unsubscribeMultiprovider = value.onActiveAccountChanged(PROVIDER_ID, (event) => {
+          refreshUsageForActiveAccount(usageContext ?? event.ctx);
+        });
+      }
+      // The event re-fires at every session start with the same stable object,
+      // so this also catches a service that appeared mid-session.
+      refreshUsageForActiveAccount(usageContext);
+    });
+  }
+
+  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) => {
+    usageContext = ctx;
+    usageController.start(ctx);
     revalidateAbort?.abort();
     revalidateAbort = new AbortController();
     const signal = revalidateAbort.signal;
@@ -438,7 +576,21 @@ 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();
+    usageContext = undefined;
+    unsubscribeMultiprovider?.();
+    unsubscribeMultiprovider = undefined;
+    multiproviderService = undefined;
+    setActiveMultiproviderService(undefined);
+    usageController.shutdown();
   });
 }

package/multiprovider.ts

@@ -0,0 +1,74 @@
+/**
+ * Soft bridge to pi-multiprovider.
+ *
+ * When pi-multiprovider pools several opencode-go accounts it announces a
+ * service on Pi's event bus and notifies followers whenever the session's
+ * active account changes — including a resume, which replays the account the
+ * session last switched to. Usage is account-scoped: each account has its own
+ * 5h / 7d / 30d budget, so the widget has to bill the active pooled account
+ * instead of whichever credential Pi resolves on its own. Without that
+ * extension everything here stays inert and resolution is unchanged.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const MULTIPROVIDER_SERVICE_EVENT = "pi-multiprovider:service";
+
+export type MultiproviderActiveAccount = {
+  id: string;
+  label: string;
+  authKind: string;
+};
+
+export type MultiproviderAccountAuth = {
+  accessToken: string;
+  label: string;
+  source?: string;
+};
+
+export type MultiproviderAccountChangedEvent = {
+  providerId: string;
+  account: MultiproviderActiveAccount | undefined;
+  ctx: ExtensionContext;
+};
+
+export type MultiproviderServiceContext = Pick<
+  ExtensionContext,
+  "modelRegistry" | "model" | "sessionManager"
+>;
+
+export type MultiproviderService = {
+  getActiveAccount(
+    providerId: string,
+    ctx: MultiproviderServiceContext,
+  ): Promise<MultiproviderActiveAccount | undefined>;
+  resolveActiveAccountAuth(
+    providerId: string,
+    ctx: MultiproviderServiceContext,
+    signal?: AbortSignal,
+  ): Promise<MultiproviderAccountAuth | undefined>;
+  onActiveAccountChanged(
+    providerId: string,
+    callback: (event: MultiproviderAccountChangedEvent) => void,
+  ): () => void;
+};
+
+export function isMultiproviderService(value: unknown): value is MultiproviderService {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<MultiproviderService>;
+  return (
+    typeof candidate.getActiveAccount === "function" &&
+    typeof candidate.resolveActiveAccountAuth === "function" &&
+    typeof candidate.onActiveAccountChanged === "function"
+  );
+}
+
+let activeService: MultiproviderService | undefined;
+
+export function setActiveMultiproviderService(service: MultiproviderService | undefined): void {
+  activeService = service;
+}
+
+export function getActiveMultiproviderService(): MultiproviderService | undefined {
+  return activeService;
+}

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "pi-opencode-go-provider",
-  "version": "1.0.24",
+  "version": "1.1.0",
   "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": "npm run typecheck && npm run test",
+    "update-models": "node scripts/update-models.js",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
   "keywords": [
     "pi",
     "extension",
@@ -24,12 +32,8 @@
     ]
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1"
-  },
-  "scripts": {
-    "clean": "echo 'nothing to clean'",
-    "build": "echo 'nothing to build'",
-    "check": "echo 'nothing to check'",
-    "update-models": "node scripts/update-models.js"
+    "@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");
+});