pi-ollama-cloud 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [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.
@@ -110,19 +108,7 @@ Example `ollama-cloud.json`:
 
 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 +121,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.
 
-Model metadata is derived from the cached data:
+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 `/api/show` response:
 
 | Field | Source |
 |---|---|
@@ -146,7 +134,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 +150,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 +163,48 @@ 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. |
 
 ## 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).
+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 `-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 +220,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 +238,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 +254,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/index.ts

@@ -1,144 +1,46 @@
 /**
  * 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 } 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 { registerWebFetchTool, registerWebSearchTool } from "./web-tools.ts";
 
-// --- Registrations ---
+// --- Main ---
 
-function registerProvider(pi: ExtensionAPI, models: ProviderModelConfig[]) {
+export default async function (pi: ExtensionAPI) {
   pi.registerProvider("ollama-cloud", {
     name: "Ollama Cloud",
     baseUrl: `${OLLAMA_BASE}/v1`,
     apiKey: "$OLLAMA_API_KEY",
     api: "openai-completions",
-    models,
+    models: GENERATED_MODELS,
+    refreshModels: refreshOllamaCatalog,
   });
-}
-
-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";
-  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();
-    },
-  };
-}
-
-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);
-    });
-  }
 
   // --- Web Tools Management ---
 

package/models.generated.ts

@@ -1,14 +1,54 @@
 // Auto-generated by scripts/generate-models.ts
 // Do not edit manually.
-// Generated: 2026-07-17T19:55:27.551Z
+// Generated: 2026-08-08T04:19:46.959Z
 // Model count: 18
 
 import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 
 export const GENERATED_MODELS: ProviderModelConfig[] = [
   {
-    id: "deepseek-v4-flash",
-    name: "deepseek-v4-flash",
+    id: "deepseek-v4-flash:0731",
+    name: "deepseek-v4-flash:0731",
+    compat: {
+      maxTokensField: "max_tokens",
+      openRouterRouting: {},
+      requiresAssistantAfterToolResult: false,
+      requiresReasoningContentOnAssistantMessages: false,
+      requiresThinkingAsText: false,
+      requiresToolResultName: false,
+      sendSessionAffinityHeaders: false,
+      supportsDeveloperRole: false,
+      supportsLongCacheRetention: false,
+      supportsReasoningEffort: true,
+      supportsStore: false,
+      supportsStrictMode: false,
+      supportsUsageInStreaming: true,
+      thinkingFormat: "openai",
+      vercelGatewayRouting: {},
+      zaiToolStream: false,
+    },
+    contextWindow: 1048576,
+    cost: {
+      cacheRead: 0.0028,
+      cacheWrite: 0,
+      input: 0.14,
+      output: 0.28,
+    },
+    input: ["text"],
+    maxTokens: 32768,
+    reasoning: true,
+    thinkingLevelMap: {
+      high: "high",
+      low: "low",
+      medium: "medium",
+      minimal: null,
+      off: "none",
+      xhigh: "max",
+    },
+  },
+  {
+    id: "deepseek-v4-flash:preview",
+    name: "deepseek-v4-flash:preview",
     compat: {
       maxTokensField: "max_tokens",
       openRouterRouting: {},
@@ -109,10 +149,10 @@ export const GENERATED_MODELS: ProviderModelConfig[] = [
     },
     contextWindow: 262144,
     cost: {
-      cacheRead: 0.12,
+      cacheRead: 0.1,
       cacheWrite: 0,
-      input: 0.22,
-      output: 0.55,
+      input: 0.1,
+      output: 0.34,
     },
     input: ["text", "image"],
     maxTokens: 32768,
@@ -286,46 +326,6 @@ export const GENERATED_MODELS: ProviderModelConfig[] = [
       xhigh: null,
     },
   },
-  {
-    id: "kimi-k2.5",
-    name: "kimi-k2.5",
-    compat: {
-      maxTokensField: "max_tokens",
-      openRouterRouting: {},
-      requiresAssistantAfterToolResult: false,
-      requiresReasoningContentOnAssistantMessages: false,
-      requiresThinkingAsText: false,
-      requiresToolResultName: false,
-      sendSessionAffinityHeaders: false,
-      supportsDeveloperRole: false,
-      supportsLongCacheRetention: false,
-      supportsReasoningEffort: true,
-      supportsStore: false,
-      supportsStrictMode: false,
-      supportsUsageInStreaming: true,
-      thinkingFormat: "openai",
-      vercelGatewayRouting: {},
-      zaiToolStream: false,
-    },
-    contextWindow: 262144,
-    cost: {
-      cacheRead: 0.1,
-      cacheWrite: 0,
-      input: 0.6,
-      output: 3,
-    },
-    input: ["text", "image"],
-    maxTokens: 32768,
-    reasoning: true,
-    thinkingLevelMap: {
-      high: "high",
-      low: "low",
-      medium: "medium",
-      minimal: null,
-      off: "none",
-      xhigh: "max",
-    },
-  },
   {
     id: "kimi-k2.6",
     name: "kimi-k2.6",
@@ -407,8 +407,8 @@ export const GENERATED_MODELS: ProviderModelConfig[] = [
     },
   },
   {
-    id: "minimax-m2.5",
-    name: "minimax-m2.5",
+    id: "kimi-k3",
+    name: "kimi-k3",
     compat: {
       maxTokensField: "max_tokens",
       openRouterRouting: {},
@@ -427,14 +427,14 @@ export const GENERATED_MODELS: ProviderModelConfig[] = [
       vercelGatewayRouting: {},
       zaiToolStream: false,
     },
-    contextWindow: 196608,
+    contextWindow: 1048576,
     cost: {
-      cacheRead: 0.03,
-      cacheWrite: 0.375,
-      input: 0.3,
-      output: 1.2,
+      cacheRead: 0.3,
+      cacheWrite: 0,
+      input: 3,
+      output: 15,
     },
-    input: ["text"],
+    input: ["text", "image"],
     maxTokens: 32768,
     reasoning: true,
     thinkingLevelMap: {
@@ -442,7 +442,7 @@ export const GENERATED_MODELS: ProviderModelConfig[] = [
       low: "low",
       medium: "medium",
       minimal: null,
-      off: null,
+      off: "none",
       xhigh: "max",
     },
   },
@@ -581,7 +581,7 @@ export const GENERATED_MODELS: ProviderModelConfig[] = [
     },
     contextWindow: 262144,
     cost: {
-      cacheRead: 0,
+      cacheRead: 0.03,
       cacheWrite: 0,
       input: 0.05,
       output: 0.2,

package/models.ts

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { type ExtensionCommandContext, getAgentDir, type ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { GENERATED_MODELS } from "./models.generated.ts";
 import { MODEL_PRICING, type ModelPrice } from "./pricing.generated.ts";
 import { resolve as resolveThinkingLevelMap } from "./thinking-levels.ts";
 import { concurrentMap, fetchJsonWithTimeout, getContextLength } from "./utils.ts";
@@ -18,10 +18,10 @@ function resolvePrice(id: string): ModelPrice {
 }
 
 // --- Constants ---
-const CACHE_DIR = join(getAgentDir(), "cache");
-const CACHE_FILE = join(CACHE_DIR, "ollama-cloud-models.json");
-const CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 10000;
+// How long a stored catalog is considered fresh before the next network refresh
+// (mirrors pi-mono's REMOTE_CATALOG_REFRESH_INTERVAL_MS in remote-catalog-provider.ts).
+const REFRESH_COOLDOWN_MS = 4 * 60 * 60 * 1000;
 
 // The cloud extension always targets ollama.com; local Ollama daemons (typically
 // pointed at via OLLAMA_API_BASE for the local CLI) are a different product and
@@ -67,25 +67,6 @@ interface OllamaShowResponse {
   modified_at: string;
 }
 
-type CachedOllamaModel = OllamaShowResponse;
-
-/** On-disk cache: raw /api/show responses keyed by model ID. */
-interface CachedData {
-  /** Unix epoch milliseconds used to decide when the generated metadata is stale. */
-  timestamp?: number;
-  models: Record<string, CachedOllamaModel>;
-}
-
-type RefreshProgressStage = "list" | "details" | "done";
-
-export interface RefreshProgress {
-  stage: RefreshProgressStage;
-  current?: number;
-  total?: number;
-  failed?: number;
-  message: string;
-}
-
 // --- Assembly: raw API data -> ProviderModelConfig[] ---
 
 /**
@@ -135,7 +116,7 @@ function buildCompat(): ProviderModelConfig["compat"] {
   };
 }
 
-export function assembleModels(raw: Record<string, CachedOllamaModel>): ProviderModelConfig[] {
+export function assembleModels(raw: Record<string, OllamaShowResponse>): ProviderModelConfig[] {
   return Object.entries(raw)
     .filter(([, data]) => data.capabilities?.includes("tools"))
     .map(([id, data]) => ({
@@ -153,60 +134,8 @@ export function assembleModels(raw: Record<string, CachedOllamaModel>): Provider
     }));
 }
 
-// --- Cache I/O ---
-type CacheState =
-  | { status: "fresh"; models: Record<string, CachedOllamaModel> }
-  | { status: "stale"; models: Record<string, CachedOllamaModel> }
-  | { status: "missing" };
-
-function createCacheData(models: Record<string, CachedOllamaModel>, now = new Date()): CachedData {
-  return { timestamp: now.getTime(), models };
-}
-
-function readCacheData(path: string): CachedData | null {
-  try {
-    const data: CachedData = JSON.parse(readFileSync(path, "utf-8"));
-    if (!data.models || Object.keys(data.models).length === 0) return null;
-    return data;
-  } catch {
-    return null;
-  }
-}
-
-function isFreshGeneratedCache(data: CachedData): boolean {
-  if (typeof data.timestamp !== "number" || !Number.isFinite(data.timestamp)) return false;
-  return Date.now() - data.timestamp <= CACHE_MAX_AGE_MS;
-}
-
-export function readCacheState(): CacheState {
-  if (!existsSync(CACHE_FILE)) return { status: "missing" };
-
-  const data = readCacheData(CACHE_FILE);
-  if (!data) {
-    try {
-      rmSync(CACHE_FILE, { force: true });
-    } catch {
-      // Ignore cache delete errors.
-    }
-    return { status: "missing" };
-  }
-
-  return isFreshGeneratedCache(data)
-    ? { status: "fresh", models: data.models }
-    : { status: "stale", models: data.models };
-}
-
-export function writeCache(models: Record<string, CachedOllamaModel>): void {
-  try {
-    mkdirSync(CACHE_DIR, { recursive: true });
-    writeFileSync(CACHE_FILE, JSON.stringify(createCacheData(models), null, 2));
-  } catch {
-    // Ignore cache write errors
-  }
-}
-
 // --- Fetch Models ---
-export async function fetchModelIds(timeoutMs = FETCH_TIMEOUT_MS): Promise<string[]> {
+export async function fetchModelIds(signal?: AbortSignal, timeoutMs = FETCH_TIMEOUT_MS): Promise<string[]> {
   const headers: Record<string, string> = {};
   const apiKey = process.env.OLLAMA_API_KEY;
   if (apiKey) {
@@ -217,10 +146,11 @@ export async function fetchModelIds(timeoutMs = FETCH_TIMEOUT_MS): Promise<strin
     `${OLLAMA_BASE}/v1/models`,
     { headers },
     timeoutMs,
+    signal,
   );
 
   if (res.status === 429) {
-    throw new Error("Ollama Cloud rate limited. Try again shortly.");
+    throw new Error("Ollama Cloud model list fetch rate limited. Try again shortly.");
   }
   if (!res.ok || !res.data) {
     throw new Error(`Failed to fetch model list: ${res.status}${res.error ? ` - ${res.error}` : ""}`);
@@ -229,7 +159,11 @@ export async function fetchModelIds(timeoutMs = FETCH_TIMEOUT_MS): Promise<strin
   return res.data.data.map((m) => m.id);
 }
 
-export async function fetchModelDetails(id: string, timeoutMs = FETCH_TIMEOUT_MS): Promise<CachedOllamaModel> {
+export async function fetchModelDetails(
+  id: string,
+  signal?: AbortSignal,
+  timeoutMs = FETCH_TIMEOUT_MS,
+): Promise<OllamaShowResponse> {
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   const apiKey = process.env.OLLAMA_API_KEY;
   if (apiKey) {
@@ -244,10 +178,11 @@ export async function fetchModelDetails(id: string, timeoutMs = FETCH_TIMEOUT_MS
       body: JSON.stringify({ model: id }),
     },
     timeoutMs,
+    signal,
   );
 
   if (res.status === 429) {
-    throw new Error("Ollama Cloud rate limited. Try again shortly.");
+    throw new Error("Ollama Cloud /api/show rate limited. Try again shortly.");
   }
   if (!res.ok || !res.data) {
     throw new Error(`Failed to fetch /api/show for ${id}: ${res.status}${res.error ? ` - ${res.error}` : ""}`);
@@ -256,69 +191,161 @@ export async function fetchModelDetails(id: string, timeoutMs = FETCH_TIMEOUT_MS
   return res.data;
 }
 
-export async function refreshOllamaCloudModels(params: {
-  notify?: (message: string, level?: "info" | "error") => void;
-  onProgress?: (progress: RefreshProgress) => void;
-  workers?: number;
-}): Promise<Record<string, CachedOllamaModel>> {
-  const notify = params.notify ?? (() => undefined);
-  const onProgress = params.onProgress ?? (() => undefined);
-  onProgress({ stage: "list", message: "Fetching model list..." });
-  const modelIds = await fetchModelIds();
-  notify(`Found ${modelIds.length} models, fetching details...`);
-  onProgress({ stage: "details", current: 0, total: modelIds.length, failed: 0, message: "Fetching model details" });
-
-  let detailsDone = 0;
-  let detailsFailed = 0;
-  const detailResults = await concurrentMap(modelIds, params.workers ?? 8, async (id) => {
-    try {
-      return [id, await fetchModelDetails(id)] as const;
-    } catch (error) {
-      detailsFailed++;
-      throw error;
-    } finally {
-      detailsDone++;
-      onProgress({
-        stage: "details",
-        current: detailsDone,
-        total: modelIds.length,
-        failed: detailsFailed,
-        message: "Fetching model details",
-      });
-    }
+/**
+ * Fetch per-model /api/show details for a list of model IDs, 8 workers at a time.
+ * Returns the models that succeeded. Throws when every detail request fails
+ * (the zero-succeeded case), so the caller can surface a real failure instead
+ * of an empty catalog.
+ */
+export async function refreshOllamaCloudModels(
+  modelIds: string[],
+  signal?: AbortSignal,
+): Promise<{ models: Record<string, OllamaShowResponse>; failed: number }> {
+  const detailResults = await concurrentMap(modelIds, 8, async (id) => {
+    return [id, await fetchModelDetails(id, signal)] as const;
   });
-  const models: Record<string, CachedOllamaModel> = {};
+  const models: Record<string, OllamaShowResponse> = {};
+  let failed = 0;
   for (const result of detailResults) {
     if (result.status === "fulfilled") {
       const [id, data] = result.value;
       models[id] = data;
+    } else {
+      failed++;
     }
   }
-  const succeeded = Object.keys(models).length;
-  if (succeeded === 0)
-    throw new Error(`Failed to fetch model details${detailsFailed ? ` (${detailsFailed} failed)` : ""}`);
-  notify(`Fetched ${succeeded} model details${detailsFailed ? ` (${detailsFailed} failed)` : ""}`, "info");
-
-  onProgress({
-    stage: "done",
-    current: Object.keys(models).length,
-    total: Object.keys(models).length,
-    message: "Done",
-  });
-  return models;
+  if (Object.keys(models).length === 0) {
+    throw new Error(`Failed to fetch model details${failed ? ` (${failed} failed)` : ""}`);
+  }
+  return { models, failed };
 }
 
-export async function fetchModels(
-  ctx: Pick<ExtensionCommandContext, "ui">,
-  onProgress?: (progress: RefreshProgress) => void,
-): Promise<Record<string, CachedOllamaModel> | null> {
+// --- refreshModels callback ---
+
+/**
+ * The `refreshModels` callback pi invokes for the "ollama-cloud" provider.
+ * Pi calls it twice per refresh: a restore phase (`allowNetwork: false`) before
+ * auth resolution, then a network phase (`allowNetwork: true`) only when a
+ * credential resolves. The composer swaps the return value into the model list
+ * on every invocation, so this must never return `[]`.
+ *
+ * The model fetch itself is keyless (public `/v1/models` and `/api/show`
+ * endpoints; `Authorization` is only added when `OLLAMA_API_KEY` is set). But
+ * pi only invokes this network phase when a credential resolves, so a
+ * credentialless user stays on `GENERATED_MODELS` until they configure a key.
+ * That is a non-issue in practice because a credentialless user cannot run
+ * models anyway.
+ */
+export async function refreshOllamaCatalog(context: RefreshModelsContext): Promise<ProviderModelConfig[]> {
+  // The fallback list: the persisted snapshot (copied) when non-empty, else the
+  // baked-in list. Guards against a stored empty catalog (e.g. a prior bad
+  // refresh) propagating [] across sessions. A mutable copy is returned because
+  // the stored list is `readonly` and the return type is a mutable array.
+  const fallback = context.stored?.models.length ? [...context.stored.models] : GENERATED_MODELS;
+
+  // Restore phase. Rehydrate from the persisted snapshot so removals stick
+  // across sessions; fall back to the baked-in list on first launch. Also the
+  // early-out for an already-aborted signal.
+  if (!context.allowNetwork || context.signal.aborted) {
+    return fallback;
+  }
+
+  // Cooldown: skip the network fetch when the stored catalog was checked within
+  // the freshness window and the refresh isn't forced (mirrors pi-mono's
+  // remote-catalog-provider). A forced refresh (pi update --models) always fetches.
+  if (
+    !context.force &&
+    context.stored?.checkedAt !== undefined &&
+    Date.now() - context.stored.checkedAt < REFRESH_COOLDOWN_MS
+  ) {
+    return fallback;
+  }
+
+  // Network phase. The /v1/models and /api/show endpoints are publicly
+  // accessible and do not require authentication, so context.credential is
+  // intentionally not threaded into fetchModelIds/fetchModelDetails. Only
+  // the web tools (search, fetch) require an API key.
+  //
+  // Pi's model-selector aborts a catalog refresh after 15s
+  // (packages/coding-agent/src/modes/interactive/components/model-selector.ts
+  // in pi-mono), so a cold refresh must stay under that budget or the in-memory
+  // list won't update on the first picker-open. With ~18 models and 8 workers
+  // this is ~1s today; revisit if the catalog grows or the API slows.
+  let modelIds: string[];
+  let raw: Record<string, OllamaShowResponse>;
+  let failed = 0;
   try {
-    return await refreshOllamaCloudModels({
-      notify: (message, level) => ctx.ui.notify(message, level),
-      onProgress,
-    });
+    modelIds = await fetchModelIds(context.signal);
+    if (context.signal.aborted) {
+      return fallback;
+    }
+    const result = await refreshOllamaCloudModels(modelIds, context.signal);
+    raw = result.models;
+    failed = result.failed;
   } catch (error) {
-    ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
-    return null;
+    // Abort mid-flight returns the current baseline; any other error propagates
+    // and pi keeps the last good catalog (no publish was reached).
+    if (context.signal.aborted) {
+      return fallback;
+    }
+    throw error;
+  }
+  if (context.signal.aborted) {
+    return fallback;
+  }
+
+  const models = assembleModels(raw);
+  // Guard: an empty assembled list (e.g. the live API returned no tools-capable
+  // models) must not be persisted or swapped in, or it would kill the provider
+  // for the cooldown window. Keep the last good catalog instead.
+  if (models.length === 0) {
+    return fallback;
   }
+
+  // The store is typed to pi-ai's internal Model shape, so rehydrate the live
+  // list with the provider identity fields. A Model is structurally assignable
+  // to ProviderModelConfig, so the same list is returned to pi (the composer
+  // overrides provider/api/baseUrl on the in-memory swap regardless).
+  const persisted = models.map((model) => ({
+    ...model,
+    provider: "ollama-cloud",
+    api: "openai-completions",
+    baseUrl: `${OLLAMA_BASE}/v1`,
+  }));
+
+  // Best-effort persistence into pi's FileModelsStore. The in-memory list swap
+  // happens automatically from the return value, so a failed store write must
+  // not prevent returning the fresh catalog.
+  if (failed === 0) {
+    // Fully successful: persist the fresh catalog.
+    try {
+      const published = await context.publish({ persist: { models: persisted, checkedAt: Date.now() } });
+      if (!published) {
+        console.warn("[pi-ollama-cloud] Catalog persist rejected (generation check failed or refresh superseded).");
+      }
+    } catch {
+      // Persistence failure is non-fatal.
+    }
+  } else {
+    // Partial failure: keep the last-good catalog (if any) but advance checkedAt
+    // so the cooldown applies and a flaky catalog isn't re-fetched on every
+    // /model open, then surface the incomplete refresh. Mirrors pi-mono's
+    // remote-catalog-provider, which persists then throws on a transient failure;
+    // pi keeps the last-good catalog and reports the error.
+    if (context.stored?.models.length) {
+      try {
+        const published = await context.publish({ persist: { ...context.stored, checkedAt: Date.now() } });
+        if (!published) {
+          console.warn(
+            "[pi-ollama-cloud] Partial-failure persist rejected (generation check failed or refresh superseded).",
+          );
+        }
+      } catch {
+        // Persistence failure is non-fatal.
+      }
+    }
+    throw new Error(`Ollama Cloud catalog refresh incomplete: ${failed} model(s) failed`);
+  }
+
+  return persisted;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ollama-cloud",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -20,11 +20,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/fgrehm/pi-ollama-cloud"
+    "url": "git+https://github.com/fgrehm/pi-ollama-cloud.git"
   },
   "scripts": {
-    "check": "biome check --write .",
+    "check": "biome check --write . && tsgo --noEmit",
     "lint": "biome check .",
+    "typecheck": "tsgo --noEmit",
     "format": "biome format --write .",
     "test": "vitest run",
     "smoke:web-tools": "tsx scripts/smoke-web-tools.ts",
@@ -36,12 +37,15 @@
     ]
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "2",
+    "@types/node": "^26.1.2",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "tsx": "^4.19.0",
     "vitest": "^4.1.6"
   }

package/pricing.generated.ts

@@ -1,6 +1,6 @@
 // Auto-generated by scripts/generate-pricing.ts
 // Do not edit manually.
-// Generated: 2026-07-17T19:55:25.388Z
+// Generated: 2026-08-08T04:19:45.594Z
 // Model count: 18
 
 export interface ModelPrice {
@@ -11,21 +11,21 @@ export interface ModelPrice {
 }
 
 export const MODEL_PRICING: Record<string, ModelPrice> = {
-  "deepseek-v4-flash": { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+  "deepseek-v4-flash:0731": { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
+  "deepseek-v4-flash:preview": { input: 0.14, output: 0.28, cacheRead: 0.0028, cacheWrite: 0 },
   "deepseek-v4-pro": { input: 0.435, output: 0.87, cacheRead: 0.003625, cacheWrite: 0 },
-  "gemma4:31b": { input: 0.22, output: 0.55, cacheRead: 0.12, cacheWrite: 0 },
+  "gemma4:31b": { input: 0.1, output: 0.34, cacheRead: 0.1, cacheWrite: 0 },
   "glm-5.1": { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
   "glm-5.2": { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
   "gpt-oss:120b": { input: 0.037, output: 0.17, cacheRead: 0, cacheWrite: 0 },
   "gpt-oss:20b": { input: 0.03, output: 0.13, cacheRead: 0.03, cacheWrite: 0 },
-  "kimi-k2.5": { input: 0.6, output: 3, cacheRead: 0.1, cacheWrite: 0 },
   "kimi-k2.6": { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
   "kimi-k2.7-code": { input: 0.95, output: 4, cacheRead: 0.19, cacheWrite: 0 },
-  "minimax-m2.5": { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+  "kimi-k3": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 0 },
   "minimax-m2.7": { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
   "minimax-m3": { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
   "mistral-large-3:675b": { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
-  "nemotron-3-nano:30b": { input: 0.05, output: 0.2, cacheRead: 0, cacheWrite: 0 },
+  "nemotron-3-nano:30b": { input: 0.05, output: 0.2, cacheRead: 0.03, cacheWrite: 0 },
   "nemotron-3-super": { input: 0.2, output: 0.8, cacheRead: 0, cacheWrite: 0 },
   "nemotron-3-ultra": { input: 0.5, output: 2.5, cacheRead: 0.15, cacheWrite: 0 },
   "qwen3.5:397b": { input: 0.6, output: 3.6, cacheRead: 0, cacheWrite: 0 },

package/web-tools.ts

@@ -17,10 +17,12 @@
  */
 
 import {
+  type AgentToolResult,
   type ExtensionAPI,
   type ExtensionContext,
   keyHint,
   type Theme,
+  type ToolRenderResultOptions,
   truncateToVisualLines,
 } from "@earendil-works/pi-coding-agent";
 import { type Component, Text, truncateToWidth } from "@earendil-works/pi-tui";
@@ -41,7 +43,7 @@ interface SearchResponse {
 interface FetchResponse {
   title: string;
   content: string;
-  links: string[];
+  links: string[] | null;
 }
 
 // --- Helpers ---
@@ -63,68 +65,45 @@ export async function getCloudApiKey(ctx: Pick<ExtensionContext, "modelRegistry"
   return (await ctx.modelRegistry.getApiKeyForProvider("ollama-cloud")) ?? process.env.OLLAMA_API_KEY;
 }
 
-function noApiKeyError() {
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: "Error: No Ollama Cloud API key configured. Set OLLAMA_API_KEY or add to auth.json.",
-      },
-    ],
-    isError: true,
-  };
+/** Throw a no-API-key error. */
+function noApiKeyError(): never {
+  throw new Error("No Ollama Cloud API key configured. Set OLLAMA_API_KEY or add to auth.json.");
 }
 
-/** Search error response for a non-ok result, mapping distinct status codes. */
-function searchError(status: number, error?: string) {
+/** Throw a search error for a non-ok result, mapping distinct status codes. */
+function searchError(status: number, error?: string): never {
   if (status === 401 || status === 403) {
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text:
-            "Ollama Cloud search failed: authentication error. " + "Check your API key in OLLAMA_API_KEY or auth.json.",
-        },
-      ],
-      isError: true,
-    };
+    throw new Error(
+      "Ollama Cloud search failed: authentication error. " + "Check your API key in OLLAMA_API_KEY or auth.json.",
+    );
   }
   if (status === 429) {
-    return {
-      content: [{ type: "text" as const, text: "Ollama Cloud search failed: rate limited. Try again shortly." }],
-      isError: true,
-    };
+    throw new Error("Ollama Cloud search failed: rate limited. Try again shortly.");
   }
-  return {
-    content: [{ type: "text" as const, text: `Search API error (status ${status}): ${error || "unknown error"}` }],
-    isError: true,
-  };
+  if (status >= 500) {
+    throw new Error(`Ollama Cloud search failed: server error (status ${status}). Try again shortly.`);
+  }
+  throw new Error(
+    `Ollama Cloud search failed: unexpected response (status ${status}${error ? `: ${error}` : ""}). Try again shortly.`,
+  );
 }
 
-/** Fetch error response for a non-ok result, mapping distinct status codes. */
-function fetchError(status: number, error?: string) {
+/** Throw a fetch error for a non-ok result, mapping distinct status codes. */
+function fetchError(status: number, error?: string): never {
   if (status === 401 || status === 403) {
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text:
-            "Ollama Cloud fetch failed: authentication error. " + "Check your API key in OLLAMA_API_KEY or auth.json.",
-        },
-      ],
-      isError: true,
-    };
+    throw new Error(
+      "Ollama Cloud fetch failed: authentication error. " + "Check your API key in OLLAMA_API_KEY or auth.json.",
+    );
   }
   if (status === 429) {
-    return {
-      content: [{ type: "text" as const, text: "Ollama Cloud fetch failed: rate limited. Try again shortly." }],
-      isError: true,
-    };
+    throw new Error("Ollama Cloud fetch failed: rate limited. Try again shortly.");
   }
-  return {
-    content: [{ type: "text" as const, text: `Fetch API error (status ${status}): ${error || "unknown error"}` }],
-    isError: true,
-  };
+  if (status >= 500) {
+    throw new Error(`Ollama Cloud fetch failed: server error (status ${status}). Try again shortly.`);
+  }
+  throw new Error(
+    `Ollama Cloud fetch failed: unexpected response (status ${status}${error ? `: ${error}` : ""}). Try again shortly.`,
+  );
 }
 
 const PREVIEW_LINES = 8;
@@ -135,17 +114,19 @@ const PREVIEW_LINES = 8;
  */
 function createRenderResult() {
   return (
-    result: { content: Array<{ type: string; text: string }>; isError?: boolean },
-    options: { expanded: boolean; isPartial: boolean },
+    result: AgentToolResult<unknown>,
+    options: ToolRenderResultOptions,
     theme: Theme,
     context: {
       invalidate: () => void;
       lastComponent: Component | undefined;
+      isError: boolean;
       state: { cachedWidth?: number; cachedLines?: string[]; cachedSkipped?: number };
     },
   ) => {
     const state = context.state;
     const output = result.content
+      .filter((c): c is { type: "text"; text: string } => c.type === "text")
       .map((c) => c.text)
       .join("")
       .trim();
@@ -154,9 +135,9 @@ function createRenderResult() {
       .map((line: string) => theme.fg("toolOutput", line))
       .join("\n");
 
-    if (options.expanded || result.isError) {
+    if (options.expanded || context.isError) {
       const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-      text.setText(result.isError ? styledOutput : `\n${styledOutput}`);
+      text.setText(context.isError ? styledOutput : `\n${styledOutput}`);
       return text;
     }
 
@@ -185,16 +166,25 @@ function createRenderResult() {
   };
 }
 
-/** Validate a parsed web_search response: must have a results array. */
-function isSearchResponse(data: unknown): data is SearchResponse {
-  return data != null && typeof data === "object" && Array.isArray((data as SearchResponse).results);
+/** Validate a parsed web_search response: must have a results array of well-formed entries. */
+export function isSearchResponse(data: unknown): data is SearchResponse {
+  if (data == null || typeof data !== "object") return false;
+  const results = (data as SearchResponse).results;
+  return (
+    Array.isArray(results) &&
+    results.every((r) => typeof r.title === "string" && typeof r.url === "string" && typeof r.content === "string")
+  );
 }
 
-/** Validate a parsed web_fetch response: must have string title/content and a links array. */
-function isFetchResponse(data: unknown): data is FetchResponse {
+/** Validate a parsed web_fetch response: must have string title/content and a links array of strings (or null). */
+export function isFetchResponse(data: unknown): data is FetchResponse {
   if (data == null || typeof data !== "object") return false;
   const d = data as FetchResponse;
-  return typeof d.title === "string" && typeof d.content === "string" && Array.isArray(d.links);
+  return (
+    typeof d.title === "string" &&
+    typeof d.content === "string" &&
+    (d.links === null || (Array.isArray(d.links) && d.links.every((l) => typeof l === "string")))
+  );
 }
 
 // --- Registrations ---
@@ -220,7 +210,9 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const apiKey = await getCloudApiKey(ctx);
-      if (!apiKey) return noApiKeyError();
+      if (!apiKey) {
+        noApiKeyError();
+      }
 
       const res = await fetchJsonWithTimeout<SearchResponse>(
         `${OLLAMA_BASE}/api/web_search`,
@@ -239,12 +231,11 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
         signal,
       );
 
-      if (!res.ok) return searchError(res.status, res.error);
+      if (!res.ok) {
+        searchError(res.status, res.error);
+      }
       if (!isSearchResponse(res.data)) {
-        return {
-          content: [{ type: "text", text: "Web search failed: unexpected response shape from the API." }],
-          isError: true,
-        };
+        throw new Error("Web search failed: unexpected response shape from the API.");
       }
 
       const formatted = res.data.results
@@ -277,7 +268,9 @@ export function registerWebFetchTool(pi: ExtensionAPI) {
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const apiKey = await getCloudApiKey(ctx);
-      if (!apiKey) return noApiKeyError();
+      if (!apiKey) {
+        noApiKeyError();
+      }
 
       const res = await fetchJsonWithTimeout<FetchResponse>(
         `${OLLAMA_BASE}/api/web_fetch`,
@@ -293,12 +286,11 @@ export function registerWebFetchTool(pi: ExtensionAPI) {
         signal,
       );
 
-      if (!res.ok) return fetchError(res.status, res.error);
+      if (!res.ok) {
+        fetchError(res.status, res.error);
+      }
       if (!isFetchResponse(res.data)) {
-        return {
-          content: [{ type: "text", text: "Web fetch failed: unexpected response shape from the API." }],
-          isError: true,
-        };
+        throw new Error("Web fetch failed: unexpected response shape from the API.");
       }
 
       const data = res.data;