@cardinal4/opencode-tavily-quota 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-tavily-quota contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# opencode-tavily-quota
+
+An OpenCode 2 TUI plugin that shows the remaining Tavily API credits in the
+session sidebar.
+
+```
+Tavily
+█████████████████████████   84% left
+```
+
+## Install
+
+```sh
+opencode plugin add @cardinal4/opencode-tavily-quota
+```
+
+Or declare it in `cli.json` to pass the API key option (see
+[Configuration](#configuration)). If a local copy exists under
+`~/.config/opencode/plugins/opencode-tavily-quota/`, remove it after installing
+the package so the plugin is not loaded twice.
+
+The sidebar follows the built-in quota styling — the heading uses the default
+text color and the body (bar included) uses the muted/subdued text color. It
+polls every 10 minutes and can be refreshed on demand with the command below.
+
+## Requirements
+
+- OpenCode 2 (`opencode --version` reports `2.x`).
+- A Tavily API key, supplied one of two ways:
+  - `TAVILY_API_KEY` in the environment OpenCode is started from, or
+  - the `apiKey` plugin option configured on this plugin in `cli.json`.
+
+`TAVILY_API_KEY` takes precedence when both are set. The key is read in the CLI
+process and sent only to `api.tavily.com` as a `Bearer` token. It is never
+displayed.
+
+The `apiKey` option also accepts `{file:...}` and `{env:...}` references, which
+the plugin expands itself because `cli.json` does not (unlike `opencode.jsonc`).
+
+## Layout
+
+```
+~/.config/opencode/plugins/opencode-tavily-quota/
+├── index.ts        # server entrypoint (no-op; required for discovery)
+├── tui.tsx         # TUI entrypoint: sidebar slot + command
+├── usage.ts        # key resolution, /usage fetch, formatting
+└── usage.test.ts   # unit tests for usage.ts
+```
+
+OpenCode discovers local plugins as directories under
+`~/.config/opencode/plugins/`, or `<project>/.opencode/plugins/`. The server
+entrypoint (`index.ts` / `server.ts`) satisfies discovery; the `tui` entrypoint
+(`tui.tsx`) is loaded by the CLI to render the sidebar.
+
+## Configuration
+
+Register the plugin in `cli.json` to pass the API key as a plugin option:
+
+```json title="cli.json"
+{
+  "plugins": [
+    {
+      "package": "file:///home/me/.config/opencode/plugins/opencode-tavily-quota",
+      "options": {
+        "apiKey": "tvly-..."
+      }
+    }
+  ]
+}
+```
+
+The CLI-only `cli.json` entry also keeps the plugin active when the TUI is
+connected to a remote server. The same entry accepts a `refreshMs` option to
+override the default 10 minute poll interval (Tavily's `/usage` endpoint allows
+at most 10 requests per 10 minutes, so keep it at or above that).
+
+### Keeping the key out of the file
+
+`cli.json` is not processed like `opencode.jsonc`: OpenCode does not expand
+`{file:...}` or `{env:...}` in plugin options, so the plugin does it. Use either
+reference as `apiKey` to avoid pasting the raw key into `cli.json`:
+
+```json title="cli.json"
+{
+  "plugins": [
+    {
+      "package": "file:///home/me/.config/opencode/plugins/opencode-tavily-quota",
+      "options": {
+        "apiKey": "{file:~/.secrets/tavily-api-key}"
+      }
+    }
+  ]
+}
+```
+
+`{env:NAME}` reads an environment variable (empty when unset). `{file:PATH}`
+reads a file's trimmed contents, with `~/` expanding to the home directory and
+relative paths resolving against the CLI's working directory. `TAVILY_API_KEY`
+still wins over `apiKey` when both are set. A missing or unreadable file is
+reported in the sidebar instead of being used as the key.
+
+## Commands
+
+- `/tavily-quota` — slash command that re-fetches and reports the current quota
+  in a toast.
+- "Refresh Tavily quota" — the same action from the command palette (`Ctrl+P`).
+
+## Data source
+
+`GET https://api.tavily.com/usage` with `Authorization: Bearer <key>`. The
+plugin prefers the account plan (`account.plan_limit` / `account.plan_usage`,
+e.g. `Researcher` with 1000 monthly credits) and falls back to the per-key limit
+when the plan limit is absent. A `null` per-key limit (unlimited key) is
+therefore handled.
+
+## Development
+
+`usage.ts` is deliberately free of OpenCode and OpenTUI imports so it can be
+tested anywhere. `usage.test.ts` covers the pure quota math (`deriveSnapshot`,
+`formatPercent`, `formatRemaining`), key resolution, and every `fetchQuota`
+error branch using an injected `fetch`.
+
+Run the tests and type check from the repository root:
+
+```sh
+npm install
+npm test        # tsx --test usage.test.ts
+npm run typecheck
+```
+
+## Notes
+
+- The plugin is a no-op on the server. All work happens in the CLI runtime,
+  which is where TUI slots live.

package/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Server entrypoint for the Tavily quota sidebar plugin.
+ *
+ * OpenCode discovers a local plugin directory by its `index` (server) entry and
+ * loads the `tui` entry beside it for the terminal UI. All rendering happens in
+ * the CLI runtime (`tui.tsx`); this file only exists so the directory is a
+ * complete plugin and shows up by id instead of as an anonymous entry.
+ *
+ * It deliberately imports nothing beyond `@opencode/plugin` so the background
+ * service can load it in any runtime.
+ */
+
+import { Plugin } from "@opencode/plugin";
+
+export const PLUGIN_ID = "opencode-tavily-quota";
+
+export default Plugin.define({
+  id: PLUGIN_ID,
+  setup() {
+    // Intentional no-op: the sidebar and command are registered by the TUI
+    // entrypoint (tui.tsx), which runs in the CLI process.
+  },
+});

package/package.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@cardinal4/opencode-tavily-quota",
+  "version": "1.0.0",
+  "description": "OpenCode 2 TUI plugin that shows remaining Tavily API credits in the sidebar.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./index.ts",
+    "./server": "./index.ts",
+    "./tui": "./tui.tsx"
+  },
+  "files": [
+    "index.ts",
+    "tui.tsx",
+    "usage.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "tsx --test usage.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-tui",
+    "tavily",
+    "quota",
+    "credits"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cardin/opencode-tavily-quota.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cardin/opencode-tavily-quota/issues"
+  },
+  "homepage": "https://github.com/cardin/opencode-tavily-quota#readme",
+  "peerDependencies": {
+    "@opencode/plugin": "^2.0.7",
+    "@opentui/core": ">=0.5.10",
+    "@opentui/solid": ">=0.5.10",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.0.7",
+    "@opentui/core": "^0.5.11",
+    "@opentui/solid": "^0.5.11",
+    "@types/node": "^22.0.0",
+    "solid-js": "^1.9.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tui.tsx

@@ -0,0 +1,197 @@
+/** @jsxImportSource @opentui/solid */
+
+/**
+ * Tavily quota sidebar — an OpenCode 2 TUI plugin.
+ *
+ * Renders the remaining Tavily API credits in the session sidebar
+ * (`sidebar.content`) and exposes a `/tavily-quota` slash command /
+ * "Refresh Tavily quota" palette command that re-fetches on demand.
+ *
+ * The plugin owns no session state: Tavily credits are account-wide, so a
+ * single snapshot is shared by every sidebar render and refreshed on a timer.
+ * Colors follow the built-in quota sections: the heading uses the default text
+ * color and the body (bar included) uses the muted/subdued text color.
+ *
+ * Authenticate with `TAVILY_API_KEY`, or with the `apiKey` plugin option
+ * configured on this plugin in `cli.json`. Resolution and the network call
+ * live in `./usage.ts`.
+ */
+
+import type { RGBA } from "@opentui/core";
+import { Plugin } from "@opencode/plugin/tui";
+import { createSignal } from "solid-js";
+import {
+  fetchQuota,
+  formatPercent,
+  formatQuotaLine,
+  formatRemaining,
+  type QuotaSnapshot,
+} from "./usage";
+
+type Context = Plugin.Context;
+
+export const PLUGIN_ID = "opencode-tavily-quota";
+// Tavily's `/usage` endpoint allows at most 10 requests per 10 minutes, so poll
+// once per window and rely on the `/tavily-quota` command for on-demand reads.
+const REFRESH_INTERVAL_MS = 600_000;
+
+type ViewState =
+  | { status: "loading" }
+  | { status: "ready"; snapshot: QuotaSnapshot }
+  | { status: "error"; message: string };
+
+type ThemeColors = {
+  text?: RGBA;
+  textMuted?: RGBA;
+};
+
+/**
+ * OpenCode 2.0.7 exposes `text.default` / `text.subdued`; later builds renamed
+ * the leaves to `text.base` / `text.muted`. Read whichever the running build
+ * provides so the plugin matches the built-in quota sections on both.
+ */
+function readThemeColors(context: Context): ThemeColors {
+  const text = context.theme.text as unknown as {
+    default?: RGBA;
+    base?: RGBA;
+    subdued?: RGBA;
+    muted?: RGBA;
+  };
+  return {
+    text: text.default ?? text.base,
+    textMuted: text.subdued ?? text.muted,
+  };
+}
+
+export function buildLines(state: ViewState): string[] {
+  if (state.status === "loading") {
+    return ["loading…"];
+  }
+  if (state.status === "error") {
+    return [`⚠ ${state.message}`];
+  }
+
+  const snapshot = state.snapshot;
+  return [formatQuotaLine(snapshot)];
+}
+
+function TavilyQuotaSidebar(props: { context: Context; state: () => ViewState }) {
+  const colors = () => readThemeColors(props.context);
+  // Keep the quota line on one line; let an error message wrap instead of
+  // truncating it, since it can be longer than the sidebar.
+  const wrapMode = () => (props.state().status === "error" ? "word" : "none");
+
+  return (
+    <box gap={0} flexDirection="column">
+      <text fg={colors().text}>
+        <b>Tavily</b>
+      </text>
+      {buildLines(props.state()).map((line) => (
+        <text fg={colors().textMuted} wrapMode={wrapMode()}>
+          {line}
+        </text>
+      ))}
+    </box>
+  );
+}
+
+function TavilyQuotaCommands(props: {
+  context: Context;
+  refresh: () => Promise<ViewState>;
+}) {
+  props.context.keymap.layer(() => ({
+    mode: "global",
+    commands: [
+      {
+        id: `${PLUGIN_ID}.refresh`,
+        title: "Refresh Tavily quota",
+        description: "Re-fetch remaining Tavily API credits and show a summary",
+        group: "Tavily",
+        palette: true,
+        slash: { name: "tavily-quota" },
+        run: async () => {
+          const next = await props.refresh();
+          const message =
+            next.status === "ready"
+              ? `${formatRemaining(next.snapshot)} · ${formatPercent(next.snapshot.percentRemaining)}`
+              : next.status === "error"
+                ? next.message
+                : "still loading…";
+          props.context.ui.toast.show({
+            title: "Tavily quota",
+            message,
+            variant: next.status === "error" ? "error" : "info",
+          });
+        },
+      },
+    ],
+  }));
+
+  return null;
+}
+
+export const TavilyQuotaTuiPlugin = Plugin.define({
+  id: PLUGIN_ID,
+  async setup(context) {
+    const [state, setState] = createSignal<ViewState>({ status: "loading" });
+    const apiKey = typeof context.options.apiKey === "string" ? context.options.apiKey : undefined;
+    const refreshMs =
+      typeof context.options.refreshMs === "number" && context.options.refreshMs > 0
+        ? context.options.refreshMs
+        : REFRESH_INTERVAL_MS;
+
+    let disposed = false;
+    let inFlight = false;
+
+    const refresh = async (): Promise<ViewState> => {
+      if (inFlight) return state();
+      inFlight = true;
+      try {
+        const result = await fetchQuota({ apiKey });
+        if (!disposed) {
+          setState(
+            result.ok
+              ? { status: "ready", snapshot: result.snapshot }
+              : { status: "error", message: result.message },
+          );
+        }
+      } catch (error) {
+        // `fetchQuota` is written never to throw, but a rejected promise here
+        // must not take down the sidebar: surface it inline instead.
+        if (!disposed) {
+          setState({
+            status: "error",
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      } finally {
+        inFlight = false;
+      }
+      return state();
+    };
+
+    const stopSidebar = context.ui.slot({
+      append: "sidebar.content",
+      render: () => <TavilyQuotaSidebar context={context} state={state} />,
+    });
+
+    // `keymap.layer` reads Solid context, so it must be mounted from a slot
+    // component rather than called directly during plugin setup.
+    const stopCommands = context.ui.slot({
+      append: "app",
+      render: () => <TavilyQuotaCommands context={context} refresh={refresh} />,
+    });
+
+    void refresh();
+    const interval = setInterval(() => void refresh(), refreshMs);
+
+    return () => {
+      disposed = true;
+      clearInterval(interval);
+      stopSidebar();
+      stopCommands();
+    };
+  },
+});
+
+export default TavilyQuotaTuiPlugin;

package/usage.ts

@@ -0,0 +1,299 @@
+/**
+ * Tavily quota client for the sidebar plugin.
+ *
+ * Pure formatting/derivation helpers are split from the single network call so
+ * they can be unit tested without touching the network, real credentials, or
+ * the OpenCode runtime. Node builtins only; no OpenCode or OpenTUI imports.
+ *
+ * The `apiKey` plugin option may be a literal key or an `{env:NAME}` /
+ * `{file:PATH}` reference. OpenCode expands those references in
+ * `opencode.json(c)` but not in `cli.json`, so this module expands them itself.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export const USAGE_URL = "https://api.tavily.com/usage";
+export const DEFAULT_TIMEOUT_MS = 15_000;
+
+/**
+ * Sidebar content width shared with the built-in quota section, which renders
+ * in a 36-column sidebar (`TUI_SIDEBAR_MAX_WIDTH` in opencode-quota).
+ */
+export const SIDEBAR_WIDTH = 36;
+/**
+ * Width the quota section reserves for its `100% left` / `100% used` label, so
+ * labels line up vertically across sections.
+ */
+export const PERCENT_COLUMN_WIDTH = "100% left".length;
+/** Gap between the bar and its label, matching the quota section's separator. */
+export const BAR_SEPARATOR = "  ";
+/**
+ * Bar width that lines the Tavily bar up with the quota section's bars:
+ * `36 (sidebar) − 2 (separator) − 9 (percent column) = 25`.
+ */
+export const DEFAULT_BAR_WIDTH = SIDEBAR_WIDTH - BAR_SEPARATOR.length - PERCENT_COLUMN_WIDTH;
+
+/** Shape of `GET https://api.tavily.com/usage` (all fields optional). */
+export interface TavilyUsagePayload {
+  key?: {
+    usage?: number | null;
+    limit?: number | null;
+  } | null;
+  account?: {
+    current_plan?: string | null;
+    plan_usage?: number | null;
+    plan_limit?: number | null;
+    paygo_usage?: number | null;
+    paygo_limit?: number | null;
+  } | null;
+}
+
+export interface QuotaSnapshot {
+  /** Plan name reported by Tavily, e.g. `Researcher`. */
+  planName: string;
+  /** Credits consumed this billing cycle. */
+  used: number;
+  /** Credits included this billing cycle. */
+  limit: number;
+  /** Credits still available (`limit - used`, never negative). */
+  remaining: number;
+  /** `remaining / limit` as a percentage in `[0, 100]`. */
+  percentRemaining: number;
+  /** Milliseconds since epoch when the snapshot was produced. */
+  updatedAt: number;
+}
+
+export type QuotaResult =
+  | { ok: true; snapshot: QuotaSnapshot }
+  | { ok: false; message: string };
+
+export interface FetchQuotaOptions {
+  /** Environment to read `TAVILY_API_KEY` from. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Key supplied as a plugin option (e.g. from `cli.json`). */
+  apiKey?: string;
+  /** File reader for `{file:...}` references in `apiKey`. Injected by tests. */
+  readFile?: (path: string) => string;
+  /** Home directory for `~/` in `{file:...}`. Injected by tests. */
+  home?: string;
+  /** Base directory for relative `{file:...}` paths. Injected by tests. */
+  cwd?: string;
+  /** Request timeout in milliseconds. */
+  timeoutMs?: number;
+  /** Injectable fetch, used by tests. Defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Injectable clock, used by tests. Defaults to `Date.now`. */
+  now?: number;
+}
+
+function finite(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * `{env:NAME}` and `{file:PATH}` references accepted in the `apiKey` option.
+ * This mirrors the references OpenCode expands in `opencode.json(c)`, but the
+ * expansion lives here because `cli.json` passes plugin options through
+ * verbatim.
+ */
+export interface ExpandOptions {
+  /** Environment used by `{env:NAME}`. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Reads a file as UTF-8. Defaults to `readFileSync`. Injected by tests. */
+  readFile?: (path: string) => string;
+  /** Home directory for `~/`. Defaults to `os.homedir()`. */
+  home?: string;
+  /** Base directory for relative paths. Defaults to `process.cwd()`. */
+  cwd?: string;
+}
+
+const OPTION_REFERENCE = /\{(env|file):([^}]+)\}/g;
+
+/**
+ * Expand every `{env:NAME}` and `{file:PATH}` reference in a plugin option.
+ *
+ * `{env:NAME}` reads an environment variable (empty string when unset).
+ * `{file:PATH}` reads a file's trimmed contents; `~/` expands to the home
+ * directory and relative paths resolve against `cwd`. Unreadable files throw
+ * with the offending reference and resolved path.
+ */
+export function expandOptionValue(value: string, options: ExpandOptions = {}): string {
+  const env = options.env ?? process.env;
+  const readFile = options.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+  const home = options.home ?? homedir();
+  const cwd = options.cwd ?? process.cwd();
+
+  return value.replace(OPTION_REFERENCE, (match, kind: string, body: string) => {
+    if (kind === "env") return env[body] ?? "";
+
+    const raw = body.trim();
+    const path =
+      raw === "~"
+        ? home
+        : raw.startsWith("~/")
+          ? join(home, raw.slice(2))
+          : isAbsolute(raw)
+            ? raw
+            : resolve(cwd, raw);
+    try {
+      return readFile(path).trim();
+    } catch (cause) {
+      throw new Error(`bad file reference: "${match}" (${path}) could not be read`, { cause });
+    }
+  });
+}
+
+/**
+ * Resolve the Tavily API key: `TAVILY_API_KEY` first, then the `apiKey` plugin
+ * option configured in `cli.json`. Reference values such as
+ * `{file:~/.secrets/tavily-api-key}` are expanded here (see
+ * `expandOptionValue`), since `cli.json` does not expand them itself. Never
+ * logs or returns the key beyond the caller.
+ */
+export function resolveApiKey(
+  env: Record<string, string | undefined> = process.env,
+  apiKey?: string,
+  options: Omit<ExpandOptions, "env"> = {},
+): string {
+  const fromEnv = (env.TAVILY_API_KEY ?? "").trim();
+  if (fromEnv) return fromEnv;
+  const raw = (apiKey ?? "").trim();
+  if (!raw) return "";
+  return expandOptionValue(raw, { ...options, env }).trim();
+}
+
+/**
+ * Derive the headline credit quota from a `/usage` payload.
+ *
+ * Prefers the account plan (`plan_limit`/`plan_usage`) because a per-key limit
+ * is often `null` while the account still has a monthly allowance. Falls back
+ * to the key limit when no positive plan limit is reported.
+ */
+export function deriveSnapshot(
+  payload: TavilyUsagePayload,
+  now: number = Date.now(),
+): QuotaResult {
+  const account = payload.account ?? {};
+  const key = payload.key ?? {};
+
+  const planLimit = finite(account.plan_limit);
+  const planUsage = finite(account.plan_usage);
+  const keyLimit = finite(key.limit);
+  const keyUsage = finite(key.usage);
+
+  const usePlan = planLimit !== null && planLimit > 0;
+  const limit = usePlan ? planLimit : keyLimit;
+  const used = usePlan ? planUsage ?? 0 : keyUsage ?? 0;
+
+  if (limit === null || limit <= 0) {
+    return { ok: false, message: "Tavily returned no credit limit for this key" };
+  }
+
+  const remaining = Math.max(0, limit - used);
+  const planName =
+    typeof account.current_plan === "string" && account.current_plan.trim()
+      ? account.current_plan.trim()
+      : "Tavily";
+
+  return {
+    ok: true,
+    snapshot: {
+      planName,
+      used,
+      limit,
+      remaining,
+      percentRemaining: (remaining / limit) * 100,
+      updatedAt: now,
+    },
+  };
+}
+
+/** Format a remaining percentage for the sidebar. */
+export function formatPercent(percentRemaining: number): string {
+  const clamped = Math.max(0, Math.min(100, percentRemaining));
+  return `${clamped.toFixed(clamped >= 10 ? 0 : 1)}%`;
+}
+
+/** Render a fixed-width progress bar for a remaining percentage. */
+export function progressBar(percentRemaining: number, width = DEFAULT_BAR_WIDTH): string {
+  const clamped = Math.max(0, Math.min(100, percentRemaining));
+  const safeWidth = Math.max(1, Math.floor(width));
+  const filled = Math.round((clamped / 100) * safeWidth);
+  return "█".repeat(filled) + "░".repeat(Math.max(0, safeWidth - filled));
+}
+
+/**
+ * Compose the single sidebar line: the bar plus a `84% left` label.
+ *
+ * The bar matches the built-in quota section's bars and the label sits in the
+ * same right-aligned percent column, so the two sections line up. The exact
+ * credit count is still available from `formatRemaining` (used by the toast).
+ */
+export function formatQuotaLine(
+  snapshot: QuotaSnapshot,
+  width = DEFAULT_BAR_WIDTH,
+): string {
+  const label = `${formatPercent(snapshot.percentRemaining)} left`;
+  return `${progressBar(snapshot.percentRemaining, width)}${BAR_SEPARATOR}${label.padStart(PERCENT_COLUMN_WIDTH)}`;
+}
+
+/** Format the headline line, e.g. `839 credits left`. */
+export function formatRemaining(snapshot: QuotaSnapshot): string {
+  return `${snapshot.remaining} credits left`;
+}
+
+/**
+ * Fetch and derive the current Tavily quota.
+ *
+ * Never throws: every failure is returned as `{ ok: false, message }` so the
+ * sidebar can render it inline.
+ */
+export async function fetchQuota(options: FetchQuotaOptions = {}): Promise<QuotaResult> {
+  let key: string;
+  try {
+    key = resolveApiKey(options.env, options.apiKey, options);
+  } catch (error) {
+    // A `{file:...}` option can point at a missing or unreadable file; surface
+    // that inline instead of rejecting the sidebar render.
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+  if (!key) {
+    return {
+      ok: false,
+      message: "no Tavily API key (set TAVILY_API_KEY or the apiKey plugin option)",
+    };
+  }
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let response: Response;
+  try {
+    response = await fetchImpl(USAGE_URL, {
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { ok: false, message: `request failed: ${reason}` };
+  }
+
+  if (response.status === 401) {
+    return { ok: false, message: "API key rejected (401)" };
+  }
+  if (response.status === 429) {
+    return { ok: false, message: "rate limited on /usage (10 req / 10 min)" };
+  }
+  if (!response.ok) {
+    return { ok: false, message: `HTTP ${response.status} from /usage` };
+  }
+
+  let payload: TavilyUsagePayload;
+  try {
+    payload = (await response.json()) as TavilyUsagePayload;
+  } catch {
+    return { ok: false, message: "invalid JSON from /usage" };
+  }
+
+  return deriveSnapshot(payload, options.now);
+}