pi-ollama-cloud 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+- Fix `/ollama-cloud-usage` and the usage status bar failing with "unexpected response shape" after the undocumented `/api/usage` endpoint flipped between a single `limits.monthly` bucket and `limits.session` plus `limits.weekly` (the shape has flip-flopped repeatedly as of 2026-09). Any bucket present (`monthly`, `session`, `weekly`) is accepted alone or in combination, and whichever are present are displayed as `5h`/`7d`/`30d` segments. Thanks @johanngyger (#56).
+- Cache `ollama_web_search` results (24h) and `ollama_web_fetch` pages (24h success / 15 min failure) on disk under the pi agent home, so repeated queries and page reads cost 0 API calls. Expired entries are pruned on write, the cache is capped at 500 entries per kind (oldest evicted beyond the cap; `PI_OLLAMA_SEARCH_MAX_ENTRIES`), a partially corrupted cache file is validated per entry and degrades to "no cache" instead of crashing tool calls, and the file is written with `0600` permissions since it stores page content and URLs that can embed credentials. Tune with `PI_OLLAMA_SEARCH_TTL_HOURS`, `PI_OLLAMA_SEARCH_FAIL_TTL_MINUTES`, `PI_OLLAMA_SEARCH_MAX_ENTRIES`, and `PI_OLLAMA_SEARCH_CACHE_PATH`.
+- Bound web tool context usage: search snippets truncate to 500 chars with `[truncated]`/`[complete]` markers, `expand=<index>` returns a truncated result's full content from the cached search (0 extra API calls), and `ollama_web_fetch` pages long pages in 3000-char chunks via `offset`/`full` with a `Continue:` hint for the next offset (`PI_OLLAMA_SEARCH_SNIPPET_CHARS`/`PI_OLLAMA_SEARCH_CHUNK_CHARS` to tune).
+- Add `refresh=true` to both web tools to bypass the cache (including a cached failure) and re-call the API; the fresh result replaces the cache entry.
+- Failed page fetches are negative-cached for 15 min with a diagnostic message (likely cause + next steps) instead of a bare error. Auth (401/403), rate-limit (429), transport (timeout/abort/network), server (5xx), and unexpected-response-shape failures are never cached — search reports transport errors as `transport error` instead of a confusing `status 0` — so retrying after a fixed key, an expired rate-limit window, or a transient server blip re-calls the API immediately.
+- Note: `ollama_web_fetch` tool results now carry `details: { title, totalChars, links }` (previously `{ title, content, links }`); paged content is read via the tool output text, not `details.content`.
+
 ## [0.10.0] - 2026-09-03
 
 - **Breaking:** Adapt to the changed `/api/usage` response shape. The endpoint now returns a single `limits.monthly` bucket (replacing `limits.session` and `limits.weekly`) and adds an `activity.models` array. `UsageData`, `isUsageResponse`, `formatUsage`, and `formatUsageStatusColored` now read the monthly limit; the status bar shows a single `30d` segment instead of `5h`/`7d`.

package/README.md

@@ -167,19 +167,60 @@ See [docs/think-experiment.md](docs/think-experiment.md) for the testing methodo
 
 Both tools use the same Ollama Cloud API key configured for the provider. No local Ollama server is needed.
 
+### Caching
+
+Both tools cache results on disk (under the pi agent home, `~/.pi/agent/cache/pi-ollama-cloud/cache.json`). A repeated search query or page fetch within the TTL is served from cache and costs 0 API calls:
+
+- Successful searches and pages: cached for 24h
+- Failed page fetches: negative-cached for 15 min, so retrying a dead page does not re-call the API. Auth (401/403), rate-limit (429), transport (timeouts, aborts, network errors), and server (5xx) failures are not cached — fixing the key, waiting out the limit, or a transient blip lets a retry through immediately
+- Expired entries are pruned on write and the cache is capped at 500 entries per kind (searches/pages), evicting the oldest first. This bounds entry count, not file size: full page and search content can still make `cache.json` large, and loading it parses the whole file
+- The cache file is written with `0600` permissions. It stores full page content and raw URLs, which can embed credentials in query strings — avoid fetching URLs that carry secrets in the query string, or set a custom `PI_OLLAMA_SEARCH_CACHE_PATH`
+- Concurrent pi processes share the cache file on a last-writer-wins basis (no cross-process locking): one process's save can drop another's fresh entries, at the cost of a redundant API call
+- `refresh=true` on either tool bypasses the cache (including a cached failure) and re-calls the API; the fresh result replaces the cache entry
+
+### `ollama_web_search`
+
+Returns up to 5 results by default (`max_results`, max 10; title, URL, 500-char snippet). Snippets are marked `[truncated]` when the source is longer than the snippet. Output ends with `# live query` or `# from cache` to show whether the API was called.
+
+The search API returns each result's full content; it is cached in full, so a truncated result can be expanded without a separate fetch:
+
+- `expand=<index>` — return the full content of that result (1-based) from the cached search, 0 extra API calls. The cache key includes `max_results`, so expanding hits the cache only when the query was searched with the same `max_results`; otherwise the search runs live first.
+- Use `ollama_web_fetch` only when the search result's content is not enough (e.g. you need a different page, or the search excerpt is shorter than the full page).
+
+### `ollama_web_fetch`
+
+Returns the page title, a 3000-char slice of the content, and links. Long pages are read in chunks to keep the context window small:
+
+- `offset=N` — continue reading from character N (the output tells you the next offset)
+- `full=true` — return all remaining content from `offset` in one call
+
+A failed fetch throws a diagnostic message (likely cause + next steps) instead of a bare error.
+
+### Tuning
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `PI_OLLAMA_SEARCH_TTL_HOURS` | `24` | Success cache TTL |
+| `PI_OLLAMA_SEARCH_FAIL_TTL_MINUTES` | `15` | Failure (negative) cache TTL |
+| `PI_OLLAMA_SEARCH_CACHE_PATH` | `<pi agent home>/cache/pi-ollama-cloud/cache.json` | Cache file location |
+| `PI_OLLAMA_SEARCH_MAX_ENTRIES` | `500` | Max cached entries per kind (searches/pages); oldest evicted beyond the cap |
+| `PI_OLLAMA_SEARCH_SNIPPET_CHARS` | `500` | Search snippet length |
+| `PI_OLLAMA_SEARCH_CHUNK_CHARS` | `3000` | Fetch chunk size |
+
 ## Commands
 
 | Command | Description |
 |---|---|
 | `/ollama-webtools [on\|off\|enable\|disable]` | Enable or disable the `ollama_web_search` and `ollama_web_fetch` tools. Toggles if no argument given. |
-| `/ollama-cloud-usage` | Show Ollama Cloud monthly usage limits, per-model request counts, and the 4-week activity cost. |
+| `/ollama-cloud-usage` | Show Ollama Cloud usage limits (one section per limit bucket the API reports), per-model request counts, and the 4-week activity cost. |
 | `/ollama-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 (`30d ▕███░░░░░░░▏ 34%`) that refreshes
-every 5 minutes and after each agent turn (but no more often than every 5 minutes). It is colored by how close
+live usage readout with one segment per limit bucket the API reports
+(`5h ▕███░░░░░░░▏ 34% 7d ▕█░░░░░░░░░▏ 7%`, or a single `30d` segment) that
+refreshes every 5 minutes and after each agent turn (but no more often than every 5 minutes). It is colored by how close
 it is to the cap: green below 60%, yellow at 60-79%, red at 80%+. It reads the
 same undocumented `/api/usage` endpoint as `/ollama-cloud-usage` and clears
 itself on transient errors or when you switch to a non-Ollama-Cloud provider.

package/cache.ts

@@ -0,0 +1,181 @@
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { envInt } from "./utils.ts";
+
+export const CACHE_PATH =
+  process.env.PI_OLLAMA_SEARCH_CACHE_PATH ?? join(getAgentDir(), "cache", "pi-ollama-cloud", "cache.json");
+export const CACHE_TTL_MS = envInt("PI_OLLAMA_SEARCH_TTL_HOURS", 24) * 60 * 60 * 1000;
+export const FAIL_TTL_MS = envInt("PI_OLLAMA_SEARCH_FAIL_TTL_MINUTES", 15) * 60 * 1000;
+/** Max entries per map (searches/pages); oldest-ts entries are evicted beyond this. */
+export const MAX_ENTRIES = envInt("PI_OLLAMA_SEARCH_MAX_ENTRIES", 500);
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  content: string;
+}
+
+export interface SearchCacheEntry {
+  ts: number;
+  q: string;
+  results: SearchResult[];
+}
+
+export interface PageCacheEntry {
+  ts: number;
+  status?: number;
+  title?: string;
+  content?: string;
+  links?: string[] | null;
+  error?: string;
+  errorType?: "response-shape";
+}
+
+export interface CacheData {
+  searches: Record<string, SearchCacheEntry>;
+  pages: Record<string, PageCacheEntry>;
+}
+
+interface CacheOptions {
+  path: string;
+  ttlMs: number;
+  failTtlMs: number;
+  maxEntries: number;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Keys that must never come from a parsed JSON file (prototype pollution). */
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+export function isSafeKey(key: string): boolean {
+  return !UNSAFE_KEYS.has(key);
+}
+
+/** Shallow shape checks so a partially corrupted cache file degrades instead of crashing tool calls. */
+function isSearchEntry(v: unknown): v is SearchCacheEntry {
+  return (
+    isRecord(v) &&
+    typeof v.ts === "number" &&
+    typeof v.q === "string" &&
+    Array.isArray(v.results) &&
+    v.results.every(
+      (r) => isRecord(r) && typeof r.title === "string" && typeof r.url === "string" && typeof r.content === "string",
+    )
+  );
+}
+
+function isPageEntry(v: unknown): v is PageCacheEntry {
+  if (!isRecord(v) || typeof v.ts !== "number") return false;
+  const fieldsValid =
+    (v.status === undefined || typeof v.status === "number") &&
+    (v.title === undefined || typeof v.title === "string") &&
+    (v.content === undefined || typeof v.content === "string") &&
+    (v.links === null ||
+      v.links === undefined ||
+      (Array.isArray(v.links) && v.links.every((l) => typeof l === "string"))) &&
+    (v.error === undefined || (typeof v.error === "string" && v.error !== "")) &&
+    (v.errorType === undefined || v.errorType === "response-shape");
+  if (!fieldsValid) return false;
+  // Must be either a real failure or a real success; anything else (e.g. an
+  // entry with neither content nor a non-empty error) would render as a fake
+  // empty success.
+  return (
+    (typeof v.error === "string" && v.error !== "") || (typeof v.title === "string" && typeof v.content === "string")
+  );
+}
+
+export interface CacheStore {
+  loadCache(): CacheData;
+  saveCache(): void;
+  isFresh(entry: { ts: number; error?: string } | undefined): boolean;
+}
+
+export function createCache(options: Partial<CacheOptions> = {}): CacheStore {
+  const path = options.path ?? CACHE_PATH;
+  const ttlMs = options.ttlMs ?? CACHE_TTL_MS;
+  const failTtlMs = options.failTtlMs ?? FAIL_TTL_MS;
+  const maxEntries = options.maxEntries ?? MAX_ENTRIES;
+  let cacheData: CacheData | null = null;
+
+  function loadCache(): CacheData {
+    if (cacheData) return cacheData;
+    try {
+      const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+      if (isRecord(raw) && isRecord(raw.searches) && isRecord(raw.pages)) {
+        // Per-entry validation: drop poisoned entries so a partially corrupt
+        // file degrades to "those entries are gone" instead of crashing calls.
+        cacheData = { searches: {}, pages: {} };
+        for (const [key, entry] of Object.entries(raw.searches)) {
+          if (isSafeKey(key) && isSearchEntry(entry)) cacheData.searches[key] = entry;
+        }
+        for (const [key, entry] of Object.entries(raw.pages)) {
+          if (isSafeKey(key) && isPageEntry(entry)) cacheData.pages[key] = entry;
+        }
+        return cacheData;
+      }
+    } catch {
+      // First run or corrupt file, start fresh.
+    }
+    cacheData = { searches: {}, pages: {} };
+    return cacheData;
+  }
+
+  function isFresh(entry: { ts: number; error?: string } | undefined): boolean {
+    if (!entry) return false;
+    // A future ts (hand-edited file) would otherwise be fresh forever; treat as stale.
+    if (entry.ts > Date.now()) return false;
+    return Date.now() - entry.ts < (entry.error ? failTtlMs : ttlMs);
+  }
+
+  function evictOldest(map: Record<string, { ts: number }>): void {
+    const keys = Object.keys(map);
+    if (keys.length <= maxEntries) return;
+    const overflow = keys.sort((a, b) => map[a].ts - map[b].ts).slice(0, keys.length - maxEntries);
+    for (const key of overflow) delete map[key];
+  }
+
+  function saveCache(): void {
+    const data = loadCache();
+    for (const [key, entry] of Object.entries(data.searches)) if (!isFresh(entry)) delete data.searches[key];
+    for (const [key, entry] of Object.entries(data.pages)) if (!isFresh(entry)) delete data.pages[key];
+    // TTL bounds entry age; the cap bounds entry count so an aggressive session
+    // cannot grow the file without limit.
+    evictOldest(data.searches);
+    evictOldest(data.pages);
+    try {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      // Use a unique temporary path so concurrent processes cannot overwrite
+      // one another's in-progress writes.
+      const tmp = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+      try {
+        // 0o600: the cache stores full page content and URLs, which can embed
+        // credentials in query strings; it should not be world-readable.
+        writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+        renameSync(tmp, path);
+        // Fix perms of a file written by a pre-0600 version.
+        chmodSync(path, 0o600);
+      } catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+      }
+    } catch {
+      // Cache is best-effort; a failed write must not break the tool call.
+    }
+  }
+
+  return { loadCache, saveCache, isFresh };
+}
+
+export const defaultCache = createCache();
+export const loadCache = defaultCache.loadCache;
+export const saveCache = defaultCache.saveCache;
+export const isFresh = defaultCache.isFresh;
+
+export function searchCacheKey(query: string, maxResults: number): string {
+  return createHash("sha1").update(`${query}\n${maxResults}`).digest("hex");
+}

package/index.ts

@@ -134,7 +134,7 @@ export default async function (pi: ExtensionAPI) {
   // --- Usage Command ---
 
   pi.registerCommand("ollama-cloud-usage", {
-    description: "Show Ollama Cloud monthly usage limits.",
+    description: "Show Ollama Cloud usage limits.",
     handler: async (_args, ctx) => {
       const apiKey = await getCloudApiKey(ctx);
       if (!apiKey) {
@@ -152,7 +152,7 @@ export default async function (pi: ExtensionAPI) {
 
   // --- Usage Status Bar ---
 
-  // Footer status showing live monthly usage while ollama-cloud is the
+  // Footer status showing live 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ollama-cloud",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -8,6 +8,7 @@
   "files": [
     "index.ts",
     "config.ts",
+    "cache.ts",
     "limits.generated.ts",
     "models.ts",
     "models.generated.ts",

package/usage.ts

@@ -11,6 +11,12 @@
  * fetch degrades gracefully: distinct HTTP statuses map to distinct
  * user-facing errors, and a malformed body raises a clear error rather than
  * crashing.
+ *
+ * The response shape has flipped twice: through 2026-09-02 it carried
+ * limits.session and limits.weekly, on 2026-09-03 it switched to a single
+ * limits.monthly bucket (0.10.0 adapted to that), and by 2026-09-07 it
+ * returned session and weekly again. All three buckets are therefore optional
+ * and whichever are present are displayed.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
@@ -43,7 +49,12 @@ export interface UsageActivity {
 
 export interface UsageData {
   limits: {
-    monthly: UsageLimit;
+    /** Monthly (30d) bucket, served by the API between 2026-09-03 and 2026-09-07. */
+    monthly?: UsageLimit;
+    /** Session (5h) bucket, served before 2026-09-03 and again as of 2026-09-07. */
+    session?: UsageLimit;
+    /** Weekly (7d) bucket, served before 2026-09-03 and again as of 2026-09-07. */
+    weekly?: UsageLimit;
   };
   activity?: UsageActivity;
 }
@@ -71,11 +82,18 @@ export function isUsageLimit(data: unknown): data is UsageLimit {
   );
 }
 
-/** Validate a parsed /api/usage response: must have a monthly limit. */
+/**
+ * Validate a parsed /api/usage response: needs at least one valid limit bucket.
+ * The endpoint is undocumented and flips shape unpredictably (monthly-only,
+ * session+weekly, possibly other combinations), so any bucket present alone or
+ * in any combination is accepted and rendered.
+ */
 export function isUsageResponse(data: unknown): data is UsageData {
   if (data == null || typeof data !== "object") return false;
   const d = data as UsageData;
-  return d.limits != null && typeof d.limits === "object" && isUsageLimit(d.limits.monthly);
+  if (d.limits == null || typeof d.limits !== "object" || Array.isArray(d.limits)) return false;
+  const buckets = [d.limits.monthly, d.limits.session, d.limits.weekly];
+  return buckets.some(isUsageLimit) && buckets.every((bucket) => bucket === undefined || isUsageLimit(bucket));
 }
 
 // --- Fetch ---
@@ -121,14 +139,30 @@ function usagePercent(usage: number): number {
   return Math.min(Math.max(Math.round(usage * 100), 0), 100);
 }
 
+/** The limit buckets present in a response, in display order. */
+function limitSegments(data: UsageData): Array<{ label: string; short: string; limit: UsageLimit }> {
+  const segs: Array<{ label: string; short: string; limit: UsageLimit }> = [];
+  if (isUsageLimit(data.limits.session)) {
+    segs.push({ label: "Session (5h)", short: "5h", limit: data.limits.session });
+  }
+  if (isUsageLimit(data.limits.weekly)) {
+    segs.push({ label: "Weekly (7d)", short: "7d", limit: data.limits.weekly });
+  }
+  if (isUsageLimit(data.limits.monthly)) {
+    segs.push({ label: "Monthly (30d)", short: "30d", limit: data.limits.monthly });
+  }
+  return segs;
+}
+
 /** Format usage for the /ollama-cloud-usage command output. */
 export function formatUsage(data: UsageData): string {
   const lines: string[] = ["Ollama Cloud usage:"];
 
-  const monthlyPct = usagePercent(data.limits.monthly.usage);
-  lines.push(`  Monthly (30d): ${monthlyPct}%`);
-  for (const m of data.limits.monthly.models) {
-    lines.push(`    - ${m.name}: ${m.request_count} request${m.request_count === 1 ? "" : "s"}`);
+  for (const seg of limitSegments(data)) {
+    lines.push(`  ${seg.label}: ${usagePercent(seg.limit.usage)}%`);
+    for (const m of seg.limit.models) {
+      lines.push(`    - ${m.name}: ${m.request_count} request${m.request_count === 1 ? "" : "s"}`);
+    }
   }
 
   if (typeof data.activity?.cost === "string") {
@@ -151,11 +185,13 @@ function colorSegment(theme: Theme, label: string, pct: number): string {
 }
 
 /**
- * Compact one-line usage for the footer status bar, colored by usage level.
- * The endpoint exposes a monthly reset period but not an exact timestamp, so
- * the color reflects the usage fraction rather than pace.
+ * Compact one-line usage for the footer status bar, colored by usage level,
+ * with one segment per limit bucket present in the response (5h and 7d, or
+ * 30d when the API serves the monthly shape). The color reflects the usage
+ * fraction rather than pace because the bucket periods differ per shape.
  */
 export function formatUsageStatusColored(theme: Theme, data: UsageData): string {
-  const monthly = usagePercent(data.limits.monthly.usage);
-  return colorSegment(theme, "30d", monthly);
+  return limitSegments(data)
+    .map((seg) => colorSegment(theme, seg.short, usagePercent(seg.limit.usage)))
+    .join(" ");
 }

package/utils.ts

@@ -111,3 +111,9 @@ export function httpError(op: string, status: number, error?: string): never {
     `Ollama Cloud ${op} failed: unexpected response (status ${status}${error ? `: ${error}` : ""}). Try again shortly.`,
   );
 }
+
+/** Parse a positive-integer env var, falling back when unset or invalid (NaN, non-integer, <= 0). */
+export function envInt(name: string, fallback: number): number {
+  const value = Number(process.env[name]);
+  return Number.isInteger(value) && value > 0 ? value : fallback;
+}

package/web-tools.ts

@@ -6,6 +6,7 @@
  *   - pi-coding-agent - ExtensionAPI, ExtensionContext, keyHint, truncateToVisualLines
  *   - pi-tui          - Text, truncateToWidth
  *   - utils.ts        - fetchJsonWithTimeout
+ *   - cache.ts        - disk-backed cache (24h success / 15min failure TTL)
  * Does NOT depend on provider registration or model fetching internals.
  *
  * API key resolution: each tool's execute() receives an ExtensionContext whose
@@ -26,8 +27,18 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { type Component, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
+import {
+  CACHE_TTL_MS,
+  type CacheStore,
+  defaultCache,
+  FAIL_TTL_MS,
+  isSafeKey,
+  type PageCacheEntry,
+  type SearchResult,
+  searchCacheKey,
+} from "./cache.ts";
 import { OLLAMA_BASE } from "./models.ts";
-import { fetchJsonWithTimeout, getCloudApiKey, httpError } from "./utils.ts";
+import { envInt, fetchJsonWithTimeout, getCloudApiKey, httpError } from "./utils.ts";
 
 // --- Types ---
 
@@ -48,6 +59,12 @@ interface FetchResponse {
 // --- Helpers ---
 
 const WEB_TOOLS_TIMEOUT_MS = 15000;
+// Search snippets and fetch chunks are capped so a single call never floods the
+// context window; the agent pages through long pages with offset/full.
+const SNIPPET_LIMIT = envInt("PI_OLLAMA_SEARCH_SNIPPET_CHARS", 500);
+const READ_CHUNK = envInt("PI_OLLAMA_SEARCH_CHUNK_CHARS", 3000);
+const SUCCESS_TTL_HOURS = CACHE_TTL_MS / 3_600_000;
+const FAIL_TTL_MINUTES = Math.round(FAIL_TTL_MS / 60_000);
 
 /** Throw a no-API-key error. */
 function noApiKeyError(): never {
@@ -135,15 +152,61 @@ export function isFetchResponse(data: unknown): data is FetchResponse {
   );
 }
 
+/** Build a failure message with likely causes and next steps (thrown, per the AgentToolResult contract). */
+function fetchFailureMessage(
+  url: string,
+  entry: PageCacheEntry,
+  failureState: "cached" | "live-cached" | "live-uncached",
+): string {
+  const lines = [
+    `Ollama Cloud fetch failed: ${url}`,
+    `API error: ${entry.error}`,
+    entry.errorType === "response-shape"
+      ? "Status: live request returned an unexpected response shape (not cached; the next call retries the API)"
+      : failureState === "cached"
+        ? `Status: from cache (failure cached for ${FAIL_TTL_MINUTES} min; pass refresh=true to force a live retry)`
+        : failureState === "live-cached"
+          ? `Status: live request failed (failure cached for ${FAIL_TTL_MINUTES} min; pass refresh=true to force a live retry)`
+          : "Status: live request failed (not cached; the next call retries the API)",
+  ];
+  if (entry.status === 401 || entry.status === 403) {
+    lines.push(
+      "Likely cause: authentication error.",
+      "Suggestion: check your API key in OLLAMA_API_KEY or auth.json, then retry (auth failures are not cached).",
+    );
+  } else if (entry.status === 429) {
+    lines.push("Likely cause: rate limited.", "Suggestion: try again shortly (rate-limit failures are not cached).");
+  } else if (entry.errorType === "response-shape") {
+    lines.push(
+      "Likely cause: Ollama Cloud returned an unexpected response shape.",
+      "Suggestion: try again shortly; this failure is not cached.",
+    );
+  } else if (entry.status !== undefined && entry.status >= 500) {
+    lines.push(
+      "Likely cause: Ollama server error.",
+      "Suggestion: try again shortly (server failures are not cached; the next call retries the API).",
+    );
+  } else {
+    lines.push(
+      "Likely cause: anti-bot / login wall, JS-rendered page, or malformed URL.",
+      "Suggestion: 1) use ollama_web_search for the site/topic; 2) check the URL; 3) retrying with offset/full will also fail — use refresh=true only if you believe the failure was transient.",
+    );
+  }
+  return lines.join("\n");
+}
+
 // --- Registrations ---
 
-export function registerWebSearchTool(pi: ExtensionAPI) {
+export function registerWebSearchTool(pi: ExtensionAPI, cacheStore: CacheStore = defaultCache) {
   pi.registerTool({
     name: "ollama_web_search",
     label: "Ollama Web Search",
     description:
       "Search the web for real-time information using Ollama Cloud's web search API. " +
-      "Returns relevant results with titles, URLs, and content snippets. " +
+      `Returns up to max_results results (default 5, max 10; title, URL, ${SNIPPET_LIMIT}-char snippet; [truncated] means the source is longer — ` +
+      "pass expand=<index> to get that result's full content from the cached search, 0 extra API calls). " +
+      `Results are cached for ${SUCCESS_TTL_HOURS}h: the same query within that window costs 0 API calls. ` +
+      "Pass refresh=true to bypass the cache and re-call the API (e.g. results look stale). " +
       "Requires an Ollama Cloud API key.",
     parameters: Type.Object({
       query: Type.String({ description: "The search query to execute" }),
@@ -155,6 +218,21 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
           maximum: 10,
         }),
       ),
+      refresh: Type.Optional(
+        Type.Boolean({
+          description:
+            "Bypass the cached search and re-call the API (default: false). The fresh result replaces the cache entry.",
+          default: false,
+        }),
+      ),
+      expand: Type.Optional(
+        Type.Integer({
+          description:
+            "Return the full content of this result (1-based index) instead of snippets. " +
+            "Served from the cached search — 0 API calls if the query was searched recently.",
+          minimum: 1,
+        }),
+      ),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const apiKey = await getCloudApiKey(ctx);
@@ -162,37 +240,97 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
         noApiKeyError();
       }
 
-      const res = await fetchJsonWithTimeout<SearchResponse>(
-        `${OLLAMA_BASE}/api/web_search`,
-        {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
+      const maxResults = params.max_results ?? 5;
+      const cache = cacheStore.loadCache();
+      const key = searchCacheKey(params.query, maxResults);
+      const cached = cache.searches[key];
+      let live = false;
+      let results: SearchResult[];
+
+      if (!params.refresh && cacheStore.isFresh(cached)) {
+        results = cached!.results;
+      } else {
+        live = true;
+        const res = await fetchJsonWithTimeout<SearchResponse>(
+          `${OLLAMA_BASE}/api/web_search`,
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+              query: params.query,
+              max_results: maxResults,
+            }),
           },
-          body: JSON.stringify({
-            query: params.query,
-            max_results: params.max_results ?? 5,
-          }),
-        },
-        WEB_TOOLS_TIMEOUT_MS,
-        signal,
-      );
+          WEB_TOOLS_TIMEOUT_MS,
+          signal,
+        );
+
+        if (!res.ok) {
+          if (res.status === 0) {
+            // Transport failure (timeout, abort, network); not a server answer.
+            throw new Error(
+              `Ollama Cloud search failed: transport error (${res.error ?? "unknown"}). Not cached; the next call retries the API.`,
+            );
+          }
+          httpError("search", res.status, res.error);
+        }
+        if (!isSearchResponse(res.data)) {
+          throw new Error("Web search failed: unexpected response shape from the API.");
+        }
 
-      if (!res.ok) {
-        httpError("search", res.status, res.error);
+        results = res.data.results.map((r) => ({
+          title: r.title,
+          url: r.url,
+          content: r.content,
+        }));
+        cache.searches[key] = { ts: Date.now(), q: params.query, results };
+        cacheStore.saveCache();
       }
-      if (!isSearchResponse(res.data)) {
-        throw new Error("Web search failed: unexpected response shape from the API.");
+
+      // Expand mode: return the full content of one result from the cached search.
+      if (params.expand !== undefined) {
+        const idx = params.expand;
+        if (idx < 1 || idx > results.length) {
+          throw new Error(
+            `Web search expand: index ${idx} out of range (this search has ${results.length} results). ` +
+              "Use ollama_web_fetch to read a specific URL instead.",
+          );
+        }
+        const r = results[idx - 1];
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Result ${idx} of "${params.query}" (full content, ${r.content.length} chars):\n\n${r.content}\n\n${live ? "# live query" : "# from cache"}`,
+            },
+          ],
+          details: { results: [r] },
+        };
       }
 
-      const formatted = res.data.results
-        .map((r, i) => `${i + 1}. ${r.title}\n   URL: ${r.url}\n   ${r.content}`)
+      const formatted = results
+        .map((r, i) => {
+          const truncated = r.content.length > SNIPPET_LIMIT;
+          return `${i + 1}. ${truncated ? "[truncated]" : "[complete]"} ${r.title}\n   URL: ${r.url}\n   ${r.content.slice(0, SNIPPET_LIMIT)}`;
+        })
         .join("\n\n");
 
+      const hasTruncated = results.some((r) => r.content.length > SNIPPET_LIMIT);
+      const expandHint = hasTruncated
+        ? `\n\nExpand: call ollama_web_search(query=${JSON.stringify(params.query)}, max_results=${maxResults}, expand=<index>) to read a [truncated] result in full — 0 extra API calls.`
+        : "";
+
       return {
-        content: [{ type: "text", text: formatted || "No results found." }],
-        details: { results: res.data.results },
+        content: [
+          {
+            type: "text",
+            text: `${formatted || "No results found."}${expandHint}\n\n${live ? "# live query" : "# from cache"}`,
+          },
+        ],
+        details: { results },
       };
     },
     renderCall(args, theme, _context) {
@@ -203,16 +341,39 @@ export function registerWebSearchTool(pi: ExtensionAPI) {
   });
 }
 
-export function registerWebFetchTool(pi: ExtensionAPI) {
+export function registerWebFetchTool(pi: ExtensionAPI, cacheStore: CacheStore = defaultCache) {
   pi.registerTool({
     name: "ollama_web_fetch",
     label: "Ollama Web Fetch",
     description:
       "Fetch and extract text content from a web page URL using Ollama Cloud's web fetch API. " +
-      "Returns the page title, main content, and links found on the page. " +
-      "Requires an Ollama Cloud API key.",
+      `Returns the page title, a ${READ_CHUNK}-char slice of the content, and links. Pages are cached for ${SUCCESS_TTL_HOURS}h. ` +
+      "Pass offset=N to continue reading from char N (the output tells you the next offset), or " +
+      `full=true to get all remaining content from offset in one call. A failed URL is cached for ${FAIL_TTL_MINUTES} min ` +
+      `— retrying it within the failure TTL (${FAIL_TTL_MINUTES} min) costs 0 API calls and fails the same way; pass refresh=true to ` +
+      "force a live retry. Requires an Ollama Cloud API key.",
     parameters: Type.Object({
       url: Type.String({ description: "URL to fetch and extract content from", format: "uri" }),
+      offset: Type.Optional(
+        Type.Integer({
+          description: "Start reading from this character index (default: 0)",
+          default: 0,
+          minimum: 0,
+        }),
+      ),
+      full: Type.Optional(
+        Type.Boolean({
+          description: "Return all remaining content from offset in one call (default: false)",
+          default: false,
+        }),
+      ),
+      refresh: Type.Optional(
+        Type.Boolean({
+          description:
+            "Bypass the cached page (or cached failure) and re-call the API (default: false). The fresh result replaces the cache entry.",
+          default: false,
+        }),
+      ),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const apiKey = await getCloudApiKey(ctx);
@@ -220,41 +381,85 @@ export function registerWebFetchTool(pi: ExtensionAPI) {
         noApiKeyError();
       }
 
-      const res = await fetchJsonWithTimeout<FetchResponse>(
-        `${OLLAMA_BASE}/api/web_fetch`,
-        {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
+      const cache = cacheStore.loadCache();
+      let entry = cache.pages[params.url];
+      let live = false;
+      let liveCacheable = false;
+
+      if (params.refresh || !cacheStore.isFresh(entry)) {
+        live = true;
+        const res = await fetchJsonWithTimeout<FetchResponse>(
+          `${OLLAMA_BASE}/api/web_fetch`,
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ url: params.url }),
           },
-          body: JSON.stringify({ url: params.url }),
-        },
-        WEB_TOOLS_TIMEOUT_MS,
-        signal,
-      );
+          WEB_TOOLS_TIMEOUT_MS,
+          signal,
+        );
 
-      if (!res.ok) {
-        httpError("fetch", res.status, res.error);
+        if (!res.ok) {
+          entry = { ts: Date.now(), status: res.status, error: `HTTP ${res.status}: ${res.error ?? "unknown error"}` };
+          // Auth, rate-limit, transport (status 0: timeout, abort, DNS/connection
+          // errors), and server (5xx) failures are not negative-cached: a fixed
+          // key, an expired rate-limit window, or a transient server/network
+          // issue should let the next retry through.
+          liveCacheable =
+            res.status !== 0 && res.status < 500 && res.status !== 401 && res.status !== 403 && res.status !== 429;
+        } else if (!isFetchResponse(res.data)) {
+          // A shape failure is a transient server-side bug, not a durable
+          // property of the page; never negative-cache it.
+          entry = { ts: Date.now(), error: "unexpected response shape from the API", errorType: "response-shape" };
+          liveCacheable = false;
+        } else {
+          entry = {
+            ts: Date.now(),
+            title: res.data.title,
+            content: res.data.content,
+            links: res.data.links,
+          };
+          liveCacheable = true;
+        }
+        if (liveCacheable && isSafeKey(params.url)) {
+          cache.pages[params.url] = entry;
+          cacheStore.saveCache();
+        }
       }
-      if (!isFetchResponse(res.data)) {
-        throw new Error("Web fetch failed: unexpected response shape from the API.");
+
+      if (entry.error) {
+        throw new Error(
+          fetchFailureMessage(params.url, entry, live ? (liveCacheable ? "live-cached" : "live-uncached") : "cached"),
+        );
       }
 
-      const data = res.data;
-      const formatted = [
-        `Title: ${data.title}`,
-        "",
-        "Content:",
-        data.content,
-        "",
-        `Links found: ${data.links?.length ?? 0}`,
-        ...(data.links?.slice(0, 10).map((l) => `  - ${l}`) ?? []),
-      ].join("\n");
+      const content = entry.content ?? "";
+      const total = content.length;
+      const start = params.offset ?? 0;
+      const end = params.full ? total : Math.min(start + READ_CHUNK, total);
+      const lines = [
+        `Title: ${entry.title} (${total} chars total)`,
+        start >= total
+          ? "Already at the end, no more content."
+          : `Chars ${start + 1}-${end} of ${total}${end < total ? ` (${total - end} remaining)` : ""}:`,
+        content.slice(start, end),
+      ];
+      if (!params.full && end < total) {
+        lines.push(`\nContinue: call ollama_web_fetch(url="${params.url}", offset=${end})`);
+      }
+      if ((params.offset ?? 0) === 0 && !params.full) {
+        const links = entry.links ?? [];
+        lines.push(`\nLinks (${links.length}):`);
+        lines.push(...links.slice(0, 10).map((l) => `  - ${l}`));
+      }
+      lines.push(live ? "# live query" : "# from cache");
 
       return {
-        content: [{ type: "text", text: formatted }],
-        details: { title: data.title, content: data.content, links: data.links },
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { title: entry.title, totalChars: total, links: entry.links },
       };
     },
     renderCall(args, theme, _context) {