pi-ollama-cloud 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-05-22
+
+- Update `peerDependencies` and imports to the new `@earendil-works/*` packages.
+- Add build script (`scripts/generate-models.ts`) to generate `models.generated.ts` with Ollama Cloud tool-capable models from live API data. The script requires no API key.
+- Drop `FALLBACK_MODELS` in favor of `GENERATED_MODELS` which ships with the package.
+- Remove `apiKey` requirement from `fetchModelIds` and `fetchModelDetails`. Ollama Cloud's public `/v1/models` and `/api/show` endpoints do not require authentication for model metadata. (#15)
+- Remove `getOllamaCloudApiKey`, `refreshModelsFromAuth`, and the "No API key found" notification path from `fetchModels`. Users can now browse model metadata without configuring a key.
+- Remove `401`/`403` error handling from the model metadata fetch functions.
+- Add configuration system (`config.ts`) with JSON config files (global + project-local) and `/ollama-webtools` command for runtime web tools toggling.
+- Add test infrastructure (`vitest`) and model validation tests (`test/models.test.ts`).
+- Add HTTP status-aware error handling in web tools (`401`/`403` → auth error, `429` → rate limit).
+- Add explicit `buildCompat()` with all 17 `OpenAICompletionsCompat` flags set explicitly, verified against Ollama API docs.
+- Set the provider display name to `Ollama Cloud` so it reads cleanly in `/login`, `/model`, and the model selector.
+- Document `/login` as the recommended way to configure the API key.
+- Update README to clarify baked-in model list and refresh behavior.
+- Document web-tools.ts module boundaries in file header comment.
+
 ## [0.4.1] - 2026-05-07
 
 - Add `renderCall` to `ollama_web_search` and `ollama_web_fetch` tools so the TUI displays the query/URL in the tool call header instead of just the bare tool name. (#12)

package/README.md

@@ -8,8 +8,9 @@ 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.
-- **Persistent cache** - Raw API responses are cached at `~/.pi/agent/cache/ollama-cloud-models.json` so models are available immediately on startup without hitting the network.
-- **Startup refresh** - When the local cache is stale, the plugin uses it immediately and then runs the same visible refresh flow as `/ollama-cloud-refresh` once the Pi session UI is available. Missing/invalid caches use a small fallback list until refresh completes.
+- **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).
 - **`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.
@@ -65,13 +66,15 @@ Sign up at [ollama.com](https://ollama.com) and generate an API key.
 
 ### 2. Configure the API key
 
-Either set the `OLLAMA_API_KEY` environment variable:
+The simplest way is the `/login` command inside Pi: run `/login`, choose **Use an API key**, pick **Ollama Cloud**, and paste your key. Pi stores it in `~/.pi/agent/auth.json` and `/logout` removes it.
+
+Alternatively, set the `OLLAMA_API_KEY` environment variable:
 
 ```bash
 export OLLAMA_API_KEY="your-key"
 ```
 
-Or add it to `~/.pi/agent/auth.json`:
+Or add it to `~/.pi/agent/auth.json` by hand:
 
 ```json
 {
@@ -82,19 +85,36 @@ Or add it to `~/.pi/agent/auth.json`:
 }
 ```
 
-### 3. Disable web tools (optional)
+### 3. Configure the extension (optional)
 
-If you want to use a different web search or fetch tool (e.g. Brave) by default, and need to avoid conflicts with the built-in Ollama Cloud tools, set the `PI_OLLAMA_WEB_TOOLS` environment variable to any falsy value:
+Extension settings can be set via JSON config files. Project-local settings override global/user-level settings.
 
-```bash
-export PI_OLLAMA_WEB_TOOLS=0
+| Location | Scope |
+|---|---|
+| `~/.pi/agent/ollama-cloud.json` | Global / user-level (all projects) |
+| `.pi/ollama-cloud.json` | Project-local (takes precedence) |
+
+**Available settings:**
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `webTools` | boolean | `true` | Set to `false` to prevent `ollama_web_search` and `ollama_web_fetch` from being registered |
+
+Example `ollama-cloud.json`:
+
+```json
+{
+  "webTools": false
+}
 ```
 
-Accepted disabling values are `0`, `false`, `no`, `off`, or an empty string. When disabled, `ollama_web_search` and `ollama_web_fetch` are not registered. The model provider and `/ollama-cloud-refresh` command remain active regardless.
+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)
 
-### 4. Fetch models
+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.
 
-On first launch the plugin registers a small hardcoded fallback list, then refreshes model metadata automatically with the same progress widget used by the manual command. If an existing cache is merely stale, that cached model list remains active while refresh runs. You can also run:
+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
@@ -115,7 +135,7 @@ 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 triggers the visible refresh flow on `session_start`. If the cache is missing or invalid, the plugin registers a small hardcoded model list until refresh succeeds. If no key is available or refresh fails, the current registered list remains active until `/ollama-cloud-refresh` succeeds.
+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`).
 
 Model metadata is derived from the cached data:
 
@@ -163,6 +183,7 @@ 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 |
+| `/ollama-webtools [on\|off\|enable\|disable]` | Enable or disable the `ollama_web_search` and `ollama_web_fetch` tools. Toggles if no argument given. |
 
 ## Development
 
@@ -220,5 +241,5 @@ Each publish also gets automatic [provenance attestation](https://docs.npmjs.com
 
 ## Notes
 
-- The extension sets `supportsDeveloperRole: false` on all models so the system prompt always uses `role: "system"`. Without this, pi sends the prompt as `role: "developer"` for thinking-capable models, which some models (e.g. GLM-5.1) ignore entirely - the prompt simply isn't read.
 - 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.
+- `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

@@ -0,0 +1,130 @@
+/**
+ * Configuration loader for pi-ollama-cloud.
+ *
+ * Reads settings from JSON config files with project-over-global precedence:
+ *   - ~/.pi/agent/ollama-cloud.json (global / user-level)
+ *   - .pi/ollama-cloud.json        (project-local, takes precedence)
+ *
+ * Environment variables serve as overrides above both config files:
+ *   - PI_OLLAMA_WEB_TOOLS=0  disables web tool registration
+ *
+ * Example ollama-cloud.json:
+ * ```json
+ * {
+ *   "webTools": false
+ * }
+ * ```
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// --- Types ---
+
+export interface OllamaCloudConfig {
+  /** When false, ollama_web_search and ollama_web_fetch tools are not registered. Default: true. */
+  webTools?: boolean;
+}
+
+// --- Defaults ---
+
+const DEFAULT_CONFIG: OllamaCloudConfig = {
+  webTools: true,
+};
+
+// --- Validation ---
+
+/** Allowed config keys and their expected types for runtime validation. */
+const CONFIG_SCHEMA: Record<keyof OllamaCloudConfig, "boolean"> = {
+  webTools: "boolean",
+};
+
+/**
+ * Validate a parsed JSON object against the known schema.
+ * Unknown keys are silently dropped; values with wrong types fall back to undefined.
+ */
+function sanitizeConfig(raw: Record<string, unknown>): OllamaCloudConfig {
+  const out: OllamaCloudConfig = {};
+  for (const [key, expectedType] of Object.entries(CONFIG_SCHEMA)) {
+    const value = raw[key];
+    if (typeof value === expectedType) {
+      (out as Record<string, unknown>)[key] = value;
+    }
+  }
+  return out;
+}
+
+// --- Loader ---
+
+/**
+ * Load configuration from JSON files.
+ * Project-local config overrides global config.
+ * Environment variables override both.
+ */
+export function loadConfig(cwd: string): OllamaCloudConfig {
+  const globalPath = join(getAgentDir(), "ollama-cloud.json");
+  const projectPath = join(cwd, ".pi", "ollama-cloud.json");
+
+  let globalConfig: OllamaCloudConfig = {};
+  let projectConfig: OllamaCloudConfig = {};
+
+  // Load global config
+  if (existsSync(globalPath)) {
+    try {
+      const content = readFileSync(globalPath, "utf-8");
+      const parsed = JSON.parse(content);
+      // Silently skip files that parse to null, arrays, or primitives —
+      // malformed config should not crash the extension (defaults apply).
+      if (parsed != null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        globalConfig = sanitizeConfig(parsed as Record<string, unknown>);
+      }
+    } catch (err) {
+      console.error(`[pi-ollama-cloud] Failed to load config from ${globalPath}: ${err}`);
+    }
+  }
+
+  // Load project config
+  if (existsSync(projectPath)) {
+    try {
+      const content = readFileSync(projectPath, "utf-8");
+      const parsed = JSON.parse(content);
+      // Same guard as global config: null/array/primitive parses are ignored.
+      if (parsed != null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        projectConfig = sanitizeConfig(parsed as Record<string, unknown>);
+      }
+    } catch (err) {
+      console.error(`[pi-ollama-cloud] Failed to load config from ${projectPath}: ${err}`);
+    }
+  }
+
+  // Merge with defaults: defaults < global < project
+  const merged: OllamaCloudConfig = {
+    ...DEFAULT_CONFIG,
+    ...globalConfig,
+    ...projectConfig,
+  };
+
+  // Environment variable overrides (only webTools for now)
+  const envOverride = resolveWebToolsEnv();
+  if (envOverride !== undefined) {
+    merged.webTools = envOverride;
+  }
+
+  return merged;
+}
+
+/**
+ * Resolve the PI_OLLAMA_WEB_TOOLS environment variable override.
+ * Returns undefined when not set (no override),
+ * true/false when explicitly set.
+ */
+export function resolveWebToolsEnv(): boolean | undefined {
+  const raw = process.env.PI_OLLAMA_WEB_TOOLS;
+  if (raw === undefined) return undefined;
+
+  const lowered = raw.toLowerCase();
+  if (["0", "false", "no", "off", ""].includes(lowered)) return false;
+  // Treat any other non-empty value as "enabled"
+  return true;
+}

package/index.ts

@@ -17,16 +17,21 @@
  * 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.
  *
- * Local cache entries include timestamp. Stale local caches are used immediately while a visible startup
- * refresh runs; missing/invalid caches use a small hardcoded model list until refresh completes.
+ * 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.
  *
  * Only models with "tools" capability are registered.
  */
 
-import type { ExtensionAPI, ExtensionCommandContext, ProviderModelConfig } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { loadConfig, resolveWebToolsEnv } from "./config.ts";
+import { GENERATED_MODELS } from "./models.generated.ts";
 import {
   assembleModels,
-  FALLBACK_MODELS,
   fetchModels,
   OLLAMA_BASE,
   type RefreshProgress,
@@ -35,20 +40,11 @@ import {
 } from "./models.ts";
 import { registerWebFetchTool, registerWebSearchTool } from "./web-tools.ts";
 
-/**
- * Opt-out flag for the ollama_web_search and ollama_web_fetch tools.
- * When the value is one of "0", "false", "no", "off", or the empty string,
- * both web tool registrations are skipped. The model provider and
- * /ollama-cloud-refresh command remain active regardless.
- */
-const PI_OWT_RAW = process.env.PI_OLLAMA_WEB_TOOLS;
-const WEB_TOOLS_DISABLED =
-  PI_OWT_RAW !== undefined && ["0", "false", "no", "off", ""].includes(PI_OWT_RAW.toLowerCase());
-
 // --- 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",
@@ -124,8 +120,14 @@ function registerRefreshCommand(pi: ExtensionAPI) {
 
 export default async function (pi: ExtensionAPI) {
   const cacheState = readCacheState();
-  const needsStartupRefresh = cacheState.status !== "fresh";
-  const models = cacheState.status === "missing" ? FALLBACK_MODELS : assembleModels(cacheState.models);
+  // 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 (36 tool-capable models from
+  // the build script). 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);
@@ -139,8 +141,101 @@ export default async function (pi: ExtensionAPI) {
     });
   }
 
-  if (!WEB_TOOLS_DISABLED) {
-    registerWebSearchTool(pi);
-    registerWebFetchTool(pi);
+  // --- Web Tools Management ---
+
+  /**
+   * Ensure web tools are registered (idempotent).
+   * Returns true if any tools were newly registered.
+   */
+  function ensureWebToolsRegistered(): boolean {
+    const allTools = pi.getAllTools();
+    let registered = false;
+    if (!allTools.some((t) => t.name === "ollama_web_search")) {
+      registerWebSearchTool(pi);
+      registered = true;
+    }
+    if (!allTools.some((t) => t.name === "ollama_web_fetch")) {
+      registerWebFetchTool(pi);
+      registered = true;
+    }
+    return registered;
+  }
+
+  /**
+   * Add or remove web tools from the active tools set.
+   */
+  function setWebToolsActive(active: boolean) {
+    const currentActive = pi.getActiveTools();
+    const webToolNames = ["ollama_web_search", "ollama_web_fetch"];
+
+    if (active) {
+      const missing = webToolNames.filter((n) => !currentActive.includes(n));
+      if (missing.length > 0) {
+        pi.setActiveTools([...currentActive, ...missing]);
+      }
+    } else {
+      const filtered = currentActive.filter((t) => !webToolNames.includes(t));
+      if (filtered.length < currentActive.length) {
+        pi.setActiveTools(filtered);
+      }
+    }
+  }
+
+  // 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;
+  let webToolsEnabled = false;
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!webToolsConfigured) {
+      webToolsConfigured = true;
+      const config = loadConfig(ctx.cwd);
+      if (config.webTools !== false) {
+        webToolsEnabled = true;
+        ensureWebToolsRegistered();
+      }
+    }
+    // On every session start (including resume/fork/new), re-apply the
+    // runtime state. Tools may have been unregistered during teardown.
+    if (webToolsEnabled) {
+      ensureWebToolsRegistered();
+      setWebToolsActive(true);
+    }
+  });
+
+  // Only register the runtime toggle command when the env var doesn't force tools off.
+  // PI_OLLAMA_WEB_TOOLS acts as a hard kill switch — no command to re-enable.
+  if (resolveWebToolsEnv() !== false) {
+    pi.registerCommand("ollama-webtools", {
+      description:
+        "Enable or disable Ollama Cloud web tools (ollama_web_search, ollama_web_fetch). " +
+        "Accepts optional argument: on/off/enable/disable. Without argument, toggles.",
+      handler: async (args, ctx) => {
+        const arg = args.trim().toLowerCase();
+
+        if (arg === "on" || arg === "enable") {
+          webToolsEnabled = true;
+        } else if (arg === "off" || arg === "disable") {
+          webToolsEnabled = false;
+        } else if (arg === "") {
+          // Toggle current state
+          webToolsEnabled = !webToolsEnabled;
+        } else {
+          ctx.ui.notify(`Unknown argument "${args.trim()}". Usage: /ollama-webtools [on|off|enable|disable]`, "error");
+          return;
+        }
+
+        if (webToolsEnabled) {
+          ensureWebToolsRegistered();
+          setWebToolsActive(true);
+        } else {
+          setWebToolsActive(false);
+        }
+
+        ctx.ui.notify(`Ollama Web Tools: ${webToolsEnabled ? "enabled" : "disabled"}`, "info");
+      },
+    });
   }
 }