pi-ollama-cloud 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -2,7 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.9.0] - 2026-08-11
+
+- Add `/ollama-cloud-usage` command to show Ollama Cloud session (5h) and weekly (7d) usage limits, per-model request counts, and the 4-week activity cost, fetched from the undocumented `/api/usage` endpoint with the already-resolved API key.
+- Add a footer usage status bar (`5h ▕███░░░░░░░▏ 34% 7d ▕████░░░░░░▏ 45%`) while an `ollama-cloud` model is active, refreshing every 5 minutes and after each agent turn (throttled so it never exceeds one /api/usage call per 5 minutes). Segments are colored by usage level (green <60%, yellow 60-79%, red 80%+). The quota-bar concept is inspired by `@entelligentsia/pi-ollama-cloud-usage-tracker`. Off by default; enable with `/ollama-usage-status on` or `"usageStatus": true` in `ollama-cloud.json`.
+- Add `/ollama-usage-status [on|off|enable|disable]` to toggle the footer usage status bar at runtime (toggles without an argument).
+- Document the exported usage API (`fetchUsage`, `formatUsageStatusColored`, `getCloudApiKey`, validators) so custom status bars can reuse it.
+
+## [0.8.0] - 2026-08-09
+
+- **Breaking:** Migrate model refresh to pi's native `refreshModels` mechanism. Remove the `/ollama-cloud-refresh` command and the manual `~/.pi/agent/cache/ollama-cloud-models.json` cache. The catalog now refreshes automatically on startup, on `/model` open, and via `pi update --models`, persisted through pi's own `FileModelsStore`. Users should delete the orphaned cache file after upgrade: `rm ~/.pi/agent/cache/ollama-cloud-models.json`.
+- The shipped `GENERATED_MODELS` list is now a first-launch fallback; releases are no longer required for model freshness (only for deprecation or pricing changes).
+- Refresh the generated catalog from the live API: add `deepseek-v4-flash:0731`, `deepseek-v4-flash:preview`, and `kimi-k3`; remove `kimi-k2.5` and `minimax-m2.5`, which are no longer listed. Refresh models.dev pricing, including the new models. Thanks @noruthedev (#43).
+- Requires a pi version with the `stored`/`publish` `RefreshModelsContext` (pi 0.84.0+). Add `@earendil-works/pi-ai` as a peer dependency.
+- Web tools now throw on errors instead of returning an `isError` result, aligning with pi 0.84.0's `AgentToolResult` contract.
+- Fix `ollama_web_fetch` failing on pages where the API returns `links: null` (e.g. GitHub PR pages); the response is now accepted and rendered without a links list.
+- Refresh robustness: add a 4-hour cooldown so repeated `/model` opens don't re-fetch the catalog; on a partial refresh failure, keep the last-good catalog and surface the error instead of silently returning an incomplete list.
+- Add `tsgo --noEmit` type-checking to `npm run check` and CI.
+
+## [0.7.0] - 2026-07-18
 
 - Fix extension crash on pi 0.80.8+ where `AuthStorage` is no longer exported by `@earendil-works/pi-coding-agent`. Web tools now resolve the API key through the tool execution context's `modelRegistry.getApiKeyForProvider()`, preserving runtime/CLI overrides and the registered `apiKey: "$OLLAMA_API_KEY"` config. Thanks @badlogic for the cross-version analysis (#34, #35, #37).
 - Restore the `OLLAMA_API_KEY` env-var fallback in `ollama_web_search` and `ollama_web_fetch`. Thanks @cawilliamson (#26).

package/README.md

@@ -8,10 +8,8 @@ Registers Ollama Cloud as a model provider with dynamically fetched models, and
 
 - **Dynamic model discovery** - Fetches the full model list from `ollama.com/v1/models`, then fetches per-model details via `/api/show` to determine capabilities, context length, and tool support.
 - **Curated thinking levels** - Maps Pi's thinking levels to Ollama Cloud's OpenAI-compatible `reasoning_effort` values via `thinking-levels.ts`, with per-model exceptions based on API testing.
-- **Baked-in model list** - A generated model list (`models.generated.ts`) ships with the extension so models are available immediately on first launch without any network calls. Updated by running `npm run generate-models` and releasing a new version.
-- **Persistent cache** - Running `/ollama-cloud-refresh` fetches the latest models from the API and caches them to `~/.pi/agent/cache/ollama-cloud-models.json`. On subsequent launches, this disk cache takes precedence over the baked-in list.
-- **Auto-refresh on stale cache** - When the disk cache is older than 30 days, the extension uses it immediately and shows a visible refresh progress widget on the next `session_start` to pull in any new models.
-- **`/ollama-cloud-refresh` command** - Re-fetches the model list and updates the cache and provider registration live (no restart needed).
+- **Baked-in model list** - A generated fallback list (`models.generated.ts`) ships with the extension so models are available on first launch without any network calls. It is only a fallback: pi refreshes the live catalog at runtime, so shipping a new release for catalog freshness is no longer needed.
+- **Automatic model refresh** - On startup, `/model` open, and `pi update --models`, pi calls the extension's `refreshModels` callback to fetch the latest models from the API and persists them through pi's own model store. No manual refresh command.
 - **`ollama_web_search` tool** - Search the web for real-time information using Ollama Cloud's `/api/web_search` endpoint. Returns titles, URLs, and content snippets.
 - **`ollama_web_fetch` tool** - Fetch and extract text content from a web page URL using Ollama Cloud's `/api/web_fetch` endpoint. Returns page title, content, and links.
 - **Estimated cost tracking** - Models are registered with estimated per-token costs sourced from [models.dev](https://models.dev) (the same catalog pi uses), so Pi's `/cost` shows comparable usage. Ollama Cloud is subscription-billed (Free, Pro, Max), so these are equivalent pay-as-you-go estimates, not actual charges. See [ollama.com/pricing](https://ollama.com/pricing) for plan details.
@@ -99,30 +97,20 @@ Extension settings can be set via JSON config files. Project-local settings over
 | Setting | Type | Default | Description |
 |---|---|---|---|
 | `webTools` | boolean | `true` | Set to `false` to prevent `ollama_web_search` and `ollama_web_fetch` from being registered |
+| `usageStatus` | boolean | `false` | Set to `true` to show the footer usage status bar (opt-in; enable at runtime with `/ollama-usage-status`) |
 
 Example `ollama-cloud.json`:
 
 ```json
 {
-  "webTools": false
+  "webTools": false,
+  "usageStatus": true
 }
 ```
 
 The `PI_OLLAMA_WEB_TOOLS` environment variable still works as an override above config files. Set it to `0`, `false`, `no`, or `off` to disable web tools regardless of config file settings.
 
-### 4. Fetch models (optional)
-
-On first launch the plugin uses a baked-in model list shipped with the extension — no network calls needed. If you want the very latest models, run `/ollama-cloud-refresh` to fetch from the API and cache the result to disk. After that, the disk cache is used on subsequent launches.
-
-If the disk cache is older than 30 days, the extension uses it immediately and runs a visible refresh on the next session start (progress appears in the UI widget). You can also run:
-
-```
-/ollama-cloud-refresh
-```
-
-This fetches the full model list from the Ollama Cloud API and overwrites the local cache.
-
-### 5. Select a model
+### 4. Select a model
 
 Use `/model` or `Ctrl+L` to switch to an Ollama Cloud model. Models appear under the `ollama-cloud` provider.
 
@@ -135,9 +123,11 @@ The plugin uses two Ollama Cloud API endpoints to build the model list:
 
 Only models with the `tools` capability are registered - these are the ones Pi can use for tool-calling.
 
-The raw `/api/show` responses are cached at `~/.pi/agent/cache/ollama-cloud-models.json` with a top-level `timestamp` value. If that local cache is older than 30 days, the plugin keeps using it immediately and runs a visible refresh on `session_start` (progress appears in the UI widget). If the cache is missing, the plugin uses the baked-in model list shipped with the extension (`models.generated.ts`).
+The model list refreshes automatically: pi calls the extension's `refreshModels` callback on startup, when `/model` opens, and on `pi update --models`, fetching the live catalog and persisting it through pi's own model store. A model removed from the Ollama Cloud API disappears after the next successful refresh. The baked-in `models.generated.ts` list (regenerated via `npm run generate-models`) is only a first-launch fallback when no persisted catalog exists yet.
+
+The model fetch itself is keyless (the `/v1/models` and `/api/show` endpoints are public), but pi only runs the live refresh when a credential resolves, so a user without a configured API key stays on the baked-in list until they add one. That is a non-issue in practice because a credentialless user cannot run models anyway.
 
-Model metadata is derived from the cached data:
+Model metadata is derived from the `/api/show` response:
 
 | Field | Source |
 |---|---|
@@ -146,7 +136,7 @@ Model metadata is derived from the cached data:
 | `input` | `["text", "image"]` if `capabilities` includes `"vision"`, else `["text"]` |
 | `contextWindow` | `model_info.*.context_length` (falls back to 128000) |
 | `maxTokens` | Fixed at 32768 |
-| `cost` | Estimated per-1M-token prices from [models.dev](https://models.dev), generated by `scripts/generate-pricing.ts` into `pricing.generated.ts`. Ollama Cloud is subscription-billed, so these are equivalent pay-as-you-go estimates, not actual charges. Unmapped models default to zero. Prices are pinned to the installed package version: `/ollama-cloud-refresh` updates the model list and metadata but does not re-fetch prices, so newly added models register with zero cost until the next release. |
+| `cost` | Estimated per-1M-token prices from [models.dev](https://models.dev), generated by `scripts/generate-pricing.ts` into `pricing.generated.ts`. Ollama Cloud is subscription-billed, so these are equivalent pay-as-you-go estimates, not actual charges. Unmapped models default to zero. Prices are pinned to the installed package version and only update on a new release, so newly added models register with zero cost until then. |
 
 ### Thinking level mapping
 
@@ -162,14 +152,6 @@ Pi's thinking levels are mapped to Ollama Cloud's OpenAI-compatible `reasoning_e
 
 See [docs/think-experiment.md](docs/think-experiment.md) for the testing methodology and results.
 
-Refresh from inside Pi:
-
-```text
-/ollama-cloud-refresh
-```
-
-That command updates `~/.pi/agent/cache/ollama-cloud-models.json` with a new `timestamp` and re-registers the provider live, so no restart is required.
-
 ## Tools
 
 | Tool | Description |
@@ -183,19 +165,100 @@ Both tools use the same Ollama Cloud API key configured for the provider. No loc
 
 | Command | Description |
 |---|---|
-| `/ollama-cloud-refresh` | Fetch models from the Ollama Cloud API, update cache, and re-register the provider. Updates the model list and metadata but not estimated prices (those are pinned to the installed package version). |
 | `/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 session (5h) and weekly (7d) usage limits, per-model request counts, and the 4-week activity cost. |
+| `/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 (`5h ▕███░░░░░░░▏ 34% 7d ▕████░░░░░░▏ 45%`) that refreshes
+every 5 minutes and after each agent turn (but no more often than every 5 minutes). Each segment 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.
+
+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
+bar never appears after enabling, run `/ollama-cloud-usage` to see the
+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.
+
+## Usage API for custom status bars
+
+The usage data plane is exported so you can plug it into your own footer or
+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 { 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. |
+| `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). |
+| `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. |
+
+Example custom status bar:
+
+```ts
+const apiKey = await getCloudApiKey(ctx);
+const data = await fetchUsage(apiKey);
+ctx.ui.setStatus("my-usage", formatUsageStatusColored(ctx.ui.theme, data));
+```
+
+Note that the package ships raw TypeScript sources (no build step), so submodule
+imports use the `.ts` extension, matching how the extension imports internally.
 
 ## Development
 
 ```bash
-npm install          # install devDependencies (biome)
-npm run check        # lint + format with auto-fix
-npm run lint        # lint only (no fixes)
-npm run format      # format only
+npm install          # install devDependencies
+npm run check        # lint + format + type-check (auto-fix)
+npm run lint         # lint only (no fixes)
+npm run typecheck    # type-check only (tsgo --noEmit)
+npm run format       # format only
+```
+
+The project uses [Biome](https://biomejs.dev/) for linting and formatting (2-space indent, line width 120) and [tsgo](https://github.com/microsoft/typescript-go) for type-checking.
+
+### Testing local changes
+
+Static checks (no API key needed):
+
+```bash
+npm install
+npm run check        # lint + format + type-check
+npm run test         # unit tests
+```
+
+Live smoke against the real API (needs an `OLLAMA_API_KEY` or an `ollama-cloud` entry in `auth.json`):
+
+```bash
+# Run pi with the local extension, no install required. The --no-* flags isolate
+# the run from other installed extensions, skills, prompt templates, themes,
+# context files, and session storage so only the local checkout is exercised
+pi --no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files --no-session \
+  -e ./index.ts --model "ollama-cloud/gemma4:31b" --no-tools -p "Say hi in one word"
+
+# Verify thinking is suppressed when off
+pi --no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files --no-session \
+  -e ./index.ts --thinking off --model "ollama-cloud/glm-5.2" --no-tools --mode json -p 'hi'
+
+# Web tools
+npm run smoke:web-tools
 ```
 
-The project uses [Biome](https://biomejs.dev/) for linting and formatting (2-space indent, line width 120).
+The `-e`/`--extension` flag loads the extension from the local checkout without installing it; `--no-extensions` disables all other extension discovery so the run cannot pick up an installed `pi-ollama-cloud` or other plugins. The same commands run in CI (`.github/workflows/test.yml`), gated on the `OLLAMA_CLOUD_API_KEY` secret.
 
 ## How is this different from `ollama launch pi`?
 
@@ -211,7 +274,7 @@ The project uses [Biome](https://biomejs.dev/) for linting and formatting (2-spa
 | **Authentication** | Handled by the local server (sign-in flow via `ollama`) | Ollama Cloud API key (set via `OLLAMA_API_KEY` or `auth.json`) |
 | **Model discovery** | Interactive picker with curated recommendations + pulled models | Dynamic - fetches all available cloud models with tool support from the API |
 | **Web tools** | Auto-installed (`@ollama/pi-web-search`) when cloud is enabled | ✅ Built-in: `ollama_web_search` and `ollama_web_fetch` use the [Ollama Cloud web search API](https://docs.ollama.com/capabilities/web-search) directly (same API key, no local server needed) |
-| **Setup effort** | One command: `ollama launch pi` | Install extension + API key + `/ollama-cloud-refresh` |
+| **Setup effort** | One command: `ollama launch pi` | Install extension + API key |
 | **Use when** | You're already running Ollama locally and want the default experience | You don't want to run a local server, or want a standalone cloud-only provider alongside your local setup |
 
 **You can use both at the same time.** The providers live under different names (`ollama` vs `ollama-cloud`), so you can switch between them with `/model` or `Ctrl+L`. For example, use your local `ollama` provider for low-latency work on smaller models, and `ollama-cloud` for direct access to the full catalog of cloud models without needing a local server.
@@ -229,6 +292,11 @@ npm version minor   # or patch, or major
 git push --tags
 ```
 
+Because the model catalog refreshes automatically at runtime, a release is **not** needed to ship new models. Publish only when:
+
+- A model is retired and still listed by the API: add it to `RETIRED_MODEL_IDS` in `scripts/generate-models.ts` (check https://docs.ollama.com/cloud#retirements, then regenerate `models.generated.ts`).
+- Pricing changes: models.dev prices updated, or a new model needs an `OLLAMA_TO_MODELSDEV` mapping line (regenerate `pricing.generated.ts`).
+
 The tag version must match the version in `package.json` - `npm version` handles this automatically. The workflow at `.github/workflows/publish.yml` verifies the match before publishing to npm.
 
 The workflow uses npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC) - no tokens stored as secrets. To set it up:
@@ -240,7 +308,15 @@ The workflow uses npm's [trusted publishing](https://docs.npmjs.com/trusted-publ
 
 Each publish also gets automatic [provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
 
+## Upgrading
+
+Since 0.8.0:
+
+- The `/ollama-cloud-refresh` command is removed. Models refresh automatically on startup, `/model` open, and `pi update --models`.
+- The old cache file at `~/.pi/agent/cache/ollama-cloud-models.json` is orphaned. Delete it manually: `rm ~/.pi/agent/cache/ollama-cloud-models.json`.
+- Requires a pi version with the native `refreshModels` API (pi 0.84.0+).
+
 ## Notes
 
-- The fetch timeout is 10 seconds per request. On slow connections, some model detail fetches may time out - the plugin reports how many succeeded vs failed.
+- The fetch timeout is 10 seconds per request. On slow connections, some model detail fetches may time out; the refresh uses whatever succeeded and only fails if every model detail fetch fails.
 - `deepseek-v4` occasionally emits raw `<｜DSML｜tool_calls｜>` markup as plain text instead of structured tool calls, then stops. This is DeepSeek's native tool-call format leaking through Ollama Cloud's OpenAI-compatible endpoint, so it looks like an upstream Ollama issue rather than something this extension can fix. If you hit it, retry or switch models.

package/config.ts

@@ -25,12 +25,15 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 export interface OllamaCloudConfig {
   /** When false, ollama_web_search and ollama_web_fetch tools are not registered. Default: true. */
   webTools?: boolean;
+  /** When true, the footer usage status bar is shown. Default: false (opt-in; enable with /ollama-usage-status). */
+  usageStatus?: boolean;
 }
 
 // --- Defaults ---
 
 const DEFAULT_CONFIG: OllamaCloudConfig = {
   webTools: true,
+  usageStatus: false,
 };
 
 // --- Validation ---
@@ -38,6 +41,7 @@ const DEFAULT_CONFIG: OllamaCloudConfig = {
 /** Allowed config keys and their expected types for runtime validation. */
 const CONFIG_SCHEMA: Record<keyof OllamaCloudConfig, "boolean"> = {
   webTools: "boolean",
+  usageStatus: "boolean",
 };
 
 /**

package/index.ts

@@ -1,144 +1,63 @@
 /**
  * Ollama Cloud Provider Extension
  *
- * Registers Ollama Cloud as a model provider with dynamically fetched models.
+ * Registers Ollama Cloud as a model provider with a baked-in fallback catalog
+ * and a native `refreshModels` callback that overlays live API updates.
  *
  * Setup:
  *   1. Get an API key from https://ollama.com
  *   2. Add to auth.json in the agent config dir (~/.pi/agent/auth.json, or set PI_CODING_AGENT_DIR):
  *      { "ollama-cloud": { "type": "api_key", "key": "your-key" } }
- *   3. Run /ollama-cloud-refresh to fetch model metadata
- *   4. Use /model or ctrl+l to select an Ollama Cloud model
+ *   3. Use /model or ctrl+l to select an Ollama Cloud model
  *
  * Two endpoints are used to build the model list:
  *   - GET  https://ollama.com/v1/models  -> list of model IDs
  *   - POST https://ollama.com/api/show   -> per-model details (capabilities, context length)
  *
- * Raw /api/show responses are cached at <agentDir>/cache/ollama-cloud-models.json
- * so the provider assembly can be debugged and re-derived without re-fetching.
- *
- * Startup behavior:
- *   - Missing cache: uses baked-in GENERATED_MODELS (manually generated via
- *     `npm run generate-models` and committed to the repo).
- *   - Stale cache (>30 days): uses the cached data immediately and triggers a visible refresh
- *     on session_start that shows progress in the UI widget.
- *   - Fresh cache: uses cached data directly, no refresh triggered.
+ * Catalog behavior:
+ *   - The baked-in GENERATED_MODELS list (via `npm run generate-models`) is the
+ *     first-launch fallback when no persisted catalog exists.
+ *   - On startup, /model open, and `pi update --models`, pi calls the
+ *     `refreshModels` callback, which fetches the live catalog and persists it
+ *     through pi's own FileModelsStore. Refresh is automatic.
  *
  * Only models with "tools" capability are registered.
  */
 
-import type { ExtensionAPI, ExtensionCommandContext, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig, resolveWebToolsEnv } from "./config.ts";
 import { GENERATED_MODELS } from "./models.generated.ts";
-import {
-  assembleModels,
-  fetchModels,
-  OLLAMA_BASE,
-  type RefreshProgress,
-  readCacheState,
-  writeCache,
-} from "./models.ts";
+import { OLLAMA_BASE, refreshOllamaCatalog } from "./models.ts";
+import { fetchUsage, formatUsage, formatUsageStatusColored } from "./usage.ts";
+import { getCloudApiKey } from "./utils.ts";
 import { registerWebFetchTool, registerWebSearchTool } from "./web-tools.ts";
 
-// --- Registrations ---
-
-function registerProvider(pi: ExtensionAPI, models: ProviderModelConfig[]) {
-  pi.registerProvider("ollama-cloud", {
-    name: "Ollama Cloud",
-    baseUrl: `${OLLAMA_BASE}/v1`,
-    apiKey: "$OLLAMA_API_KEY",
-    api: "openai-completions",
-    models,
-  });
-}
-
-function renderProgressBar(current: number, total: number, width = 15): string {
-  if (total <= 0) return `[${"░".repeat(width)}]`;
-  const ratio = Math.max(0, Math.min(1, current / total));
-  const filled = Math.round(ratio * width);
-  return `[${"█".repeat(filled)}${"░".repeat(width - filled)}]`;
-}
-
-function createRefreshProgressUi(ctx: Pick<ExtensionCommandContext, "ui">) {
-  const key = "ollama-cloud-refresh";
+/**
+ * Resolve the new enabled state for /ollama-usage-status from its argument.
+ * Exported for unit testing.
+ */
+export function resolveUsageStatusToggle(arg: string, current: boolean): { enabled: boolean; error?: string } {
+  const a = arg.trim().toLowerCase();
+  if (a === "on" || a === "enable") return { enabled: true };
+  if (a === "off" || a === "disable") return { enabled: false };
+  if (a === "") return { enabled: !current };
   return {
-    update(progress: RefreshProgress) {
-      const current = progress.current ?? 0;
-      const total = progress.total ?? 0;
-      const percent = total > 0 ? Math.round((current / total) * 100) : 0;
-      const failed = progress.failed ? `, ${progress.failed} failed` : "";
-      const stage =
-        progress.stage === "list"
-          ? "Discovering models"
-          : progress.stage === "details"
-            ? "Fetching model details"
-            : "Done";
-      const summary = total > 0 ? `${current}/${total} (${percent}%${failed})` : progress.message;
-      const line = `☁ Ollama Cloud - ${stage} — ${summary} ${renderProgressBar(current, total)}`;
-
-      ctx.ui.setWorkingMessage(`Refreshing Ollama Cloud models - ${stage.toLowerCase()}`);
-      ctx.ui.setWidget(key, [line], { placement: "belowEditor" });
-    },
-    clear() {
-      ctx.ui.setWidget(key, undefined);
-      ctx.ui.setStatus(key, undefined);
-      ctx.ui.setWorkingMessage();
-    },
+    enabled: current,
+    error: `Unknown argument "${arg.trim()}". Usage: /ollama-usage-status [on|off|enable|disable]`,
   };
 }
 
-async function runRefresh(pi: ExtensionAPI, ctx: Pick<ExtensionCommandContext, "ui">) {
-  const progressUi = createRefreshProgressUi(ctx);
-  try {
-    progressUi.update({ stage: "list", message: "Starting refresh..." });
-
-    const raw = await fetchModels(ctx, (progress) => progressUi.update(progress));
-    if (!raw) return false;
-
-    writeCache(raw);
-    const newModels = assembleModels(raw);
-
-    registerProvider(pi, newModels);
-
-    ctx.ui.notify(`Registered ${newModels.length} Ollama Cloud models`, "info");
-    return true;
-  } finally {
-    progressUi.clear();
-  }
-}
-
-function registerRefreshCommand(pi: ExtensionAPI) {
-  pi.registerCommand("ollama-cloud-refresh", {
-    description: "Refresh Ollama Cloud models from the API",
-    handler: async (_args: string, ctx: ExtensionCommandContext) => {
-      await runRefresh(pi, ctx);
-    },
-  });
-}
-
 // --- Main ---
 
 export default async function (pi: ExtensionAPI) {
-  const cacheState = readCacheState();
-  // Auto-refresh only when the disk cache is stale (>30 days).
-  // When cache is missing, GENERATED_MODELS serves as the cache —
-  // it is manually generated via `npm run generate-models` and committed to the repo.
-  const needsStartupRefresh = cacheState.status === "stale";
-  // GENERATED_MODELS ships with the package. Used when no local cache exists. A
-  // fresh user cache from /ollama-cloud-refresh takes precedence over the generated list.
-  const models = cacheState.status === "missing" ? GENERATED_MODELS : assembleModels(cacheState.models);
-
-  registerProvider(pi, models);
-  registerRefreshCommand(pi);
-
-  if (needsStartupRefresh) {
-    let started = false;
-    pi.on("session_start", async (_event, ctx) => {
-      if (started) return;
-      started = true;
-      await runRefresh(pi, ctx);
-    });
-  }
+  pi.registerProvider("ollama-cloud", {
+    name: "Ollama Cloud",
+    baseUrl: `${OLLAMA_BASE}/v1`,
+    apiKey: "$OLLAMA_API_KEY",
+    api: "openai-completions",
+    models: GENERATED_MODELS,
+    refreshModels: refreshOllamaCatalog,
+  });
 
   // --- Web Tools Management ---
 
@@ -180,21 +99,25 @@ export default async function (pi: ExtensionAPI) {
     }
   }
 
-  // Module-level tracking across session restarts within the same extension
-  // instance. The config file is read once, on the first session_start;
-  // later sessions reuse webToolsEnabled (including any /ollama-webtools
-  // override). Restart pi or /reload to pick up config file changes.
-  let webToolsConfigured = false;
+  // Config is read once per extension factory invocation (on the first
+  // session_start). The factory is re-invoked on /new, /fork, /resume, and
+  // /reload, so runtime toggles (e.g. /ollama-webtools, /ollama-usage-status)
+  // reset to the config default on each session restart. Restart pi or /reload
+  // to pick up config file changes.
+  let configLoaded = false;
   let webToolsEnabled = false;
+  let usageStatusEnabled = false;
 
   pi.on("session_start", async (_event, ctx) => {
-    if (!webToolsConfigured) {
-      webToolsConfigured = true;
+    if (!configLoaded) {
+      configLoaded = true;
       const config = loadConfig(ctx.cwd);
       if (config.webTools !== false) {
         webToolsEnabled = true;
         ensureWebToolsRegistered();
       }
+      // The status bar is opt-in: enabled only when the config explicitly sets it true.
+      usageStatusEnabled = config.usageStatus === true;
     }
     // On every session start (including resume/fork/new), re-apply the
     // runtime state. Tools may have been unregistered during teardown.
@@ -202,6 +125,126 @@ export default async function (pi: ExtensionAPI) {
       ensureWebToolsRegistered();
       setWebToolsActive(true);
     }
+    // Start the usage status bar when ollama-cloud is the active provider.
+    if (usageStatusEnabled && isOllamaCloud(ctx)) {
+      startUsageStatus(ctx);
+    }
+  });
+
+  // --- Usage Command ---
+
+  pi.registerCommand("ollama-cloud-usage", {
+    description: "Show Ollama Cloud session and weekly usage limits.",
+    handler: async (_args, ctx) => {
+      const apiKey = await getCloudApiKey(ctx);
+      if (!apiKey) {
+        ctx.ui.notify("No Ollama Cloud API key configured. Set OLLAMA_API_KEY or add to auth.json.", "error");
+        return;
+      }
+      try {
+        const data = await fetchUsage(apiKey);
+        ctx.ui.notify(formatUsage(data), "info");
+      } catch (err) {
+        ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      }
+    },
+  });
+
+  // --- Usage Status Bar ---
+
+  // Footer status showing live session/weekly usage 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
+  // @entelligentsia/pi-ollama-cloud-usage-tracker.
+  const USAGE_STATUS_KEY = "ollama-usage";
+  const USAGE_REFRESH_MS = 5 * 60_000;
+  let usageTimer: ReturnType<typeof setInterval> | null = null;
+  let usageActive = false;
+  // Timestamp (ms) of the most recent refresh attempt; gates the agent_end
+  // refresh so it fires at most once per cooldown. Set when a fetch starts, so
+  // a failing endpoint is also throttled, not just a successful one.
+  let lastRefreshAt = 0;
+
+  async function refreshUsageStatus(ctx: ExtensionContext) {
+    try {
+      const apiKey = await getCloudApiKey(ctx);
+      if (!apiKey) {
+        ctx.ui.setStatus(USAGE_STATUS_KEY, undefined);
+        return;
+      }
+      lastRefreshAt = Date.now();
+      const data = await fetchUsage(apiKey);
+      ctx.ui.setStatus(USAGE_STATUS_KEY, formatUsageStatusColored(ctx.ui.theme, data));
+    } catch {
+      // Transient errors (undocumented endpoint, network) should not spam the
+      // footer; clear the status and retry on the next refresh.
+      ctx.ui.setStatus(USAGE_STATUS_KEY, undefined);
+    }
+  }
+
+  function startUsageStatus(ctx: ExtensionContext) {
+    if (usageActive) return;
+    // The status bar is TUI-only; skip the fetch and timer in print/json/rpc.
+    if (ctx.mode !== "tui") return;
+    usageActive = true;
+    refreshUsageStatus(ctx);
+    usageTimer = setInterval(() => refreshUsageStatus(ctx), USAGE_REFRESH_MS);
+  }
+
+  function stopUsageStatus(ctx: ExtensionContext) {
+    usageActive = false;
+    if (usageTimer) {
+      clearInterval(usageTimer);
+      usageTimer = null;
+    }
+    ctx.ui.setStatus(USAGE_STATUS_KEY, undefined);
+  }
+
+  function isOllamaCloud(ctx: ExtensionContext): boolean {
+    return ctx.model?.provider === "ollama-cloud";
+  }
+
+  pi.on("model_select", async (_event, ctx) => {
+    if (usageStatusEnabled && isOllamaCloud(ctx)) {
+      startUsageStatus(ctx);
+    } else {
+      stopUsageStatus(ctx);
+    }
+  });
+
+  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.
+    if (usageActive && isOllamaCloud(ctx) && Date.now() - lastRefreshAt >= USAGE_REFRESH_MS) {
+      await refreshUsageStatus(ctx);
+    }
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    stopUsageStatus(ctx);
+  });
+
+  pi.registerCommand("ollama-usage-status", {
+    description:
+      "Enable or disable the Ollama Cloud usage status bar. " +
+      "Accepts optional argument: on/off/enable/disable. Without argument, toggles.",
+    handler: async (args, ctx) => {
+      const { enabled, error } = resolveUsageStatusToggle(args, usageStatusEnabled);
+      if (error) {
+        ctx.ui.notify(error, "error");
+        return;
+      }
+      usageStatusEnabled = enabled;
+
+      if (usageStatusEnabled && isOllamaCloud(ctx)) {
+        startUsageStatus(ctx);
+      } else {
+        stopUsageStatus(ctx);
+      }
+
+      ctx.ui.notify(`Ollama Cloud usage status: ${usageStatusEnabled ? "enabled" : "disabled"}`, "info");
+    },
   });
 
   // Only register the runtime toggle command when the env var doesn't force tools off.