one-code-extension 0.1.4 → 0.3.0

package/extensions/web/backends.ts

@@ -0,0 +1,421 @@
+/**
+ * Third-party search backends for `web_search` (pure — no pi imports).
+ *
+ * `pi-web-search` only speaks the model provider's *own* search API, so on any
+ * provider without one (every `openai-completions` model: OpenRouter, Z.ai,
+ * Copilot chat, Ollama, DeepSeek direct) `web_search` used to fail outright.
+ * This module is the fallback chain that runs there: Brave and Tavily when the
+ * user has a key, else Exa's keyless hosted MCP endpoint, which is rate-limited
+ * and best-effort and is therefore always labelled as such in the result (and,
+ * once per session, to the user — index.ts). Findings §12 has the survey that
+ * picked these three and the live probes behind the "keyless" claim.
+ *
+ * Every backend takes `fetch` as a parameter so the chain is unit-testable
+ * without the network; nothing here reads the environment or the file system
+ * directly — `resolveChain` is handed `env` and the parsed settings.
+ */
+
+export interface SearchResult {
+	title: string;
+	url: string;
+	snippet: string;
+}
+
+export interface DomainFilters {
+	allowed?: string[];
+	blocked?: string[];
+}
+
+export type BackendName = "brave" | "tavily" | "exa-free";
+
+export interface SearchBackend {
+	readonly name: BackendName;
+	readonly label: string;
+	/** True for the keyless route — the result carries the free-tier warning. */
+	readonly keyless: boolean;
+	search(
+		query: string,
+		filters: DomainFilters,
+		maxResults: number,
+		signal: AbortSignal | undefined,
+	): Promise<SearchResult[]>;
+}
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** `webSearch` block of `~/.onecode/settings.json` (One Code's own key). */
+export interface WebSearchSettings {
+	/** Backend order, e.g. `["tavily", "brave", "exa-free"]`. Unknown names are ignored. */
+	order?: BackendName[];
+	apiKeys?: { brave?: string; tavily?: string };
+}
+
+export const BRAVE_KEY_ENV = "BRAVE_SEARCH_API_KEY";
+export const TAVILY_KEY_ENV = "TAVILY_API_KEY";
+export const DEFAULT_MAX_RESULTS = 10;
+export const BACKEND_TIMEOUT_MS = 30_000;
+
+const BRAVE_URL = "https://api.search.brave.com/res/v1/web/search";
+const TAVILY_URL = "https://api.tavily.com/search";
+export const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+const BACKEND_NAMES: readonly BackendName[] = ["brave", "tavily", "exa-free"];
+
+/** The one-line settings snippet both warnings point at: the fix, spelled out. */
+export const SETTINGS_SNIPPET = '{ "webSearch": { "apiKeys": { "brave": "<key>" } } }';
+export const SETTINGS_FILE = "~/.onecode/settings.json";
+/** The advice both warnings share: where a key goes and that the keyed backends have free tiers. */
+const KEYLESS_ADVICE =
+	`add ${SETTINGS_SNIPPET} (or "tavily") to ${SETTINGS_FILE}, or set ${BRAVE_KEY_ENV} / ${TAVILY_KEY_ENV} in the environment. ` +
+	"Brave and Tavily both have free tiers.";
+
+/**
+ * Model-facing warning attached to every keyless result: the model should know
+ * these results are best-effort and what the user can configure instead.
+ */
+export const KEYLESS_NOTE =
+	"Note: these results came from Exa's free keyless endpoint (rate-limited, best-effort) because no search API key is configured. " +
+	`For reliable search the user can ${KEYLESS_ADVICE}`;
+
+/** User-facing one-time notice (TUI) the first time a session searches keyless. */
+export const KEYLESS_USER_NOTICE =
+	"web_search used Exa's free keyless endpoint (rate-limited, best-effort): this provider has no native web search and no search API key is configured. " +
+	`For reliable results ${KEYLESS_ADVICE}`;
+
+// ---------------------------------------------------------------------------
+// Settings + chain resolution
+// ---------------------------------------------------------------------------
+
+/** Parse the `webSearch` value of a settings file leniently: bad shapes become an empty setting, never a throw. */
+export function webSearchSettingsFrom(raw: unknown): WebSearchSettings {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const value = raw as Record<string, unknown>;
+	const settings: WebSearchSettings = {};
+	if (Array.isArray(value.order)) {
+		const order = value.order.filter((n): n is BackendName => typeof n === "string" && (BACKEND_NAMES as string[]).includes(n));
+		if (order.length) settings.order = order;
+	}
+	if (value.apiKeys && typeof value.apiKeys === "object" && !Array.isArray(value.apiKeys)) {
+		const keys = value.apiKeys as Record<string, unknown>;
+		const apiKeys: WebSearchSettings["apiKeys"] = {};
+		if (typeof keys.brave === "string" && keys.brave.trim()) apiKeys.brave = keys.brave.trim();
+		if (typeof keys.tavily === "string" && keys.tavily.trim()) apiKeys.tavily = keys.tavily.trim();
+		if (Object.keys(apiKeys).length) settings.apiKeys = apiKeys;
+	}
+	return settings;
+}
+
+/**
+ * The backends that can run right now, in order. Env vars win over settings
+ * keys (the ecosystem-wide convention). Default order: keyed backends first
+ * (Brave, then Tavily), keyless Exa last — a configured key means the user
+ * chose reliability, so the free route is only ever the last resort. A settings
+ * `order` reorders the *available* backends; a keyed backend named there
+ * without a key is skipped, and anything not named keeps its default place
+ * after the named ones.
+ */
+export function resolveChain(
+	env: Record<string, string | undefined>,
+	settings: WebSearchSettings,
+	fetchImpl: FetchLike = globalThis.fetch,
+): SearchBackend[] {
+	const braveKey = env[BRAVE_KEY_ENV]?.trim() || settings.apiKeys?.brave;
+	const tavilyKey = env[TAVILY_KEY_ENV]?.trim() || settings.apiKeys?.tavily;
+	const available = new Map<BackendName, SearchBackend>();
+	if (braveKey) available.set("brave", braveBackend(braveKey, fetchImpl));
+	if (tavilyKey) available.set("tavily", tavilyBackend(tavilyKey, fetchImpl));
+	available.set("exa-free", exaFreeBackend(fetchImpl));
+
+	const order = [...(settings.order ?? []), ...BACKEND_NAMES];
+	const chain: SearchBackend[] = [];
+	for (const name of order) {
+		const backend = available.get(name);
+		if (backend && !chain.includes(backend)) chain.push(backend);
+	}
+	return chain;
+}
+
+// ---------------------------------------------------------------------------
+// Domain filters (Claude Code's allowed_domains / blocked_domains)
+// ---------------------------------------------------------------------------
+
+function hostOf(url: string): string | undefined {
+	try {
+		return new URL(url).hostname.toLowerCase();
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeDomain(domain: string): string {
+	return domain
+		.trim()
+		.toLowerCase()
+		.replace(/^https?:\/\//, "")
+		.replace(/^www\./, "")
+		.replace(/\/.*$/, "");
+}
+
+function hostMatches(host: string, domain: string): boolean {
+	const bare = host.replace(/^www\./, "");
+	return bare === domain || bare.endsWith(`.${domain}`);
+}
+
+function normalizedDomains(list: string[] | undefined): string[] {
+	return (list ?? []).map(normalizeDomain).filter(Boolean);
+}
+
+/** Keep results whose host is under an allowed domain (when any are given) and under no blocked domain. */
+export function filterByDomains(results: SearchResult[], filters: DomainFilters): SearchResult[] {
+	const allowed = normalizedDomains(filters.allowed);
+	const blocked = normalizedDomains(filters.blocked);
+	if (!allowed.length && !blocked.length) return results;
+	return results.filter((result) => {
+		const host = hostOf(result.url);
+		if (!host) return false;
+		if (blocked.some((d) => hostMatches(host, d))) return false;
+		return !allowed.length || allowed.some((d) => hostMatches(host, d));
+	});
+}
+
+/**
+ * Express the filters as `site:` operators for engines that take them in the
+ * query (Brave, and the provider-native path, which has no filter parameters
+ * of its own). Post-filtering still applies afterwards — the operators only
+ * make the engine return relevant pages instead of pages we then drop.
+ */
+export function withSiteOperators(query: string, filters: DomainFilters): string {
+	const allowed = normalizedDomains(filters.allowed);
+	const blocked = normalizedDomains(filters.blocked);
+	const parts = [query.trim()];
+	if (allowed.length === 1) parts.push(`site:${allowed[0]}`);
+	else if (allowed.length > 1) parts.push(`(${allowed.map((d) => `site:${d}`).join(" OR ")})`);
+	for (const domain of blocked) parts.push(`-site:${domain}`);
+	return parts.join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// Backends
+// ---------------------------------------------------------------------------
+
+function timeoutSignal(signal: AbortSignal | undefined): AbortSignal {
+	const timeout = AbortSignal.timeout(BACKEND_TIMEOUT_MS);
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+/** The error body, whole: it lands in the tool result, which the caller persists when large (never a bare slice). */
+async function errorBody(response: Response): Promise<string> {
+	try {
+		const text = (await response.text()).trim();
+		return text ? `: ${text}` : "";
+	} catch {
+		return "";
+	}
+}
+
+/** Throw a labelled error for a failed keyed-API response; 401/403 name the env var to check. */
+async function assertOk(response: Response, apiName: string, keyEnv: string): Promise<void> {
+	if (response.ok) return;
+	const hint = response.status === 401 || response.status === 403 ? ` (check ${keyEnv})` : "";
+	throw new Error(`${apiName} HTTP ${response.status}${hint}${await errorBody(response)}`);
+}
+
+/** Map a provider's rows onto SearchResult, reading the snippet from `snippetKey`; rows without a url are dropped. */
+function toResults(rows: unknown, snippetKey: string): SearchResult[] {
+	if (!Array.isArray(rows)) return [];
+	return (rows as Array<Record<string, unknown>>)
+		.map((r) => ({
+			title: typeof r.title === "string" ? r.title : "",
+			url: typeof r.url === "string" ? r.url : "",
+			snippet: typeof r[snippetKey] === "string" ? (r[snippetKey] as string) : "",
+		}))
+		.filter((r) => r.url);
+}
+
+/** Brave Search API — `X-Subscription-Token`; `web.results[]` of title/url/description. */
+export function parseBrave(body: unknown): SearchResult[] {
+	return toResults((body as { web?: { results?: unknown } } | undefined)?.web?.results, "description");
+}
+
+export function braveBackend(apiKey: string, fetchImpl: FetchLike): SearchBackend {
+	return {
+		name: "brave",
+		label: "Brave Search",
+		keyless: false,
+		async search(query, filters, maxResults, signal) {
+			const url = new URL(BRAVE_URL);
+			url.searchParams.set("q", withSiteOperators(query, filters));
+			url.searchParams.set("count", String(Math.min(maxResults, 20)));
+			const response = await fetchImpl(url.toString(), {
+				headers: { accept: "application/json", "x-subscription-token": apiKey },
+				signal: timeoutSignal(signal),
+			});
+			await assertOk(response, "Brave Search API", BRAVE_KEY_ENV);
+			return filterByDomains(parseBrave(await response.json()), filters);
+		},
+	};
+}
+
+/** Tavily — Bearer key; `results[]` of title/url/content, native include/exclude domains. */
+export function parseTavily(body: unknown): SearchResult[] {
+	return toResults((body as { results?: unknown } | undefined)?.results, "content");
+}
+
+export function tavilyBackend(apiKey: string, fetchImpl: FetchLike): SearchBackend {
+	return {
+		name: "tavily",
+		label: "Tavily",
+		keyless: false,
+		async search(query, filters, maxResults, signal) {
+			const body: Record<string, unknown> = { query, max_results: Math.min(maxResults, 20) };
+			if (filters.allowed?.length) body.include_domains = normalizedDomains(filters.allowed);
+			if (filters.blocked?.length) body.exclude_domains = normalizedDomains(filters.blocked);
+			const response = await fetchImpl(TAVILY_URL, {
+				method: "POST",
+				headers: { "content-type": "application/json", accept: "application/json", authorization: `Bearer ${apiKey}` },
+				body: JSON.stringify(body),
+				signal: timeoutSignal(signal),
+			});
+			await assertOk(response, "Tavily API", TAVILY_KEY_ENV);
+			return filterByDomains(parseTavily(await response.json()), filters);
+		},
+	};
+}
+
+/**
+ * Exa's hosted MCP server, keyless. One JSON-RPC `tools/call` of `web_search_exa`
+ * (no `initialize` handshake needed — verified live 2026-09-09); the reply is
+ * either JSON or a one-message SSE stream, and the tool's text is a list of
+ * blocks separated by `---`:
+ *
+ *   Title: …\nURL: …\nPublished: …\nAuthor: …\nHighlights:\n…
+ */
+export function parseExaMcpText(text: string): SearchResult[] {
+	const results: SearchResult[] = [];
+	for (const block of text.split(/\n\s*---\s*\n/)) {
+		const title = block.match(/^Title:\s*(.*)$/m)?.[1]?.trim() ?? "";
+		const url = block.match(/^URL:\s*(\S+)/m)?.[1]?.trim() ?? "";
+		if (!url) continue;
+		const highlights = block.split(/^Highlights:\s*$/m)[1] ?? "";
+		const snippet = highlights
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line && line !== "...")
+			.join(" ")
+			.replace(/\s+/g, " ")
+			.trim();
+		results.push({ title, url, snippet });
+	}
+	return results;
+}
+
+/** The JSON-RPC message out of an MCP response body (plain JSON, or the last `data:` line of SSE). */
+export function parseMcpResponseBody(body: string, contentType: string): unknown {
+	const trimmed = body.trim();
+	if (!contentType.includes("text/event-stream")) return JSON.parse(trimmed);
+	const dataLines = trimmed
+		.split("\n")
+		.filter((line) => line.startsWith("data:"))
+		.map((line) => line.slice(5).trim())
+		.filter(Boolean);
+	if (!dataLines.length) throw new Error("Exa MCP returned an event stream with no data");
+	return JSON.parse(dataLines[dataLines.length - 1]);
+}
+
+export function exaFreeBackend(fetchImpl: FetchLike): SearchBackend {
+	let nextId = 1;
+	return {
+		name: "exa-free",
+		label: "Exa (free keyless endpoint)",
+		keyless: true,
+		async search(query, filters, maxResults, signal) {
+			const response = await fetchImpl(EXA_MCP_URL, {
+				method: "POST",
+				headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+				body: JSON.stringify({
+					jsonrpc: "2.0",
+					id: nextId++,
+					method: "tools/call",
+					params: { name: "web_search_exa", arguments: { query, numResults: Math.min(maxResults, 20) } },
+				}),
+				signal: timeoutSignal(signal),
+			});
+			if (response.status === 429) {
+				throw new Error("Exa free endpoint rate-limited the request (HTTP 429); retry shortly or configure a keyed backend");
+			}
+			if (!response.ok) throw new Error(`Exa MCP HTTP ${response.status}${await errorBody(response)}`);
+			const message = parseMcpResponseBody(await response.text(), response.headers.get("content-type") ?? "") as {
+				error?: { message?: string };
+				result?: { isError?: boolean; content?: Array<{ type: string; text?: string }> };
+			};
+			if (message.error) throw new Error(`Exa MCP error: ${message.error.message ?? JSON.stringify(message.error)}`);
+			const text = (message.result?.content ?? [])
+				.filter((c) => c.type === "text" && typeof c.text === "string")
+				.map((c) => c.text as string)
+				.join("\n");
+			if (message.result?.isError) throw new Error(`Exa MCP tool error: ${text || "(no detail)"}`);
+			return filterByDomains(parseExaMcpText(text), filters);
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Chain execution + result text
+// ---------------------------------------------------------------------------
+
+export interface ChainOutcome {
+	backend: SearchBackend;
+	results: SearchResult[];
+	/** `label: error` for every backend tried before this one. */
+	failures: string[];
+}
+
+/**
+ * Try each backend in order until one returns; a backend that throws is
+ * recorded and the next one runs. A cancellation stops the whole chain. When
+ * every backend fails the error names each attempt so the fix is visible.
+ */
+export async function runChain(
+	chain: SearchBackend[],
+	query: string,
+	filters: DomainFilters,
+	maxResults: number,
+	signal: AbortSignal | undefined,
+): Promise<ChainOutcome> {
+	const failures: string[] = [];
+	for (const backend of chain) {
+		if (signal?.aborted) throw new Error("Search was cancelled.");
+		try {
+			const results = await backend.search(query, filters, maxResults, signal);
+			return { backend, results, failures };
+		} catch (error) {
+			if (signal?.aborted) throw new Error("Search was cancelled.");
+			failures.push(`${backend.label}: ${(error as Error).message}`);
+		}
+	}
+	throw new Error(`Every search backend failed:\n- ${failures.join("\n- ")}`);
+}
+
+/**
+ * Claude Code's WebSearch returns "result blocks with titles and URLs"; this is
+ * that shape, with the backend named so the model can report its source and,
+ * on the keyless route, the configuration note.
+ */
+export function formatSearchResults(query: string, outcome: ChainOutcome): string {
+	const lines: string[] = [];
+	lines.push(`Search results for "${query}" (via ${outcome.backend.label}):`);
+	if (outcome.failures.length) lines.push(`Fell back after: ${outcome.failures.join("; ")}`);
+	if (outcome.backend.keyless) lines.push(KEYLESS_NOTE);
+	lines.push("");
+	if (!outcome.results.length) {
+		lines.push("No results.");
+	} else {
+		outcome.results.forEach((result, index) => {
+			lines.push(`${index + 1}. ${result.title || result.url}`);
+			lines.push(`   ${result.url}`);
+			if (result.snippet) lines.push(`   ${result.snippet}`);
+			lines.push("");
+		});
+		lines.push('After answering from these results, end with a "Sources:" list of the URLs you used as markdown links.');
+	}
+	return lines.join("\n").trimEnd();
+}

package/extensions/web/index.ts

@@ -1,33 +1,168 @@
 /**
  * web extension — Claude Code's WebSearch role.
  *
- * `web_search` comes from the community `pi-web-search` package, which calls the
- * *current model provider's own* search API (OpenAI/Codex, Anthropic, Gemini) —
- * no third-party key, and as close to Claude Code's server-side search as an
- * extension can get. It also registers Gemini-only `url_context`.
+ * `web_search` is registered here with Claude Code's schema (`query`,
+ * `allowed_domains`, `blocked_domains`) and routes by what the session can do:
  *
- * WebFetch lives in `extensions/web-fetch` (our own); this file only owns search.
+ *   1. Provider-native search through the community `pi-web-search` package
+ *      when the current model's provider has one (Anthropic, OpenAI/Codex,
+ *      Gemini, xAI) — no third-party key, and as close to Claude Code's
+ *      server-side search as an extension can get.
+ *   2. Otherwise the third-party chain in backends.ts: Brave, then Tavily when
+ *      the user has a key (env var or `webSearch.apiKeys` in
+ *      ~/.onecode/settings.json), and Exa's keyless hosted endpoint as the last
+ *      resort — labelled in every result and announced once to the user, so a
+ *      best-effort free route never passes for a configured one.
+ *
+ * pi-web-search's own registration still runs first: it wires the Gemini-only
+ * `url_context` tool and the active-tools sync that hides it on non-Gemini
+ * models. Its `web_search` is then overridden by ours — pi keeps one tool per
+ * name per extension (`extension.tools.set(name, …)`), so a second
+ * `registerTool` from the same extension replaces the vendor's entry.
  *
- * Note: pi-web-search drives `setActiveTools` to hide `url_context` on non-Gemini
- * models. That composes with our deferral only because `tool-search` loads first
- * and therefore deactivates deferred tools before this package snapshots the
- * active set. Keep that ordering.
+ * WebFetch lives in `extensions/web-fetch` (our own); this file only owns search.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import webSearch from "pi-web-search/src/index.ts";
+import { homedir } from "node:os";
+import { Type } from "typebox";
+import webSearchPackage from "pi-web-search/src/index.ts";
+import { getProviderKind } from "pi-web-search/src/api.ts";
+import { webSearch as nativeWebSearch } from "pi-web-search/src/web_search.ts";
+import { getWebSearchModel } from "pi-web-search/src/utils.ts";
+import { readJsonFile } from "../lib/atomic-write.ts";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
+import { oneCodeSettingsPath } from "../lib/one-code-settings.ts";
+import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
+import { ccToolRenderers } from "../lib/tui-render.ts";
+import {
+	DEFAULT_MAX_RESULTS,
+	formatSearchResults,
+	KEYLESS_USER_NOTICE,
+	resolveChain,
+	runChain,
+	webSearchSettingsFrom,
+	withSiteOperators,
+	type WebSearchSettings,
+} from "./backends.ts";
+
+/** `webSearch` from ~/.onecode/settings.json, read leniently — a bad file skips the setting, never breaks the tool. */
+function readWebSearchSettings(): WebSearchSettings {
+	return webSearchSettingsFrom(readJsonFile<{ webSearch?: unknown }>(oneCodeSettingsPath(homedir()))?.webSearch);
+}
+
+/** Declared up front: pi infers `details` from the first return it sees. */
+interface SearchDetails {
+	query?: string;
+	backend?: string;
+	keyless?: boolean;
+	resultCount?: number;
+	failures?: string[];
+	native?: boolean;
+	error?: unknown;
+}
 
 export default function webExtension(pi: ExtensionAPI) {
-	webSearch(pi);
+	// url_context + its active-tools sync, and the vendor web_search we override below.
+	webSearchPackage(pi);
+
+	// Once per session: the user is told the first time a search goes keyless.
+	let keylessNoticeShown = false;
 
-	// pi-web-search reports failures ("Failed: …" text, details.error set)
-	// without isError, so a weak model can read a failure as a successful
-	// search with odd content. Stamp isError here rather than patching the
-	// vendor package.
+	pi.registerTool({
+		name: "web_search",
+		label: "Web Search",
+		...ccToolRenderers<{ query?: string }>("Web Search", { title: (args) => args?.query }),
+		description:
+			"Search the web. Returns result blocks with titles and URLs.\n\n" +
+			"- `allowed_domains` / `blocked_domains` filter results (enforced on Brave/Tavily/Exa; with provider-native search they become `site:` operators in the query, best-effort).\n" +
+			'- After answering from results, end with a "Sources:" list of the URLs you used as markdown links.\n' +
+			"- Uses the model provider's own search when it has one; otherwise a configured search API (Brave, Tavily) or, with no key, a free rate-limited endpoint — the result names which.",
+		parameters: Type.Object({
+			query: Type.String({ minLength: 2, description: "The search query to use" }),
+			allowed_domains: Type.Optional(Type.Array(Type.String(), { description: "Only include search results from these domains" })),
+			blocked_domains: Type.Optional(Type.Array(Type.String(), { description: "Never include search results from these domains" })),
+		}),
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const filters = { allowed: params.allowed_domains, blocked: params.blocked_domains };
+
+			// 1. Provider-native search (pi-web-search) when the current model — or a
+			// web-search.json model — supports it. Its result text is passed through;
+			// it reports failures as "Failed: …" text with details.error and no
+			// isError, which a weak model can read as a successful search with odd
+			// content, so isError is stamped here.
+			const nativeModel = await getWebSearchModel(ctx);
+			if (nativeModel) {
+				const result = await nativeWebSearch(
+					toolCallId,
+					{ query: withSiteOperators(params.query, filters) },
+					signal ?? new AbortController().signal,
+					onUpdate,
+					ctx,
+				);
+				// pi-web-search exposes no domain parameters and returns a synthesized
+				// answer (nothing to post-filter), so the filters ride as `site:`
+				// operators only — say so, rather than let the model assume enforcement.
+				const hasFilters = Boolean(params.allowed_domains?.length || params.blocked_domains?.length);
+				const content =
+					hasFilters && !result.details?.error
+						? [
+								...result.content,
+								{ type: "text" as const, text: "(Domain filters were applied as `site:` operators in the query — best-effort with provider-native search; verify the sources' hosts.)" },
+							]
+						: result.content;
+				return {
+					...result,
+					content,
+					details: { ...result.details, query: params.query, native: true, backend: `${nativeModel.provider}/${nativeModel.id}` } as SearchDetails,
+					isError: Boolean(result.isError) || Boolean(result.details?.error),
+				};
+			}
+
+			// 2. Third-party chain.
+			const chain = resolveChain(process.env, readWebSearchSettings());
+			onUpdate?.({
+				content: [{ type: "text", text: `Searching ${chain[0]?.label ?? "the web"} for "${params.query}"...` }],
+				details: { query: params.query } as SearchDetails,
+			});
+			try {
+				const outcome = await runChain(chain, params.query, filters, DEFAULT_MAX_RESULTS, signal);
+				if (outcome.backend.keyless && !keylessNoticeShown && ctx.hasUI) {
+					keylessNoticeShown = true;
+					ctx.ui.notify(KEYLESS_USER_NOTICE, "warning");
+				}
+				// Bounded by result count, but a provider's error body (quoted in
+				// "Fell back after") or long snippets can still be large: persist, never slice.
+				const text = persistIfLarge(formatSearchResults(params.query, outcome), { dir: sessionResultsDir(ctx), id: toolCallId });
+				return {
+					content: [{ type: "text", text }],
+					details: {
+						query: params.query,
+						backend: outcome.backend.name,
+						keyless: outcome.backend.keyless,
+						resultCount: outcome.results.length,
+						failures: outcome.failures.length ? outcome.failures : undefined,
+					} as SearchDetails,
+				};
+			} catch (error) {
+				const message = (error as Error).message;
+				const text = persistIfLarge(
+					`web_search failed on ${ctx.model?.provider}/${ctx.model?.id} (no native web search on this provider).\n${message}`,
+					{ dir: sessionResultsDir(ctx), id: toolCallId },
+				);
+				return {
+					content: [{ type: "text", text }],
+					details: { query: params.query, error: message } as SearchDetails,
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// url_context reports failures ("Failed: …" text, details.error set) without
+	// isError. Stamp it here rather than patching the vendor package.
 	pi.on("tool_result", (event) => {
-		if (event.toolName !== "web_search" && event.toolName !== "url_context") return;
-		if (event.isError) return;
+		if (event.toolName !== "url_context" || event.isError) return;
 		const details = event.details as { error?: unknown } | undefined;
 		if (details?.error) return { isError: true };
 	});
@@ -36,8 +171,30 @@ export default function webExtension(pi: ExtensionAPI) {
 		name: "web_search",
 		keywords: ["web", "search", "internet", "google", "news", "lookup", "online", "current"],
 	});
-	pi.events.emit(DEFER_CHANNEL, {
-		name: "url_context",
-		keywords: ["url", "analyze page", "gemini"],
-	});
+
+	// url_context only works on a Gemini-compatible provider — pi-web-search's
+	// own gate (getProviderKind === "google") deactivates the tool on anything
+	// else, and its execute() there returns "url_context currently requires a
+	// Google Gemini-compatible model". Registering it as deferred unconditionally
+	// still advertised it in the names-only reminder (and as a defer_loading
+	// definition) on every provider, so a non-Gemini model would load it and burn
+	// two rounds discovering it cannot run (TOOL-FIDELITY-REVIEW-2026-09-07 M5).
+	// Mirror pi-web-search's gate: register it once the first Gemini model is
+	// seen. The one-shot flag keeps later session_tree/model_select events from
+	// re-emitting (each emit past session_start takes the DEFER handler's
+	// late-arrival path — deactivate + reschedule the listing rewrite — which is a
+	// no-op once url_context is already registered).
+	let urlContextDeferred = false;
+	const deferUrlContextIfGemini = (model: { provider?: string; api?: string } | undefined) => {
+		// ctx.model is undefined until a model resolves (session_start can fire
+		// first), and getProviderKind dereferences model.provider without a guard —
+		// so an undefined model must short-circuit here, as pi-web-search's own
+		// `!!model && getProviderKind(...)` does.
+		if (urlContextDeferred || !model || getProviderKind(model) !== "google") return;
+		urlContextDeferred = true;
+		pi.events.emit(DEFER_CHANNEL, { name: "url_context", keywords: ["url", "analyze page", "gemini"] });
+	};
+	pi.on("session_start", (_event, ctx) => deferUrlContextIfGemini(ctx.model));
+	pi.on("session_tree", (_event, ctx) => deferUrlContextIfGemini(ctx.model));
+	pi.on("model_select", (event) => deferUrlContextIfGemini(event.model));
 }