@mono-agent/agent-runtime 0.20.14 → 0.21.0

package/src/agent/tools/web-search.js

@@ -1,11 +1,22 @@
 // @ts-check
 
+import { withWebDeadline, coordinatedWebRequest, webRequestFailure } from "./web-request.js";
+import { isIP } from "node:net";
 import { parseHTML } from "linkedom";
 import { passthroughSandbox } from "../sandbox-seam.js";
 import { searchCodexSubscription } from "./codex-subscription-search.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
 import { createCountingSemaphore } from "./shared/semaphore.js";
 import { resolveSandboxPolicy } from "./shared/tool-context.js";
+import { renderBoundedWebSearchBody } from "./web-search-output.js";
+import {
+  claimWebSearchRequest,
+  createWebSearchRunState,
+  deferWebSearchProvider,
+  deferredWebSearchProvider,
+  MAX_WEB_SEARCH_REQUESTS_PER_RUN,
+  webSearchBudgetSnapshot,
+} from "./web-search-state.js";
 
 const SEARCH_TIMEOUT_MS = 15_000;
 const SEARCH_RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
@@ -56,6 +67,8 @@ let keylessSemaphore = createCountingSemaphore(keylessThrottle.maxConcurrency);
 const backendCooldownUntil = new Map();
 /** @type {Map<string, number>} Backend -> epoch ms its next request may start. */
 const backendNextAvailableAt = new Map();
+/** @type {Map<string, ReturnType<typeof createCountingSemaphore>>} */
+const processProviderSemaphores = new Map();
 const TRACKING_PARAMETERS = new Set([
   "dclid",
   "fbclid",
@@ -75,21 +88,33 @@ const TRACKING_PARAMETERS = new Set([
  * Compatibility wrapper for direct callers.
  *
  * @param {{query: string, limit?: number, alternate_queries?: string[], domains?: string[], exclude_domains?: string[], language?: string, time_range?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch}} [options]
+ * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, coordinator?: any, searchConfig?: any, fetchImpl?: typeof fetch}} [options]
  */
 export async function webSearchToolImpl(params, options = {}) {
   return (await performWebSearch(params, options)).text;
 }
 
+/**
+ * Search through an explicitly selected Ollama endpoint, an operator-owned
+ * SearXNG endpoint, ChatGPT-subscription Codex search, and/or the keyless HTML fallback chain. Returns a structured
+ * internal outcome for the Pi bridge.
+ *
+ * @param {{query: string, limit?: number, alternate_queries?: string[], domains?: string[], exclude_domains?: string[], language?: string, time_range?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, coordinator?: any, searchConfig?: any, searchState?: any, fetchImpl?: typeof fetch, codexSearch?: typeof searchCodexSubscription}} [options]
+ */
+export async function performWebSearch(params, options = {}) {
+  return await withWebDeadline(options.signal, 60_000, (signal) => performSearch(params, { ...options, signal }));
+}
+
 /**
  * Search through an operator-owned SearXNG endpoint, ChatGPT-subscription
  * Codex search, and/or the keyless HTML fallback chain. Returns a structured
  * internal outcome for the Pi bridge.
  *
  * @param {{query: string, limit?: number, alternate_queries?: string[], domains?: string[], exclude_domains?: string[], language?: string, time_range?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch, codexSearch?: typeof searchCodexSubscription}} [options]
+ * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, coordinator?: any, searchConfig?: any, searchState?: any, fetchImpl?: typeof fetch, codexSearch?: typeof searchCodexSubscription}} [options]
  */
-export async function performWebSearch(
+async function performSearch(
   {
     query,
     limit = 5,
@@ -104,21 +129,31 @@ export async function performWebSearch(
     ctx,
     signal,
     searchConfig,
+    searchState: suppliedSearchState,
+    coordinator,
     fetchImpl = globalThis.fetch,
     codexSearch = searchCodexSubscription,
   } = {},
 ) {
   const startedAt = Date.now();
+  const searchState = createWebSearchRunState(searchConfig, suppliedSearchState);
+  const callClaims = { requests: 0 };
   const normalizedQuery = typeof query === "string" ? query.trim() : "";
   if (!normalizedQuery) {
-    return failure("Error: WebSearch query must not be empty.", "invalid_query", startedAt);
+    return searchFailure("Error: WebSearch query must not be empty.", "invalid_query", startedAt, searchState, callClaims.requests);
   }
   const max = clampInteger(limit, 1, 10, 5);
   const explicitDomains = normalizeDomains(Array.isArray(domains) ? domains : []);
   const includeDomains = normalizeDomains([...explicitDomains, ...querySiteDomains(normalizedQuery)]);
   const excludeDomains = normalizeDomains(exclude_domains);
   const config = normalizeSearchConfig(searchConfig);
-  if (config.error) return failure(`Error: ${config.error}`, "invalid_search_config", startedAt);
+  if ("error" in config) return searchFailure(
+    `Error: ${config.error}`,
+    "code" in config ? config.code : "invalid_search_config",
+    startedAt,
+    searchState,
+    callClaims.requests,
+  );
 
   const resolvedCtx = ctx ?? readToolRuntime();
   const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
@@ -135,29 +170,42 @@ export async function performWebSearch(
   const actualQueries = [];
   let attempts = 0;
   let anyProviderSucceeded = false;
+  let queueWaitMs = 0;
+  let backendDurationMs = 0;
 
-  const runQuery = async (candidate, backend) => {
+  const runQuery = async (candidate, backend, stageSignal = signal) => {
     attempts += 1;
     attemptedBackends.add(backend);
     return await searchOneQuery(
       queryWithDomains(candidate, explicitDomains),
       {
         config: { ...config, backend },
+        coordinator,
+        relevanceQuery: normalizedQuery, includeDomains, excludeDomains,
+        auto: config.backend === "auto",
         language,
         timeRange: time_range,
         sandbox,
         policy,
-        signal,
+        signal: stageSignal,
         fetchImpl,
         codexSearch,
+        searchState,
+        callClaims,
+        maxResults: max,
       },
     );
   };
   const recordResult = (result) => {
+    queueWaitMs += result.coordinationWaitMs || 0;
+    backendDurationMs += result.backendDurationMs || 0;
     // Chain failures are reported even when a later backend rescued the query,
     // so a silent degradation to the fallback is still visible in the outcome.
     if (result.failures?.length) providerFailures.push(...result.failures);
     if (result.ok) {
+      if (typeof result.actualQuery === "string" && result.actualQuery.trim()) {
+        actualQueries.push(result.actualQuery.trim());
+      }
       const filtered = filterRelevantResults(
         filterByDomains(result.results, includeDomains, excludeDomains),
         normalizedQuery,
@@ -166,6 +214,7 @@ export async function performWebSearch(
         anyProviderSucceeded = true;
         providersUsed.add(result.backend);
         rankedLists.push(filtered);
+        return true;
       } else if (result.results.length === 0) {
         anyProviderSucceeded = true;
       } else {
@@ -177,40 +226,61 @@ export async function performWebSearch(
           relevance: true,
         });
       }
-      if (typeof result.actualQuery === "string" && result.actualQuery.trim()) {
-        actualQueries.push(result.actualQuery.trim());
-      }
     } else if (!result.failures?.length) {
       providerFailures.push(result);
     }
+    return false;
   };
 
-  const runStage = async (backend, candidates) => {
-    const results = await Promise.all(candidates.map((candidate) => runQuery(candidate, backend)));
-    results.forEach(recordResult);
-    return mergeRankedResults(rankedLists, max);
-  };
-
+  // A broad primary query walks the eligible provider chain before any
+  // alternate wording. Auto includes Ollama only when its block was explicitly
+  // configured; all named backend modes remain strict.
+  const eligibleBackends = config.backend === "auto"
+    ? [...(config.ollama ? ["ollama"] : []), ...(config.endpoint ? ["searxng"] : []), "codex", "keyless"]
+    : [config.backend];
+  const disabledForCall = new Set();
   let merged = [];
-  if (config.backend === "searxng" || (config.backend === "auto" && config.endpoint)) {
-    merged = await runStage("searxng", initialQueries);
-  }
-  if (config.backend === "codex" || (config.backend === "auto" && merged.length === 0)) {
-    // Exactly one subscription turn per WebSearch call. Alternate queries still
-    // help local/keyless rank fusion but never multiply paid subscription work.
-    merged = await runStage("codex", [normalizedQuery]);
-  }
-  if (config.backend === "keyless" || (config.backend === "auto" && merged.length === 0)) {
-    merged = await runStage("keyless", initialQueries);
+  for (let queryIndex = 0; queryIndex < initialQueries.length && merged.length === 0; queryIndex += 1) {
+    const candidate = initialQueries[queryIndex];
+    for (const backend of eligibleBackends) {
+      if (signal?.aborted || disabledForCall.has(backend)) continue;
+      // Subscription search remains exactly one turn per WebSearch call.
+      if (backend === "codex" && queryIndex > 0) continue;
+      const run = (stageSignal) => runQuery(candidate, backend, stageSignal);
+      const result = backend === "searxng" && config.backend === "auto"
+        ? await withWebDeadline(signal, 3000, run)
+        : await run(signal);
+      const usable = recordResult(result);
+      if (usable) {
+        merged = mergeRankedResults(rankedLists, max);
+        break;
+      }
+      if (!result.ok && !result.relevance) disabledForCall.add(backend);
+      if (providerFailures.some((entry) => ["coordination_unavailable", "search_budget_exhausted"].includes(entry.code))) break;
+    }
+    if (providerFailures.some((entry) => ["coordination_unavailable", "search_budget_exhausted"].includes(entry.code))) break;
   }
   if (signal?.aborted) {
-    return failure("Error: WebSearch was aborted.", "aborted", startedAt, {
+    return searchFailure("Error: WebSearch was aborted or exceeded its deadline.", signal.reason?.code === "deadline_exceeded" ? "deadline_exceeded" : "aborted", startedAt, searchState, callClaims.requests, {
       attempts,
       retryable: false,
     });
   }
 
-  if (!anyProviderSucceeded) {
+  if (providerFailures.some((r) => r.code === "coordination_unavailable")) {
+    return searchFailure("Error: Web request coordination is unavailable; no uncoordinated fallback was attempted.", "coordination_unavailable", startedAt, searchState, callClaims.requests, { attempts });
+  }
+  if (providerFailures.some((entry) => entry.code === "search_budget_exhausted")) {
+    return searchFailure("Error: WebSearch request budget exhausted for this run.", "search_budget_exhausted", startedAt, searchState, callClaims.requests, {
+      attempts,
+      backend: config.backend,
+      attemptedBackends: [...attemptedBackends],
+      providerAttempts: providerAttemptMetadata(providerFailures),
+      retryInRun: false,
+      nextAction: "use_available_evidence",
+    });
+  }
+  if (!anyProviderSucceeded || (merged.length === 0 && providerFailures.some((entry) => !entry.relevance))) {
     // Four query variants against two backends produce the same handful of
     // messages over and over; dedupe so the reason stays readable.
     const reason = [...new Set(providerFailures.map((entry) => entry.message).filter(Boolean))].join("; ")
@@ -218,30 +288,42 @@ export async function performWebSearch(
     const networkDenied = providerFailures.length > 0
       && providerFailures.every((entry) => entry.message === "Network access denied by sandbox policy.");
     const throttled = providerFailures.some((entry) => entry.rateLimited || entry.cooldown);
-    return failure(networkDenied
+    const strictProviderCode = config.backend !== "auto"
+      ? providerFailures.find((entry) => typeof entry.code === "string")?.code
+      : undefined;
+    const retryAfterMs = shortestRetry(providerFailures);
+    const retryAt = earliestRetryAt(providerFailures);
+    return searchFailure(networkDenied
       ? "Error: Network access denied by sandbox policy."
       : `Error: WebSearch failed: ${reason}`,
-    networkDenied ? "network_denied" : (throttled ? "rate_limited" : "backend_unavailable"), startedAt, {
+    networkDenied ? "network_denied" : (throttled ? "rate_limited" : (strictProviderCode || "backend_unavailable")), startedAt, searchState, callClaims.requests, {
       attempts,
       backend: config.backend,
       retryable: providerFailures.some((entry) => entry.retryable),
       rateLimited: throttled,
-      cooldownBackends: [...backendCooldownUntil.keys()],
+      cooldownBackends: cooldownBackendNames(searchState),
       attemptedBackends: [...attemptedBackends],
       failureMetadata: sanitizeFailureMetadata(providerFailures),
+      queueWaitMs, backendDurationMs,
+      cooldownSkipCount: providerFailures.filter((r) => r.cooldown).length,
+      quotaSkipCount: providerFailures.filter((r) => r.quotaSkipped).length,
+      retryAfterMs,
+      ...(retryAt === undefined ? {} : { retryAt: new Date(retryAt).toISOString() }),
+      retryInRun: false,
+      nextAction: "use_available_evidence",
+      providerAttempts: providerAttemptMetadata(providerFailures),
     });
   }
 
   const backend = providersUsed.size === 1
     ? [...providersUsed][0]
     : providersUsed.size > 1 ? "mixed" : config.backend;
-  const body = merged.length === 0
-    ? "No results."
-    : merged.map((result, index) => {
-        const snippet = result.snippet ? `\n   ${collapseWhitespace(result.snippet)}` : "";
-        return `${index + 1}. [${escapeMarkdownLabel(result.title || result.url)}](${result.url})${snippet}`;
-      }).join("\n\n");
+  const rendered = renderBoundedWebSearchBody(merged);
+  const nextAction = rendered.renderedResultCount > 0
+    ? "fetch_existing_sources"
+    : searchState.requestsUsed < searchState.maxRequests ? "refine_query" : "use_available_evidence";
   const text = [
+    searchControlLine(searchState, callClaims.requests, providerFailures, nextAction),
     "[BEGIN UNTRUSTED WEB SEARCH RESULTS]",
     searchMetadataLine({
       backend,
@@ -249,28 +331,38 @@ export async function performWebSearch(
       query: actualQueries[0] || normalizedQuery,
       providerFailures,
     }),
-    body,
+    ...(language || time_range ? [`[Requested filters: language=${JSON.stringify(collapseWhitespace(language || "default").slice(0, 100))}; time_range=${collapseWhitespace(time_range || "any").slice(0, 100)}; provider-dependent, verify dates in sources.]`] : []),
+    rendered.body,
     "[END UNTRUSTED WEB SEARCH RESULTS]",
   ].join("\n");
   return {
     text,
     outcome: {
       status: "ok",
-      code: merged.length === 0 ? "no_results" : "ok",
+      code: rendered.renderedResultCount === 0 ? "no_results" : "ok",
       retryable: false,
       attempts,
       backend,
       cacheHit: false,
       durationMs: Date.now() - startedAt,
       bytes: Buffer.byteLength(text, "utf8"),
-      truncated: false,
-      resultCount: merged.length,
+      truncated: rendered.truncated,
+      resultCount: rendered.renderedResultCount,
+      queueWaitMs, backendDurationMs,
+      cooldownSkipCount: providerFailures.filter((r) => r.cooldown).length,
+      quotaSkipCount: providerFailures.filter((r) => r.quotaSkipped).length,
+      filterSupport: { language: language ? (backend === "searxng" ? "provider" : "advisory") : "not_requested", timeRange: time_range ? (["codex", "ollama", "startpage"].includes(backend) ? "advisory" : "provider") : "not_requested" },
       providerFailureCount: providerFailures.length,
       rateLimited: providerFailures.some((entry) => entry.rateLimited || entry.cooldown),
-      cooldownBackends: [...backendCooldownUntil.keys()],
+      cooldownBackends: cooldownBackendNames(searchState),
       attemptedBackends: [...attemptedBackends],
       actualQueries: uniqueStrings(actualQueries.length > 0 ? actualQueries : [normalizedQuery], 4),
       failureMetadata: sanitizeFailureMetadata(providerFailures),
+      ...webSearchBudgetSnapshot(searchState, callClaims.requests),
+      fallbackUsed: attemptedBackends.size > 1,
+      retryInRun: searchState.requestsUsed < searchState.maxRequests,
+      nextAction,
+      providerAttempts: providerAttemptMetadata(providerFailures),
     },
     error: false,
   };
@@ -294,10 +386,20 @@ async function searchOneQuery(query, options) {
   let emptySuccess = null;
   if (options.signal?.aborted) return abortedSearch(config.backend, failures);
   if (config.backend === "searxng") {
-    const result = await searchSearxng(query, options);
-    return { ...result, failures };
+    const deferred = deferredResult(options.searchState, "searxng");
+    if (deferred) return { ...deferred, failures };
+    const result = await searchWithRequestCount(options.callClaims, () => guardedSearch("searxng", options.config.endpoint, options, () => searchSearxng(query, options)));
+    return { ...rememberProviderDeferral(result, options.searchState), failures };
+  }
+  if (config.backend === "ollama") {
+    const deferred = deferredResult(options.searchState, "ollama");
+    if (deferred) return { ...deferred, failures };
+    const result = await searchWithRequestCount(options.callClaims, () => guardedSearch("ollama", config.ollama.baseUrl, options, () => searchOllama(query, options)));
+    return { ...rememberProviderDeferral(result, options.searchState), failures };
   }
   if (config.backend === "codex") {
+    const deferred = deferredResult(options.searchState, "codex");
+    if (deferred) return { ...deferred, failures };
     if (!options.sandbox.networkAllowsUrl(options.policy, "https://chatgpt.com")) {
       return {
         ok: false,
@@ -307,15 +409,21 @@ async function searchOneQuery(query, options) {
         failures,
       };
     }
-    const result = await options.codexSearch(query, {
-      model: config.codex.model,
-      signal: options.signal,
-    });
-    return { ...result, failures };
+    const result = await searchWithRequestCount(options.callClaims, () => guardedSearch("codex", "codex", options, () => options.codexSearch(query, {
+      model: config.codex.model, signal: options.signal, coordinator: options.coordinator,
+      language: options.language, timeRange: options.timeRange,
+      claimRequest: () => claimWebSearchRequest(options.searchState, "codex", options.callClaims),
+    })));
+    return { ...rememberProviderDeferral(result, options.searchState), failures };
   }
   if (config.backend === "keyless") {
     for (const backend of KEYLESS_BACKENDS) {
       if (options.signal?.aborted) return abortedSearch(backend, failures);
+      const runDeferred = deferredResult(options.searchState, backend);
+      if (runDeferred) {
+        failures.push(runDeferred);
+        continue;
+      }
       if (backendInCooldown(backend)) {
         failures.push({
           ok: false,
@@ -323,17 +431,26 @@ async function searchOneQuery(query, options) {
           message: `${backend} skipped: cooling down after rate limiting.`,
           retryable: true,
           cooldown: true,
+          retryAfterMs: processCooldownRemaining(backend),
+          retryAtMs: Date.now() + processCooldownRemaining(backend),
         });
         continue;
       }
-      const result = await KEYLESS_RUNNERS[backend](query, options);
+      const result = await searchWithRequestCount(options.callClaims, () => guardedSearch(backend, backend, options, () => KEYLESS_RUNNERS[backend](query, options)));
+      rememberProviderDeferral(result, options.searchState);
       if (result.ok) {
-        if (result.results.length > 0) return { ...result, failures };
+        if (result.results.length > 0) {
+          const usable = filterRelevantResults(filterByDomains(result.results, options.includeDomains, options.excludeDomains), options.relevanceQuery);
+          if (usable.length > 0) return { ...result, results: usable, failures };
+          failures.push({ backend, message: `${backend} returned no relevant results.`, relevance: true });
+          continue;
+        }
         emptySuccess ??= result;
         continue;
       }
       // The cooldown is already open — rateLimited() sets it at detection.
       failures.push(result);
+      if (result.code === "coordination_unavailable") return { ...result, failures };
     }
   }
   if (emptySuccess) return { ...emptySuccess, failures };
@@ -348,6 +465,39 @@ async function searchOneQuery(query, options) {
   };
 }
 
+function deferredResult(searchState, backend) {
+  const deferred = deferredWebSearchProvider(searchState, backend);
+  if (!deferred) return null;
+  const retryAfterMs = deferred.retryAtMs === undefined ? undefined : Math.max(0, deferred.retryAtMs - Date.now());
+  return {
+    ok: false,
+    backend,
+    code: "rate_limited",
+    message: `${backend} is deferred for the remainder of this run.`,
+    retryable: true,
+    retryInRun: false,
+    cooldown: true,
+    rateLimited: true,
+    ...(retryAfterMs === undefined ? {} : { retryAfterMs, retryAtMs: deferred.retryAtMs }),
+  };
+}
+
+function rememberProviderDeferral(result, searchState) {
+  if (result?.rateLimited || result?.cooldown) {
+    const retryAtMs = Number.isFinite(result.retryAtMs)
+      ? result.retryAtMs
+      : Number.isFinite(result.retryAfterMs) ? Date.now() + result.retryAfterMs : undefined;
+    deferWebSearchProvider(searchState, result.backend, retryAtMs);
+  }
+  return result;
+}
+
+async function searchWithRequestCount(callClaims, execute) {
+  const before = callClaims.requests;
+  const result = await execute();
+  return { ...result, requestsConsumed: callClaims.requests - before };
+}
+
 function abortedSearch(backend, failures = []) {
   return {
     ok: false,
@@ -358,16 +508,25 @@ function abortedSearch(backend, failures = []) {
   };
 }
 
-function backendInCooldown(backend) {
-  const until = backendCooldownUntil.get(backend);
+function backendInCooldown(backend, key = backend) {
+  const cooldownKey = processCooldownKey(backend, key);
+  const until = backendCooldownUntil.get(cooldownKey);
   if (until === undefined) return false;
   if (Date.now() >= until) {
-    backendCooldownUntil.delete(backend);
+    backendCooldownUntil.delete(cooldownKey);
     return false;
   }
   return true;
 }
 
+function processCooldownKey(backend, key) {
+  return `${backend}:${String(key)}`;
+}
+
+function processCooldownRemaining(backend, key = backend) {
+  return Math.max(0, (backendCooldownUntil.get(processCooldownKey(backend, key)) ?? Date.now()) - Date.now());
+}
+
 /**
  * Atomically claims this backend's next send slot and reports how long the
  * caller must wait for it. Synchronous on purpose: concurrent callers each
@@ -414,6 +573,7 @@ export function __resetWebSearchThrottleForTests(overrides = {}) {
   keylessSemaphore = createCountingSemaphore(keylessThrottle.maxConcurrency);
   backendCooldownUntil.clear();
   backendNextAvailableAt.clear();
+  processProviderSemaphores.clear();
 }
 
 async function searchSearxng(query, options) {
@@ -433,6 +593,7 @@ async function searchSearxng(query, options) {
     body.set("time_range", options.timeRange);
   }
   try {
+    claimWebSearchRequest(options.searchState, "searxng", options.callClaims);
     const response = await options.fetchImpl(url, {
       method: "POST",
       headers: {
@@ -441,7 +602,7 @@ async function searchSearxng(query, options) {
         "User-Agent": "mono-agent-web/1",
       },
       body,
-      signal: requestSignal(options.signal),
+      signal: options.auto ? AbortSignal.any([options.signal, AbortSignal.timeout(3000)]) : requestSignal(options.signal),
       redirect: "error",
     });
     const text = await readLimitedText(response);
@@ -450,6 +611,7 @@ async function searchSearxng(query, options) {
         ok: false,
         backend: "searxng",
         message: `SearXNG HTTP ${response.status}`,
+        rateLimited: response.status === 429, retryAfterMs: parseRetryAfter(response),
         retryable: response.status === 429 || response.status >= 500,
       };
     }
@@ -493,6 +655,74 @@ async function searchSearxng(query, options) {
   }
 }
 
+async function searchOllama(query, options) {
+  const config = options.config.ollama;
+  if (!config) {
+    return { ok: false, backend: "ollama", message: "Ollama Web Search is not configured.", retryable: false };
+  }
+  const official = config.baseUrl === "https://ollama.com";
+  const paths = official ? ["/api/web_search"] : ["/api/experimental/web_search", "/api/web_search"];
+  for (let index = 0; index < paths.length; index += 1) {
+    const url = `${config.baseUrl}${paths[index]}`;
+    if (!options.sandbox.networkAllowsUrl(options.policy, url)) {
+      return { ok: false, backend: "ollama", message: "Network access denied by sandbox policy.", retryable: false };
+    }
+    try {
+      claimWebSearchRequest(options.searchState, "ollama", options.callClaims);
+      const response = await options.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          "User-Agent": "mono-agent-web/1",
+          ...(official ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+        },
+        body: JSON.stringify({ query, max_results: options.maxResults }),
+        signal: requestSignal(options.signal),
+        redirect: "error",
+      });
+      const text = await readLimitedText(response);
+      if (!official && index === 0 && [404, 405].includes(response.status)) continue;
+      if (!official && index === 1 && [404, 405].includes(response.status)) {
+        return { ok: false, backend: "ollama", code: "endpoint_not_supported", message: "Ollama Web Search endpoints are not supported by this server.", retryable: false };
+      }
+      if (!response.ok) {
+        return {
+          ok: false,
+          backend: "ollama",
+          code: [401, 403].includes(response.status) ? "auth_failed"
+            : response.status === 408 ? "timeout"
+              : response.status === 429 ? "rate_limited"
+              : response.status >= 500 ? "provider_unavailable" : "provider_unavailable",
+          message: `Ollama Web Search HTTP ${response.status}`,
+          rateLimited: response.status === 429,
+          retryAfterMs: parseRetryAfter(response),
+          retryable: [408, 429].includes(response.status) || response.status >= 500,
+        };
+      }
+      let data;
+      try { data = JSON.parse(text); } catch {
+        return { ok: false, backend: "ollama", code: "invalid_response", message: "Ollama Web Search returned invalid JSON.", retryable: false };
+      }
+      if (!Array.isArray(data?.results)) {
+        return { ok: false, backend: "ollama", code: "invalid_response", message: "Ollama Web Search returned no results array.", retryable: false };
+      }
+      const results = data.results.flatMap((entry) => normalizedResult(entry, "ollama"));
+      if (data.results.length > 0 && results.length === 0) {
+        return { ok: false, backend: "ollama", code: "invalid_response", message: "Ollama Web Search returned no usable result URLs.", retryable: false };
+      }
+      return {
+        ok: true,
+        backend: "ollama",
+        results,
+      };
+    } catch (error) {
+      return ollamaFetchFailure(error, options.signal);
+    }
+  }
+  return { ok: false, backend: "ollama", message: "Ollama Web Search endpoint is unavailable.", retryable: false };
+}
+
 /**
  * Shared transport for the keyless HTML engines. Both are scraped the same way
  * and both bot-gate the same way, so request shaping, throttling, challenge
@@ -518,7 +748,7 @@ async function keylessHtmlSearch(spec, options) {
     // so by the time this one is admitted a sibling may already have been
     // blocked. Without this second look the very first block still costs a full
     // round of requests against a backend we know is refusing them.
-    if (backendInCooldown(spec.backend)) {
+    if (backendInCooldown(spec.backend, spec.backend)) {
       return {
         ok: false,
         backend: spec.backend,
@@ -527,6 +757,7 @@ async function keylessHtmlSearch(spec, options) {
         cooldown: true,
       };
     }
+    claimWebSearchRequest(options.searchState, spec.backend, options.callClaims);
     const response = await options.fetchImpl(spec.url, {
       // "manual", not "error": these engines answer a throttled query with a
       // redirect to a captcha page, and "error" collapses that into an opaque
@@ -560,7 +791,7 @@ async function keylessHtmlSearch(spec, options) {
     // once it stops asking politely. No credentials are ever sent to these
     // endpoints, so a 403 can only mean "blocked", never "unauthorized".
     if (RATE_LIMIT_STATUSES.has(response.status)) {
-      return rateLimited(spec, `HTTP ${response.status}`);
+      return rateLimited(spec, `HTTP ${response.status}`, response);
     }
     if (!response.ok) {
       return {
@@ -589,7 +820,7 @@ function searchDuckDuckGo(query, options) {
   return keylessHtmlSearch({
     backend: "duckduckgo",
     label: "DuckDuckGo",
-    url: `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`,
+    url: `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}${({ day: "d", month: "m", year: "y" }[options.timeRange]) ? `&df=${({ day: "d", month: "m", year: "y" }[options.timeRange])}` : ""}`,
     parse: parseDuckDuckGoResults,
   }, options);
 }
@@ -619,12 +850,16 @@ function searchStartpage(query, options) {
 // do it. The semaphore slot is released before this result reaches the caller,
 // so a queued sibling would otherwise be admitted and re-check the cooldown
 // while it was still closed, and every variant in flight would hit the wire.
-function rateLimited(spec, detail) {
-  backendCooldownUntil.set(spec.backend, Date.now() + keylessThrottle.cooldownMs);
+function rateLimited(spec, detail, response) {
+  const retryAfterMs = parseRetryAfter(response) ?? keylessThrottle.cooldownMs;
+  const retryAtMs = Date.now() + retryAfterMs;
+  backendCooldownUntil.set(processCooldownKey(spec.backend, spec.backend), retryAtMs);
   return {
     ok: false,
     backend: spec.backend,
     message: `${spec.label} rate-limited (${detail})`,
+    retryAfterMs,
+    retryAtMs,
     retryable: true,
     rateLimited: true,
   };
@@ -755,13 +990,23 @@ export function mergeRankedResults(rankedLists, limit = 10) {
 
 function normalizeSearchConfig(input) {
   const backend = input?.backend ?? "auto";
-  if (!["auto", "searxng", "codex", "keyless"].includes(backend)) {
-    return { error: "Web search backend must be auto, searxng, codex, or keyless." };
+  if (!["auto", "searxng", "ollama", "codex", "keyless"].includes(backend)) {
+    return { error: "Web search backend must be auto, searxng, ollama, codex, or keyless." };
+  }
+  const maxRequestsPerRun = input?.maxRequestsPerRun ?? 4;
+  if (!Number.isSafeInteger(maxRequestsPerRun) || maxRequestsPerRun < 1 || maxRequestsPerRun > MAX_WEB_SEARCH_REQUESTS_PER_RUN) {
+    return { error: `Web search maxRequestsPerRun must be an integer from 1 to ${MAX_WEB_SEARCH_REQUESTS_PER_RUN}.` };
+  }
+  const legacyEndpoint = input?.endpoint;
+  const nestedEndpoint = input?.searxng?.endpoint;
+  if (legacyEndpoint && nestedEndpoint && String(legacyEndpoint).trim() !== String(nestedEndpoint).trim()) {
+    return { error: "Legacy and canonical SearXNG endpoints disagree." };
   }
   let endpoint;
-  if (input?.endpoint !== undefined && String(input.endpoint).trim()) {
+  const endpointInput = nestedEndpoint ?? legacyEndpoint;
+  if (endpointInput !== undefined && String(endpointInput).trim()) {
     try {
-      const parsed = new URL(String(input.endpoint));
+      const parsed = new URL(String(endpointInput));
       if (parsed.protocol !== "http:" || !isLoopbackHost(parsed.hostname) || parsed.username || parsed.password) {
         return { error: "SearXNG endpoint must be an unauthenticated loopback http URL." };
       }
@@ -775,15 +1020,64 @@ function normalizeSearchConfig(input) {
     }
   }
   if (backend === "searxng" && !endpoint) {
-    return { error: "SearXNG backend requires tools.web.search.endpoint." };
+    return { error: "SearXNG backend requires tools.web.search.searxng.endpoint." };
   }
+  const ollama = normalizeOllamaSearchConfig(input?.ollama, backend);
+  if (ollama.error) return {
+    error: ollama.error,
+    ...(ollama.code === undefined ? {} : { code: ollama.code }),
+  };
   const model = typeof input?.codex?.model === "string" && input.codex.model.trim()
     ? input.codex.model.trim()
     : "gpt-5.6-luna";
   if (model.length > 160 || /[\u0000-\u001f\u007f]/u.test(model)) {
     return { error: "Codex web search model must be a valid model id." };
   }
-  return { backend, endpoint, codex: { model } };
+  return { backend, maxRequestsPerRun, endpoint, ...(ollama.value === undefined ? {} : { ollama: ollama.value }), codex: { model } };
+}
+
+function normalizeOllamaSearchConfig(input, backend) {
+  if (backend !== "ollama" && input === undefined) return { value: undefined };
+  let parsed;
+  try { parsed = new URL(input?.baseUrl || "http://127.0.0.1:11434"); }
+  catch { return { error: "Ollama Web Search base URL must be a valid HTTP(S) origin." }; }
+  if (!["http:", "https:"].includes(parsed.protocol)
+    || parsed.username || parsed.password || parsed.search || parsed.hash
+    || !["", "/"].includes(parsed.pathname)) {
+    return { error: "Ollama Web Search base URL must be an HTTP(S) origin without credentials, path, query, or fragment." };
+  }
+  const baseUrl = parsed.origin;
+  const official = baseUrl === "https://ollama.com";
+  if (!official && !isPrivateOllamaOrigin(parsed) && (parsed.protocol !== "https:" || input?.trustPublicUrl !== true)) {
+    return { error: "A public custom Ollama origin requires HTTPS and trustPublicUrl=true." };
+  }
+  if (!official && (input?.apiKey !== undefined || input?.apiKeyEnv !== undefined)) {
+    return { error: "Ollama Web Search credentials are allowed only for the exact https://ollama.com origin." };
+  }
+  if (official && (typeof input?.apiKey !== "string" || input.apiKey.trim().length === 0)) {
+    return { error: "Hosted Ollama Web Search requires a resolved API key.", code: "auth_missing" };
+  }
+  return { value: {
+    baseUrl,
+    trustPublicUrl: input?.trustPublicUrl === true,
+    ...(official ? { apiKey: input.apiKey } : {}),
+    ...(typeof input?.apiKeyEnv === "string" ? { apiKeyEnv: input.apiKeyEnv } : {}),
+  } };
+}
+
+function isPrivateOllamaOrigin(url) {
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+  if (["localhost", "host.docker.internal", "::1"].includes(host)) return true;
+  if (isIP(host) === 4) {
+    const [a, b] = host.split(".").map(Number);
+    return a === 10 || a === 127 || (a === 192 && b === 168)
+      || (a === 172 && b >= 16 && b <= 31) || (a === 100 && b >= 64 && b <= 127);
+  }
+  if (isIP(host) === 6) {
+    const first = Number.parseInt(host.split(":")[0] || "0", 16);
+    return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80;
+  }
+  return false;
 }
 
 function isLoopbackHost(hostname) {
@@ -874,7 +1168,7 @@ function sanitizeFailureMetadata(failures) {
   const metadata = [];
   for (const failureEntry of failures) {
     const backend = collapseWhitespace(failureEntry?.backend).slice(0, 40) || "unknown";
-    const code = failureEntry?.relevance
+    const code = ["quota_reserved", "quota_unavailable", "coordination_unavailable", "search_budget_exhausted", "auth_failed", "invalid_response", "timeout", "provider_unavailable", "access_challenge"].includes(failureEntry?.code) ? failureEntry.code : failureEntry?.relevance
       ? "no_relevant_results"
       : failureEntry?.rateLimited ? "rate_limited"
         : failureEntry?.cooldown ? "cooldown"
@@ -890,6 +1184,55 @@ function sanitizeFailureMetadata(failures) {
   return metadata;
 }
 
+function providerAttemptMetadata(failures) {
+  return sanitizeFailureMetadata(failures).slice(0, 12).map((entry) => {
+    const source = failures.find((failureEntry) => collapseWhitespace(failureEntry?.backend).slice(0, 40) === entry.backend
+      && sanitizeFailureMetadata([failureEntry])[0]?.code === entry.code);
+    const retryAtMs = Number.isFinite(source?.retryAtMs)
+      ? source.retryAtMs
+      : Number.isFinite(source?.retryAfterMs) ? Date.now() + source.retryAfterMs : undefined;
+    return {
+      backend: entry.backend,
+      code: entry.code,
+      disposition: source?.cooldown || source?.rateLimited ? "deferred_for_run" : "advanced",
+      requests: Number.isSafeInteger(source?.requestsConsumed)
+        ? source.requestsConsumed
+        : source?.cooldown || source?.quotaSkipped ? 0 : 1,
+      ...(Number.isFinite(source?.retryAfterMs) ? { retryAfterMs: source.retryAfterMs } : {}),
+      ...(retryAtMs === undefined ? {} : { retryAt: new Date(retryAtMs).toISOString() }),
+    };
+  });
+}
+
+function earliestRetryAt(failures) {
+  const values = failures.flatMap((entry) => {
+    if (Number.isFinite(entry.retryAtMs)) return [entry.retryAtMs];
+    if (Number.isFinite(entry.retryAfterMs)) return [Date.now() + entry.retryAfterMs];
+    return [];
+  }).filter((value) => value >= 0 && value <= 8_640_000_000_000_000);
+  return values.length ? Math.min(...values) : undefined;
+}
+
+function cooldownBackendNames(searchState) {
+  const processNames = [...backendCooldownUntil.keys()].map((key) => key.split(":", 1)[0]);
+  const runNames = [...(searchState?.deferredProviders?.keys?.() ?? [])];
+  return [...new Set([...processNames, ...runNames])];
+}
+
+function searchControlLine(searchState, requestsThisCall, providerFailures, nextAction) {
+  const budget = webSearchBudgetSnapshot(searchState, requestsThisCall);
+  const deferred = providerFailures.filter((entry) => entry.rateLimited || entry.cooldown).map((entry) => entry.backend);
+  const deferText = deferred.length > 0
+    ? ` ${[...new Set(deferred)].join(", ")} deferred for the remainder of this run.`
+    : "";
+  const action = nextAction === "fetch_existing_sources"
+    ? "Use WebFetch on the strongest returned URLs before searching again."
+    : nextAction === "refine_query"
+      ? "Refine the query only for a material evidence gap."
+      : "Do not retry WebSearch in this run; use available evidence and state the limitation.";
+  return `[Search control: requests=${budget.requestsUsed}/${budget.maxRequestsPerRun}; remaining=${budget.requestsRemaining};${deferText} ${action}]`;
+}
+
 function searchMetadataLine({ backend, attemptedBackends, query, providerFailures }) {
   const attempted = attemptedBackends.join(",") || "none";
   const failures = sanitizeFailureMetadata(providerFailures)
@@ -928,7 +1271,7 @@ async function readLimitedText(response) {
   if (!reader) {
     const text = await response.text();
     if (Buffer.byteLength(text, "utf8") > SEARCH_RESPONSE_MAX_BYTES) {
-      throw new Error(`search response exceeded ${SEARCH_RESPONSE_MAX_BYTES} bytes`);
+      throw Object.assign(new Error(`search response exceeded ${SEARCH_RESPONSE_MAX_BYTES} bytes`), { code: "response_too_large" });
     }
     return text;
   }
@@ -940,7 +1283,7 @@ async function readLimitedText(response) {
     bytes += next.value.byteLength;
     if (bytes > SEARCH_RESPONSE_MAX_BYTES) {
       try { await reader.cancel(); } catch { /* best effort */ }
-      throw new Error(`search response exceeded ${SEARCH_RESPONSE_MAX_BYTES} bytes`);
+      throw Object.assign(new Error(`search response exceeded ${SEARCH_RESPONSE_MAX_BYTES} bytes`), { code: "response_too_large" });
     }
     chunks.push(Buffer.from(next.value));
   }
@@ -965,9 +1308,10 @@ const RETRYABLE_FETCH_CODES = new Set([
 
 function fetchFailure(backend, error, label = backend) {
   const name = error?.name;
-  const retryable = name === "AbortError"
+  const code = error?.code ?? error?.cause?.code;
+  const retryable = code !== "search_budget_exhausted" && (name === "AbortError"
     || name === "TimeoutError"
-    || RETRYABLE_FETCH_CODES.has(error?.code ?? error?.cause?.code);
+    || RETRYABLE_FETCH_CODES.has(code));
   const message = error?.message || String(error);
   const cause = error?.cause?.message;
   const detail = cause && cause !== message ? `${message} (${cause})` : message;
@@ -976,6 +1320,28 @@ function fetchFailure(backend, error, label = backend) {
     backend,
     message: `${label} request failed: ${detail}`,
     retryable,
+    ...(code === undefined ? {} : { code }),
+  };
+}
+
+function ollamaFetchFailure(error, signal) {
+  const base = fetchFailure("ollama", error, "Ollama Web Search");
+  const abortCode = signal?.aborted
+    ? (signal.reason?.code === "deadline_exceeded" ? "deadline_exceeded" : "aborted")
+    : undefined;
+  const suppliedCode = error?.code ?? error?.cause?.code;
+  const code = abortCode
+    || (suppliedCode === "search_budget_exhausted" ? "search_budget_exhausted" : undefined)
+    || (suppliedCode === "deadline_exceeded" ? "deadline_exceeded" : undefined)
+    || (suppliedCode === "response_too_large" ? "response_too_large" : undefined)
+    || (suppliedCode === "invalid_response" ? "invalid_response" : undefined)
+    || (error?.name === "AbortError" ? "aborted" : undefined)
+    || (error?.name === "TimeoutError" ? "timeout" : undefined)
+    || "provider_unavailable";
+  return {
+    ...base,
+    code,
+    retryable: !["aborted", "response_too_large", "invalid_response", "search_budget_exhausted"].includes(code),
   };
 }
 
@@ -998,8 +1364,103 @@ function failure(text, code, startedAt, extra = {}) {
   };
 }
 
+function searchFailure(text, code, startedAt, searchState, requestsThisCall, extra = {}) {
+  const budget = webSearchBudgetSnapshot(searchState, requestsThisCall);
+  const retryAfterMs = extra.retryAfterMs;
+  const retryAt = extra.retryAt;
+  const guidance = code === "rate_limited"
+    ? `Provider retry${Number.isFinite(retryAfterMs) ? ` after ${Math.ceil(retryAfterMs / 1000)} seconds` : " time is unknown"}${retryAt ? `, at ${retryAt}` : ""}. Do not sleep or retry WebSearch to wait out this cooldown in this run. Fetch already returned URLs, or answer from available evidence and state the limitation.`
+    : code === "search_budget_exhausted"
+      ? "Do not retry WebSearch in this run. Fetch already returned URLs, or answer from available evidence and state the limitation."
+      : "";
+  const completeText = guidance
+    ? `${text}\n${guidance}\nSearch requests used: ${budget.requestsUsed}/${budget.maxRequestsPerRun}.`
+    : text;
+  return failure(completeText, code, startedAt, {
+    ...extra,
+    ...budget,
+    retryInRun: extra.retryInRun ?? false,
+    nextAction: extra.nextAction ?? "use_available_evidence",
+    bytes: Buffer.byteLength(completeText, "utf8"),
+  });
+}
+
 function clampInteger(value, min, max, fallback) {
   const number = Number(value);
   if (!Number.isFinite(number)) return fallback;
   return Math.max(min, Math.min(max, Math.floor(number)));
 }
+
+async function guardedSearch(kind, key, options, execute) {
+  try {
+    if (options.coordinator || !["ollama", "searxng"].includes(kind)) {
+      return await coordinatedWebRequest(options.coordinator, kind, key, options.signal, execute);
+    }
+    const cooldown = processCooldownRemaining(kind, key);
+    if (cooldown > 0) return processCooldownResult(kind, cooldown);
+    const scopedKey = processCooldownKey(kind, key);
+    let semaphore = processProviderSemaphores.get(scopedKey);
+    if (!semaphore) {
+      semaphore = createCountingSemaphore(1);
+      processProviderSemaphores.set(scopedKey, semaphore);
+    }
+    const release = await semaphore.acquire(options.signal);
+    try {
+      const queuedCooldown = processCooldownRemaining(kind, key);
+      if (queuedCooldown > 0) return processCooldownResult(kind, queuedCooldown);
+      const result = await execute();
+      if (result?.rateLimited) {
+        const retryAfterMs = result.retryAfterMs ?? keylessThrottle.cooldownMs;
+        const retryAtMs = Date.now() + retryAfterMs;
+        backendCooldownUntil.set(scopedKey, retryAtMs);
+        return { ...result, retryAfterMs, retryAtMs };
+      }
+      return result;
+    } finally {
+      release();
+    }
+  }
+  catch (error) { return webRequestFailure(error, kind, options.signal); }
+}
+
+function processCooldownResult(backend, retryAfterMs) {
+  return {
+    ok: false,
+    backend,
+    code: "rate_limited",
+    message: `${backend} is cooling down.`,
+    retryable: true,
+    cooldown: true,
+    rateLimited: true,
+    retryAfterMs,
+    retryAtMs: Date.now() + retryAfterMs,
+  };
+}
+
+function parseRetryAfter(response) {
+  const raw = response?.headers?.get("retry-after");
+  if (!raw) return undefined;
+  const now = Date.now();
+  const value = raw.trim();
+  let ms;
+  if (/^\d+$/u.test(value)) {
+    const seconds = Number(value);
+    if (!Number.isSafeInteger(seconds)) return undefined;
+    ms = seconds * 1000;
+  } else {
+    // Retry-After allows only an integer delta-seconds or an HTTP date. Do not
+    // let Date.parse reinterpret malformed numeric values such as "1.5" as a
+    // calendar date.
+    if (/^[+-]?(?:\d+\.?\d*|\.\d+)$/u.test(value)) return undefined;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed)) return undefined;
+    ms = parsed - now;
+  }
+  if (!Number.isFinite(ms)) return undefined;
+  return Math.min(8_640_000_000_000_000 - now, Math.max(1000, ms));
+}
+
+function shortestRetry(failures) {
+  const waits = failures.map((r) => r.retryAfterMs).filter((n) => Number.isFinite(n) && n > 0);
+  return waits.length ? Math.min(...waits) : undefined;
+}