pi-ollama-cloud 0.12.3 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.13.0] - 2026-10-07
+
+- Fix the usage command and status bar after Ollama moved quota data to `/api/balance`, supporting both legacy remaining-percentage windows and the included-balance allowance shape. Show allowance renewal dates and purchased credits when returned, and optionally display request totals from the documented `/api/usage` histogram endpoint.
+
 ## [0.12.3] - 2026-10-06
 
 - Keep the usage indicator accurate when turning it off or switching providers, and show clearer errors for connection problems and invalid responses.

package/README.md

@@ -206,18 +206,20 @@ A failed fetch throws a diagnostic message (likely cause + next steps) instead o
 | Command | Description |
 |---|---|
 | `/ollama-webtools [on\|off\|enable\|disable]` | Enable or disable the `ollama_web_search` and `ollama_web_fetch` tools. Toggles if no argument given. |
-| `/ollama-cloud-usage` | Show Ollama Cloud usage limits (one section per limit bucket the API reports), per-model request counts, and the 4-week activity cost. |
+| `/ollama-cloud-usage` | Show included quota or balance, billing-period renewal date when available, purchased credits, and request totals when the histogram endpoint is available. |
 | `/ollama-usage-status [on\|off\|enable\|disable]` | Enable or disable the footer usage status bar. Toggles if no argument given. |
 
 ## Usage status bar
 
 While an `ollama-cloud` model is the active provider, the footer shows a compact
-live usage readout with one segment per limit bucket the API reports
-(`5h ▕███░░░░░░░▏ 34% 7d ▕█░░░░░░░░░▏ 7%`, or a single `30d` segment) that
-refreshes every 5 minutes and after each agent turn (but no more often than every 5 minutes). It is colored by how close
-it is to the cap: green below 60%, yellow at 60-79%, red at 80%+. It reads the
-same undocumented `/api/usage` endpoint as `/ollama-cloud-usage` and clears
-itself on transient errors or when you switch to a non-Ollama-Cloud provider.
+live quota readout. It displays one segment per legacy quota window when those
+are returned, or a `plan` segment derived from the included balance and
+allowance. For example, `$55.50` remaining of a `$60.00` allowance displays as
+`plan ▕░░░░░░░░░░▏ 7%`. The bar refreshes every 5 minutes and after an agent turn (no more
+often than every 5 minutes). It is colored by usage: green below 60%, yellow
+at 60-79%, and red at 80% or above. Quota comes from the documented
+[`/api/balance` endpoint](https://docs.ollama.com/api/balance); transient errors
+or switching providers clear the status.
 
 It is off by default. Enable it at runtime with `/ollama-usage-status on`, or
 enable it by default with `"usageStatus": true` in `ollama-cloud.json`. If the
@@ -226,8 +228,8 @@ underlying error (e.g. a misconfigured API key).
 
 The quota-bar concept is inspired by
 [`@entelligentsia/pi-ollama-cloud-usage-tracker`](https://github.com/Entelligentsia/pi-ollama-cloud-usage-tracker),
-but this extension fetches usage from the `/api/usage` endpoint with the API key
-it already resolves, rather than scraping the settings page with Chrome cookies.
+but this extension fetches quota from `/api/balance` with the API key it already
+resolves, rather than scraping the settings page with Chrome cookies.
 
 ## Usage API for custom status bars
 
@@ -236,18 +238,19 @@ status bar instead of (or alongside) the built-in one. The relevant modules ship
 with the package and are importable directly:
 
 ```ts
-import { fetchUsage, formatUsage, formatUsageStatusColored } from "pi-ollama-cloud/usage.ts";
+import { fetchUsage, fetchUsageStats, formatUsage, formatUsageStatusColored } from "pi-ollama-cloud/usage.ts";
 import { getCloudApiKey } from "pi-ollama-cloud/utils.ts";
 import type { UsageData } from "pi-ollama-cloud/usage.ts";
 ```
 
 | Export | Description |
 |---|---|
-| `fetchUsage(apiKey, signal?)` | Fetch the raw `/api/usage` data, returning a typed `UsageData`. Throws a status-mapped error on 401/403/429/404/5xx. |
+| `fetchUsage(apiKey, signal?)` | Fetch quota from the documented [`/api/balance` endpoint](https://docs.ollama.com/api/balance), including legacy windows or the allowance-based billing-period shape. `UsageData.included.period.until` contains the renewal boundary when provided. |
 | `formatUsageStatusColored(theme, data)` | One-line status string with quota bars, colored by usage level. Takes a `Theme` (e.g. `ctx.ui.theme`). |
-| `formatUsage(data)` | Multi-line human-readable output (percentages, per-model request counts, activity cost). |
+| `fetchUsageStats(apiKey, range?, signal?)` | Fetch request histogram data from the documented [`/api/usage` endpoint](https://docs.ollama.com/api/cloud-usage), limited to 10 requests per minute per user. |
+| `formatUsage(data, stats?)` | Multi-line quota and billing-period output, with request totals when stats are provided. |
 | `getCloudApiKey(ctx)` | Resolve the Ollama Cloud API key the same way the extension does. |
-| `isUsageResponse(data)` / `isUsageLimit(data)` | Validators for parsing the raw response yourself. |
+| `isUsageResponse(data)` / `isUsageStats(data)` | Validators for parsing the raw responses yourself. |
 
 Example custom status bar:
 

package/index.ts

@@ -28,7 +28,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { loadConfig, resolveWebToolsEnv } from "./config.ts";
 import { GENERATED_MODELS } from "./models.generated.ts";
 import { OLLAMA_BASE, refreshOllamaCatalog } from "./models.ts";
-import { fetchUsage, formatUsage, formatUsageStatusColored } from "./usage.ts";
+import { fetchUsage, fetchUsageStats, formatUsage, formatUsageStatusColored, type UsageStats } from "./usage.ts";
 import { getCloudApiKey } from "./utils.ts";
 import { registerWebFetchTool, registerWebSearchTool } from "./web-tools.ts";
 
@@ -169,7 +169,17 @@ export default async function (pi: ExtensionAPI) {
       }
       try {
         const data = await fetchUsage(apiKey);
-        ctx.ui.notify(formatUsage(data), "info");
+        let stats: UsageStats | undefined;
+        let statsError: string | undefined;
+        try {
+          stats = await fetchUsageStats(apiKey);
+        } catch (err) {
+          statsError = err instanceof Error ? err.message : String(err);
+        }
+        ctx.ui.notify(formatUsage(data, stats), "info");
+        if (statsError) {
+          ctx.ui.notify(`Ollama Cloud request statistics unavailable: ${statsError}`, "warning");
+        }
       } catch (err) {
         ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
       }
@@ -178,10 +188,10 @@ export default async function (pi: ExtensionAPI) {
 
   // --- Usage Status Bar ---
 
-  // Footer status showing live usage while ollama-cloud is the
+  // Footer status showing live quota while ollama-cloud is the
   // active provider. Refreshes on a 5-minute timer; agent_end also triggers a
-  // refresh but is throttled to the same cooldown so a turn never hammers the
-  // undocumented /api/usage endpoint. The quota-bar concept is inspired by
+  // refresh but is throttled to the same cooldown. Quota comes from the
+  // /api/balance endpoint. The quota-bar concept is inspired by
   // @entelligentsia/pi-ollama-cloud-usage-tracker.
   const USAGE_STATUS_KEY = "ollama-usage";
   const USAGE_REFRESH_MS = 5 * 60_000;
@@ -240,7 +250,7 @@ export default async function (pi: ExtensionAPI) {
 
   pi.on("agent_end", async (_event, ctx) => {
     // Throttle the after-turn refresh to the same cooldown as the timer so a
-    // burst of turns never exceeds one /api/usage call per 5 minutes.
+    // burst of turns never exceeds one /api/balance call per 5 minutes.
     if (usageActive && isOllamaCloud(ctx) && Date.now() - lastRefreshAt >= USAGE_REFRESH_MS) {
       await refreshUsageStatus(ctx);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ollama-cloud",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "type": "module",
   "keywords": [
     "pi-package"

package/usage.ts

@@ -1,200 +1,209 @@
-/**
- * Ollama Cloud usage data plane: fetch and format /api/usage.
- *
- * Self-contained module. Depends on:
- *   - models.ts - only for OLLAMA_BASE URL constant
- *   - utils.ts  - fetchJsonWithTimeout
- * Does NOT depend on provider registration, model fetching, or API key
- * resolution (the caller resolves the key and passes it in).
- *
- * The /api/usage endpoint is undocumented and could change or disappear. The
- * fetch degrades gracefully: distinct HTTP statuses map to distinct
- * user-facing errors, and a malformed body raises a clear error rather than
- * crashing.
- *
- * The response shape has flipped twice: through 2026-09-02 it carried
- * limits.session and limits.weekly, on 2026-09-03 it switched to a single
- * limits.monthly bucket (0.10.0 adapted to that), and by 2026-09-07 it
- * returned session and weekly again. All three buckets are therefore optional
- * and whichever are present are displayed.
- */
-
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { OLLAMA_BASE } from "./models.ts";
 import { fetchJsonWithTimeout, httpError } from "./utils.ts";
 
-// --- Types ---
+export interface BalanceWindow {
+  remaining_percent: number;
+  resets_at?: string;
+}
 
-export interface UsageModel {
-  name: string;
-  request_count: number;
+export interface UsageData {
+  included?: {
+    session?: BalanceWindow;
+    weekly?: BalanceWindow;
+    monthly?: BalanceWindow;
+    balance_usd?: number;
+    allowance_usd?: number;
+    period?: { from?: string; until?: string };
+  };
+  purchased?: { balance_usd?: number };
 }
 
-export interface UsageLimit {
-  /** Fraction of the plan's cap, 0-1 (not tokens). */
-  usage: number;
-  /** Per-model request counts (not token counts). */
-  models: UsageModel[];
+export interface UsageBucket {
+  from?: string;
+  until?: string;
+  request_count: number;
+  partial?: boolean;
+  usage_usd?: number;
+  input_tokens?: number;
+  cached_input_tokens?: number;
+  output_tokens?: number;
 }
 
-export interface UsageActivity {
-  cost?: string;
-  period?: {
-    type?: string;
-    starting_at?: string;
-    ending_at?: string;
+export interface UsageStats {
+  range?: "24h" | "7d" | "30d";
+  totals: {
+    request_count: number;
+    usage_usd?: number;
+    input_tokens?: number;
+    cached_input_tokens?: number;
+    output_tokens?: number;
   };
-  models?: UsageModel[];
+  buckets?: UsageBucket[];
 }
 
-export interface UsageData {
-  limits: {
-    /** Monthly (30d) bucket, served by the API between 2026-09-03 and 2026-09-07. */
-    monthly?: UsageLimit;
-    /** Session (5h) bucket, served before 2026-09-03 and again as of 2026-09-07. */
-    session?: UsageLimit;
-    /** Weekly (7d) bucket, served before 2026-09-03 and again as of 2026-09-07. */
-    weekly?: UsageLimit;
-  };
-  activity?: UsageActivity;
+const USAGE_TIMEOUT_MS = 10000;
+
+function isObject(data: unknown): data is Record<string, unknown> {
+  return data !== null && typeof data === "object" && !Array.isArray(data);
 }
 
-// --- Constants ---
+export function isBalanceWindow(data: unknown): data is BalanceWindow {
+  if (!isObject(data) || typeof data.remaining_percent !== "number" || !Number.isFinite(data.remaining_percent)) {
+    return false;
+  }
+  return data.resets_at === undefined || typeof data.resets_at === "string";
+}
 
-const USAGE_TIMEOUT_MS = 10000;
+function isPurchased(data: unknown): boolean {
+  return isObject(data) && typeof data.balance_usd === "number" && Number.isFinite(data.balance_usd);
+}
 
-// --- Validation ---
+function isIncluded(data: unknown): data is NonNullable<UsageData["included"]> {
+  if (!isObject(data)) return false;
+  const windows = [data.session, data.weekly, data.monthly];
+  if (windows.some((window) => window !== undefined && !isBalanceWindow(window))) return false;
+
+  const balance = data.balance_usd;
+  const allowance = data.allowance_usd;
+  if (balance !== undefined && (typeof balance !== "number" || !Number.isFinite(balance))) return false;
+  if (allowance !== undefined && (typeof allowance !== "number" || !Number.isFinite(allowance))) return false;
+  if ((balance === undefined) !== (allowance === undefined)) return false;
+
+  if (data.period !== undefined) {
+    if (!isObject(data.period)) return false;
+    if (data.period.from !== undefined && typeof data.period.from !== "string") return false;
+    if (data.period.until !== undefined && typeof data.period.until !== "string") return false;
+  }
 
-/** Validate a single usage limit: a 0-1 fraction plus per-model request counts. */
-export function isUsageLimit(data: unknown): data is UsageLimit {
-  if (data == null || typeof data !== "object") return false;
-  const d = data as UsageLimit;
-  return (
-    typeof d.usage === "number" &&
-    Array.isArray(d.models) &&
-    d.models.every(
-      (m) =>
-        m != null &&
-        typeof m === "object" &&
-        typeof (m as UsageModel).name === "string" &&
-        typeof (m as UsageModel).request_count === "number",
-    )
-  );
+  return true;
 }
 
-/**
- * Validate a parsed /api/usage response: needs at least one valid limit bucket.
- * The endpoint is undocumented and flips shape unpredictably (monthly-only,
- * session+weekly, possibly other combinations), so any bucket present alone or
- * in any combination is accepted and rendered.
- */
 export function isUsageResponse(data: unknown): data is UsageData {
-  if (data == null || typeof data !== "object") return false;
-  const d = data as UsageData;
-  if (d.limits == null || typeof d.limits !== "object" || Array.isArray(d.limits)) return false;
-  const buckets = [d.limits.monthly, d.limits.session, d.limits.weekly];
-  return buckets.some(isUsageLimit) && buckets.every((bucket) => bucket === undefined || isUsageLimit(bucket));
+  if (!isObject(data)) return false;
+  const included = data.included;
+  const hasPurchased = isPurchased(data.purchased);
+  if (data.purchased !== undefined && !hasPurchased) return false;
+  if (included === undefined) return hasPurchased;
+  if (!isIncluded(included)) return false;
+
+  const hasWindow = [included.session, included.weekly, included.monthly].some(isBalanceWindow);
+  const hasAllowance = typeof included.balance_usd === "number" && typeof included.allowance_usd === "number";
+  return hasWindow || hasAllowance || hasPurchased;
 }
 
-// --- Fetch ---
+export function isUsageStats(data: unknown): data is UsageStats {
+  if (!isObject(data) || !isObject(data.totals) || typeof data.totals.request_count !== "number") return false;
+  if (data.buckets === undefined) return true;
+  return (
+    Array.isArray(data.buckets) &&
+    data.buckets.every((bucket) => isObject(bucket) && typeof bucket.request_count === "number")
+  );
+}
 
-/**
- * Fetch Ollama Cloud usage from the undocumented /api/usage endpoint.
- * The caller resolves the API key and passes it in.
- */
 export async function fetchUsage(apiKey: string, externalSignal?: AbortSignal): Promise<UsageData> {
   const res = await fetchJsonWithTimeout<UsageData>(
-    `${OLLAMA_BASE}/api/usage`,
-    {
-      method: "GET",
-      headers: { Authorization: `Bearer ${apiKey}` },
-    },
+    `${OLLAMA_BASE}/api/balance`,
+    { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
     USAGE_TIMEOUT_MS,
     externalSignal,
   );
-
   if (!res.ok) {
     if (res.status === 0) {
-      throw new Error(`Ollama Cloud usage failed: transport error (${res.error ?? "unknown"}). Try again shortly.`);
+      throw new Error(`Ollama Cloud balance failed: transport error (${res.error ?? "unknown"}). Try again shortly.`);
     }
-    // The 404 case is specific to this undocumented endpoint: it may have
-    // changed or disappeared, so surface that distinctly before the shared
-    // status mapping.
     if (res.status === 404) {
-      throw new Error(
-        "Ollama Cloud usage failed: the /api/usage endpoint is unavailable (status 404). " +
-          "It is undocumented and may have changed.",
-      );
+      throw new Error("Ollama Cloud balance failed: the /api/balance endpoint is unavailable (status 404).");
     }
-    httpError("usage", res.status, res.error);
-  }
-  if (!isUsageResponse(res.data)) {
-    throw new Error("Ollama Cloud usage failed: unexpected response shape from the API.");
+    httpError("balance", res.status, res.error);
   }
+  if (!isUsageResponse(res.data))
+    throw new Error("Ollama Cloud balance failed: unexpected response shape from the API.");
   return res.data;
 }
 
-// --- Formatting ---
+export async function fetchUsageStats(
+  apiKey: string,
+  range: "24h" | "7d" | "30d" = "7d",
+  externalSignal?: AbortSignal,
+): Promise<UsageStats> {
+  const res = await fetchJsonWithTimeout<UsageStats>(
+    `${OLLAMA_BASE}/api/usage?range=${range}`,
+    { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+    USAGE_TIMEOUT_MS,
+    externalSignal,
+  );
+  if (!res.ok) httpError("usage stats", res.status, res.error);
+  if (!isUsageStats(res.data))
+    throw new Error("Ollama Cloud usage stats failed: unexpected response shape from the API.");
+  return res.data;
+}
 
-/** Clamp a 0-1 usage fraction to a 0-100 percentage for display. */
-function usagePercent(usage: number): number {
-  if (!Number.isFinite(usage)) return 0;
-  return Math.min(Math.max(Math.round(usage * 100), 0), 100);
+function usedPercent(remaining: number): number {
+  if (!Number.isFinite(remaining)) return 100;
+  return Math.min(Math.max(Math.round(100 - remaining), 0), 100);
 }
 
-/** The limit buckets present in a response, in display order. */
-function limitSegments(data: UsageData): Array<{ label: string; short: string; limit: UsageLimit }> {
-  const segs: Array<{ label: string; short: string; limit: UsageLimit }> = [];
-  if (isUsageLimit(data.limits.session)) {
-    segs.push({ label: "Session (5h)", short: "5h", limit: data.limits.session });
-  }
-  if (isUsageLimit(data.limits.weekly)) {
-    segs.push({ label: "Weekly (7d)", short: "7d", limit: data.limits.weekly });
+function limitSegments(data: UsageData): Array<{ short: string; used: number }> {
+  const included = data.included;
+  if (!included) return [];
+  const segments: Array<{ short: string; used: number }> = [];
+  for (const [key, short] of [
+    ["session", "5h"],
+    ["weekly", "7d"],
+    ["monthly", "30d"],
+  ] as const) {
+    const window = included[key];
+    if (window && isBalanceWindow(window)) segments.push({ short, used: usedPercent(window.remaining_percent) });
   }
-  if (isUsageLimit(data.limits.monthly)) {
-    segs.push({ label: "Monthly (30d)", short: "30d", limit: data.limits.monthly });
+  if (
+    segments.length === 0 &&
+    typeof included.balance_usd === "number" &&
+    typeof included.allowance_usd === "number" &&
+    included.allowance_usd > 0
+  ) {
+    const used = (1 - included.balance_usd / included.allowance_usd) * 100;
+    segments.push({ short: "plan", used: Math.min(Math.max(Math.round(used), 0), 100) });
   }
-  return segs;
+  return segments;
 }
 
-/** Format usage for the /ollama-cloud-usage command output. */
-export function formatUsage(data: UsageData): string {
-  const lines: string[] = ["Ollama Cloud usage:"];
-
-  for (const seg of limitSegments(data)) {
-    lines.push(`  ${seg.label}: ${usagePercent(seg.limit.usage)}%`);
-    for (const m of seg.limit.models) {
-      lines.push(`    - ${m.name}: ${m.request_count} request${m.request_count === 1 ? "" : "s"}`);
+export function formatUsage(data: UsageData, stats?: UsageStats): string {
+  const lines = ["Ollama Cloud usage:"];
+  for (const segment of limitSegments(data)) lines.push(`  ${segment.short}: ${segment.used}% used`);
+  const included = data.included;
+  if (included && typeof included.balance_usd === "number" && typeof included.allowance_usd === "number") {
+    lines.push(
+      `  Included balance: $${included.balance_usd.toFixed(2)} / $${included.allowance_usd.toFixed(2)} remaining`,
+    );
+    if (included.period?.from || included.period?.until) {
+      lines.push(`  Included allowance period: ${included.period.from ?? "?"} to ${included.period.until ?? "?"}`);
+      if (included.period.until) lines.push(`  Included allowance renews: ${included.period.until}`);
     }
   }
-
-  if (typeof data.activity?.cost === "string") {
-    lines.push(`  Activity (4wk): $${data.activity.cost}`);
+  if (data.purchased?.balance_usd && data.purchased.balance_usd > 0) {
+    lines.push(`  Purchased credits: $${data.purchased.balance_usd.toFixed(2)}`);
+  }
+  if (stats) {
+    lines.push(`  Requests (${stats.range ?? "7d"}): ${stats.totals.request_count.toLocaleString()}`);
+    const current = stats.buckets?.at(-1);
+    if (current?.partial) lines.push(`    - current period: ${current.request_count.toLocaleString()}`);
   }
-
   return lines.join("\n");
 }
 
-/** Render a 10-character quota bar for a 0-100 percentage. */
 function quotaBar(pct: number): string {
   const filled = Math.min(Math.max(Math.floor(pct / 10), 0), 10);
   return `▕${"█".repeat(filled)}${"░".repeat(10 - filled)}▏`;
 }
 
-/** Color a single usage segment by how close it is to the cap. */
 function colorSegment(theme: Theme, label: string, pct: number): string {
   const color = pct >= 80 ? "error" : pct >= 60 ? "warning" : "success";
   return theme.fg(color, `${label} ${quotaBar(pct)} ${pct}%`);
 }
 
-/**
- * Compact one-line usage for the footer status bar, colored by usage level,
- * with one segment per limit bucket present in the response (5h and 7d, or
- * 30d when the API serves the monthly shape). The color reflects the usage
- * fraction rather than pace because the bucket periods differ per shape.
- */
 export function formatUsageStatusColored(theme: Theme, data: UsageData): string {
   return limitSegments(data)
-    .map((seg) => colorSegment(theme, seg.short, usagePercent(seg.limit.usage)))
+    .map((segment) => colorSegment(theme, segment.short, segment.used))
     .join(" ");
 }