@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/web/search/index.ts

@@ -16,7 +16,7 @@ import { discoverAuthStorage } from "../../sdk";
 import type { ToolSession } from "../../tools";
 import { formatAge } from "../../tools/render-utils";
 import { throwIfAborted } from "../../tools/tool-errors";
-import { getSearchProviderLabel, resolveProviderChain, type SearchProvider } from "./provider";
+import { getSearchProviderLabel, prewarmSearchProviders, resolveProviderChain, type SearchProvider } from "./provider";
 import { renderSearchCall, renderSearchResult, type SearchRenderDetails } from "./render";
 import type { ActiveSearchModelContext, SearchProviderId, SearchResponse } from "./types";
 import { SearchProviderError } from "./types";
@@ -68,6 +68,18 @@ function formatProviderError(error: unknown, provider: SearchProvider): string {
 	return `Unknown error from ${provider.label}`;
 }
 
+function formatProviderFailure(error: unknown, provider: SearchProvider): string {
+	if (error instanceof SearchProviderError) return error.message;
+	return `${provider.id}: ${formatProviderError(error, provider)}`;
+}
+
+function formatFallbackWarning(
+	failures: Array<{ provider: SearchProvider; error: unknown }>,
+	provider: SearchProvider,
+): string {
+	return `Web search provider fallback: ${failures.map(f => formatProviderFailure(f.error, f.provider)).join("; ")}; using ${provider.label}.`;
+}
+
 /** Truncate text for tool output */
 function truncateText(text: string, maxLen: number): string {
 	if (text.length <= maxLen) return text;
@@ -136,6 +148,22 @@ interface ExecuteSearchOptions {
 	activeModelContext?: ActiveSearchModelContext;
 }
 
+/**
+ * Delay before the keyless DuckDuckGo hedge fires while a slower primary is
+ * still in flight. Chosen to be comfortably above DDG's typical ~1-2s
+ * round-trip cost budget yet far below LLM-mediated primary latency, so a
+ * failing primary can fall back to an already-completed hedge result instead
+ * of paying primary-failure time plus DDG time sequentially.
+ */
+const DDG_HEDGE_DELAY_MS = 3_000;
+
+let ddgHedgeDelayMs = DDG_HEDGE_DELAY_MS;
+
+/** Override the hedge delay (tests). Non-finite/non-positive resets to default. */
+export function setDdgHedgeDelayMs(ms: number | undefined): void {
+	ddgHedgeDelayMs = typeof ms === "number" && Number.isFinite(ms) && ms > 0 ? ms : DDG_HEDGE_DELAY_MS;
+}
+
 /** Execute web search */
 async function executeSearch(
 	_toolCallId: string,
@@ -154,51 +182,91 @@ async function executeSearch(
 		activeModelContext,
 	});
 
+	const baseSearchParams = {
+		query: params.query.replace(/202\d/g, String(new Date().getFullYear())), // LUL
+		limit: params.limit,
+		recency: params.recency,
+		systemPrompt: webSearchSystemPrompt,
+		maxOutputTokens: params.max_tokens,
+		numSearchResults: params.num_search_results,
+		temperature: params.temperature,
+		xaiSearchMode: params.xai_search_mode,
+		allowedDomains: params.allowed_domains,
+		excludedDomains: params.excluded_domains,
+		allowedXHandles: params.allowed_x_handles,
+		excludedXHandles: params.excluded_x_handles,
+		fromDate: params.from_date,
+		toDate: params.to_date,
+		enableImageUnderstanding: params.enable_image_understanding,
+		enableImageSearch: params.enable_image_search,
+		enableVideoUnderstanding: params.enable_video_understanding,
+		noInlineCitations: params.no_inline_citations,
+		authStorage,
+		sessionId,
+		activeModelContext,
+	};
+
+	// Hedged fallback: when DuckDuckGo (keyless, cheap) is a non-primary member
+	// of the chain, start it in the background after a short delay. If the
+	// primary succeeds first the hedge is aborted; if the primary fails, the
+	// hedge result is typically already available, collapsing the fallback
+	// latency from `t(primary failure) + t(ddg)` to `max(t(primary failure), t(ddg))`.
+	const ddgIndex = providers.findIndex(p => p.id === "duckduckgo");
+	const hedgeCtl = new AbortController();
+	const onUpstreamAbort = () => hedgeCtl.abort();
+	signal?.addEventListener("abort", onUpstreamAbort, { once: true });
+	let hedgePromise: Promise<SearchResponse> | undefined;
+	let hedgeTimer: NodeJS.Timeout | undefined;
+	if (ddgIndex > 0) {
+		const ddg = providers[ddgIndex]!;
+		hedgeTimer = setTimeout(() => {
+			hedgePromise = ddg.search({ ...baseSearchParams, signal: hedgeCtl.signal });
+			// Failures are consumed when (and if) the loop reaches DuckDuckGo;
+			// never let a losing hedge become an unhandled rejection.
+			hedgePromise.catch(() => {});
+		}, ddgHedgeDelayMs);
+	}
+	const cancelHedge = () => {
+		if (hedgeTimer !== undefined) clearTimeout(hedgeTimer);
+		hedgeCtl.abort();
+		signal?.removeEventListener("abort", onUpstreamAbort);
+	};
+
 	const failures: Array<{ provider: SearchProvider; error: unknown }> = [];
 	let lastProvider = providers[0];
-	for (const provider of providers) {
-		lastProvider = provider;
-		try {
-			const response = await provider.search({
-				query: params.query.replace(/202\d/g, String(new Date().getFullYear())), // LUL
-				limit: params.limit,
-				recency: params.recency,
-				systemPrompt: webSearchSystemPrompt,
-				maxOutputTokens: params.max_tokens,
-				numSearchResults: params.num_search_results,
-				temperature: params.temperature,
-				xaiSearchMode: params.xai_search_mode,
-				allowedDomains: params.allowed_domains,
-				excludedDomains: params.excluded_domains,
-				allowedXHandles: params.allowed_x_handles,
-				excludedXHandles: params.excluded_x_handles,
-				fromDate: params.from_date,
-				toDate: params.to_date,
-				enableImageUnderstanding: params.enable_image_understanding,
-				enableImageSearch: params.enable_image_search,
-				enableVideoUnderstanding: params.enable_video_understanding,
-				noInlineCitations: params.no_inline_citations,
-				signal,
-				authStorage,
-				sessionId,
-				activeModelContext,
-			});
-
-			const text = formatForLLM(response);
-
-			return {
-				content: [{ type: "text" as const, text }],
-				details: { response },
-			};
-		} catch (error) {
-			// Surface user-initiated cancellation immediately so the session sees
-			// a clean abort instead of a generic "all providers failed" message.
-			// Without this, an AbortError from `fetch()` is treated as a provider
-			// failure and the loop falls through to the next provider (or to the
-			// summary error), masking the cancellation.
-			throwIfAborted(signal);
-			failures.push({ provider, error });
+	try {
+		for (const provider of providers) {
+			lastProvider = provider;
+			try {
+				let response: SearchResponse;
+				if (provider.id === "duckduckgo" && hedgePromise) {
+					// Reuse the in-flight (often already-settled) hedge request.
+					if (hedgeTimer !== undefined) clearTimeout(hedgeTimer);
+					response = await hedgePromise;
+				} else {
+					if (provider.id === "duckduckgo" && hedgeTimer !== undefined) clearTimeout(hedgeTimer);
+					response = await provider.search({ ...baseSearchParams, signal });
+				}
+
+				const text = formatForLLM(response);
+				const warning = failures.length > 0 ? formatFallbackWarning(failures, provider) : undefined;
+
+				return {
+					content: [{ type: "text" as const, text: warning ? `Warning: ${warning}\n\n${text}` : text }],
+					details: { response, ...(warning ? { warning } : {}) },
+				};
+			} catch (error) {
+				// Surface user-initiated cancellation immediately so the session sees
+				// a clean abort instead of a generic "all providers failed" message.
+				// Without this, an AbortError from `fetch()` is treated as a provider
+				// failure and the loop falls through to the next provider (or to the
+				// summary error), masking the cancellation.
+				throwIfAborted(signal);
+				failures.push({ provider, error });
+			}
 		}
+	} finally {
+		cancelHedge();
 	}
 
 	const lastFailure = failures[failures.length - 1];
@@ -207,13 +275,7 @@ async function executeSearch(
 		: `Unknown error from ${lastProvider.label}`;
 	const message =
 		providers.length > 1
-			? `All web search providers failed: ${failures
-					.map(f =>
-						f.error instanceof SearchProviderError
-							? f.error.message
-							: `${f.provider.id}: ${formatProviderError(f.error, f.provider)}`,
-					)
-					.join("; ")}`
+			? `All web search providers failed: ${failures.map(f => formatProviderFailure(f.error, f.provider)).join("; ")}`
 			: baseMessage;
 
 	return {
@@ -266,6 +328,24 @@ export class WebSearchTool implements AgentTool<typeof webSearchSchema, SearchRe
 	constructor(session: ToolSession) {
 		this.#session = session;
 		this.description = prompt.render(webSearchDescription);
+		// Prewarm: resolve the provider chain once in the background so the
+		// provider modules are imported and the chain cache is primed before
+		// the first user-visible search. Best-effort only.
+		const authStorage = session.authStorage;
+		if (authStorage) {
+			try {
+				const activeModelContext = session.model
+					? session.modelRegistry?.getActiveSearchModelContext(session.model)
+					: undefined;
+				prewarmSearchProviders({
+					authStorage,
+					sessionId: session.getSessionId?.() ?? undefined,
+					activeModelContext,
+				});
+			} catch {
+				// Never let prewarming break tool construction.
+			}
+		}
 	}
 
 	async execute(
@@ -321,7 +401,12 @@ export function getSearchTools(): CustomTool<any, any>[] {
 	return [webSearchCustomTool];
 }
 
-export { getSearchProvider, setPreferredSearchProvider, setSearchFallbackProviders } from "./provider";
-export { setSearchHardTimeoutMs } from "./providers/utils";
+export {
+	getConfiguredSearchProviderPreference,
+	getSearchProvider,
+	setPreferredSearchProvider,
+	setSearchFallbackProviders,
+} from "./provider";
+export { applyConfiguredSearchTimeout, setSearchHardTimeoutMs } from "./providers/utils";
 export type { SearchProviderId as SearchProvider, SearchResponse } from "./types";
 export { isConfigurableSearchProviderId, isSearchProviderPreference } from "./types";

package/src/web/search/provider.ts

@@ -141,12 +141,78 @@ const MODEL_PROVIDER_TO_SEARCH: Record<string, SearchProviderId> = {
 let preferredProvId: SearchProviderId | "auto" = "auto";
 let fallbackProvIds: SearchProviderId[] = [];
 
+/**
+ * Resolved-chain cache. Chain resolution probes provider availability
+ * (credential lookups, potentially an OAuth refresh through the broker) on
+ * every web_search call even though the result only changes when the active
+ * model, provider preference, or credentials change. Cache the resolved
+ * provider-id list per AuthStorage instance for a short TTL.
+ *
+ * Keyed by AuthStorage identity (WeakMap) so tests and short-lived CLI calls
+ * with fresh storage handles never see another handle's chain. The TTL keeps
+ * a login/logout mid-session from being masked for more than a minute.
+ */
+const CHAIN_CACHE_TTL_MS = 60_000;
+let chainCache = new WeakMap<AuthStorage, Map<string, { ids: SearchProviderId[]; expires: number }>>();
+
+/** Drop every cached resolved chain (settings changed, tests). */
+export function clearResolvedChainCache(): void {
+	chainCache = new WeakMap();
+}
+
+function chainCacheKey(
+	preferred: SearchProviderId | "auto" | undefined,
+	fallbacks: readonly SearchProviderId[],
+	ctx: ActiveSearchModelContext | undefined,
+	authStorage: AuthStorage,
+): string {
+	// Include the AuthStorage generation so credential changes (login/logout,
+	// key rotation) invalidate cached chains immediately instead of being
+	// masked for up to the TTL. Stubs without getGeneration() key as 0.
+	const generation = (authStorage as { getGeneration?: () => number }).getGeneration?.() ?? 0;
+	return JSON.stringify([
+		generation,
+		preferred ?? null,
+		fallbacks,
+		ctx
+			? [ctx.provider, ctx.modelId, ctx.wireModelId ?? null, ctx.api, ctx.baseUrl ?? null, ctx.webSearch ?? null]
+			: null,
+	]);
+}
+
 export function setPreferredSearchProvider(provider: SearchProviderId | "auto"): void {
 	preferredProvId = provider;
+	clearResolvedChainCache();
 }
 
 export function setSearchFallbackProviders(ids: readonly string[]): void {
 	fallbackProvIds = ids.filter(isConfigurableSearchProviderId);
+	clearResolvedChainCache();
+}
+
+/**
+ * Fire-and-forget warm-up: resolve the provider chain once so the provider
+ * modules are imported and the chain cache is primed before the first
+ * user-visible search. Errors are intentionally swallowed — prewarming must
+ * never surface a failure the real search path would handle itself.
+ */
+export function prewarmSearchProviders(options: ResolveProviderChainOptions): void {
+	void resolveProviderChain(options).catch(() => {});
+}
+
+export interface SearchProviderPreferenceSource {
+	get(path: "providers.webSearch" | "web_search.provider"): SearchProviderId | "auto";
+	has(path: "providers.webSearch" | "web_search.provider"): boolean;
+}
+
+export function getConfiguredSearchProviderPreference(
+	settings: SearchProviderPreferenceSource,
+): SearchProviderId | "auto" {
+	const providerPreference = settings.get("providers.webSearch");
+	if (settings.has("providers.webSearch") || providerPreference !== "auto") return providerPreference;
+
+	const legacyProviderPreference = settings.get("web_search.provider");
+	return legacyProviderPreference;
 }
 
 export interface ResolveProviderChainOptions {
@@ -342,6 +408,16 @@ export async function resolveProviderChain(options: ResolveProviderChainOptions)
 		activeModelContext,
 		fallbackProviders = fallbackProvIds,
 	} = options;
+
+	const cacheKey = chainCacheKey(preferredProvider, fallbackProviders, activeModelContext, authStorage);
+	const perStorage = chainCache.get(authStorage);
+	const cached = perStorage?.get(cacheKey);
+	if (cached && cached.expires > Date.now()) {
+		const cachedProviders: SearchProvider[] = [];
+		for (const id of cached.ids) cachedProviders.push(await getSearchProvider(id));
+		return cachedProviders;
+	}
+
 	const chain: SearchProviderId[] = [];
 
 	// A forced primary is honored only when it is a user-configurable provider.
@@ -377,6 +453,10 @@ export async function resolveProviderChain(options: ResolveProviderChainOptions)
 	}
 	appendDeduped(chain, "duckduckgo");
 
+	const storageEntry = chainCache.get(authStorage) ?? new Map<string, { ids: SearchProviderId[]; expires: number }>();
+	storageEntry.set(cacheKey, { ids: [...chain], expires: Date.now() + CHAIN_CACHE_TTL_MS });
+	chainCache.set(authStorage, storageEntry);
+
 	const providers: SearchProvider[] = [];
 	for (const id of chain) providers.push(await getSearchProvider(id));
 	return providers;

package/src/web/search/providers/anthropic.ts

@@ -119,7 +119,7 @@ async function callSearch(
 		method: "POST",
 		headers,
 		body: JSON.stringify(body),
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, "llm"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/brave.ts

@@ -85,7 +85,7 @@ async function callBraveSearch(
 			Accept: "application/json",
 			"X-Subscription-Token": apiKey,
 		},
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "api"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/codex.ts

@@ -216,7 +216,7 @@ async function callCodexSearch(
 		method: "POST",
 		headers,
 		body: JSON.stringify(body),
-		signal: withHardTimeout(options.signal),
+		signal: withHardTimeout(options.signal, "llm"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/duckduckgo.ts

@@ -196,7 +196,7 @@ async function fetchAndParse(
 			"Accept-Language": "en-US,en;q=0.9",
 		},
 		body,
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, "api"),
 	});
 
 	// DuckDuckGo signals soft blocks with 202 (which is still response.ok).

package/src/web/search/providers/exa.ts

@@ -115,7 +115,7 @@ async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<E
 			"x-api-key": apiKey,
 		},
 		body: JSON.stringify(body),
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "api"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/gemini.ts

@@ -29,7 +29,11 @@ const ANTIGRAVITY_ENDPOINT_FALLBACKS = [ANTIGRAVITY_DAILY_ENDPOINT, ANTIGRAVITY_
 const DEFAULT_MODEL = "gemini-2.5-flash";
 const MAX_RETRIES = 3;
 const BASE_DELAY_MS = 1000;
-const RATE_LIMIT_BUDGET_MS = 5 * 60 * 1000;
+// Retry-delay ceiling for 429/5xx. The web_search chain always terminates in
+// the keyless DuckDuckGo fallback, so a rate-limited Gemini should fail
+// through in seconds instead of parking the chain behind long server-provided
+// retry delays (previously a 5-minute budget).
+const RATE_LIMIT_BUDGET_MS = 30 * 1000;
 
 const GEMINI_PROVIDERS = ["google-gemini-cli", "google-antigravity"] as const;
 type GeminiProviderId = (typeof GEMINI_PROVIDERS)[number];
@@ -230,7 +234,7 @@ async function callGeminiSearch(
 			...headers,
 		},
 		body: JSON.stringify(requestBody),
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, "llm"),
 	});
 	const urlFor = (attempt: number) =>
 		`${endpoints[Math.min(attempt, endpoints.length - 1)]}/v1internal:streamGenerateContent?alt=sse`;
@@ -466,7 +470,7 @@ async function searchGeminiViaGenerativeLanguage(params: SearchParams): Promise<
 		method: "POST",
 		headers: { ...(ctx.headers ?? {}), "x-goog-api-key": apiKey, "Content-Type": "application/json" },
 		body: JSON.stringify(body),
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "llm"),
 	});
 	const text = await response.text();
 	if (!response.ok) {

package/src/web/search/providers/jina.ts

@@ -41,7 +41,7 @@ async function callJinaSearch(apiKey: string, query: string, signal?: AbortSigna
 			Accept: "application/json",
 			Authorization: `Bearer ${apiKey}`,
 		},
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, "api"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/kimi.ts

@@ -19,6 +19,11 @@ const KIMI_SEARCH_URL = "https://api.kimi.com/coding/v1/search";
 const DEFAULT_NUM_RESULTS = 10;
 const MAX_NUM_RESULTS = 20;
 const DEFAULT_TIMEOUT_SECONDS = 30;
+// Local hard ceiling aligned with the upstream `timeout_seconds` request budget
+// (plus transport headroom) instead of the generic 15s "api" class: Kimi
+// legitimately runs search + page crawling up to its advertised 30s window,
+// and aborting earlier would discard valid in-budget responses.
+const KIMI_HARD_TIMEOUT_MS = (DEFAULT_TIMEOUT_SECONDS + 5) * 1000;
 
 export interface KimiSearchParams {
 	query: string;
@@ -87,7 +92,7 @@ async function callKimiSearch(
 			enable_page_crawling: params.includeContent,
 			timeout_seconds: DEFAULT_TIMEOUT_SECONDS,
 		}),
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, KIMI_HARD_TIMEOUT_MS),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/openai-compatible.ts

@@ -134,7 +134,7 @@ export class OpenAICompatibleSearchProvider extends SearchProvider {
 				method: "POST",
 				headers,
 				body: JSON.stringify(payload),
-				signal: withHardTimeout(params.signal),
+				signal: withHardTimeout(params.signal, "llm"),
 			});
 
 		// Web search is a Responses-API capability: many OpenAI-compatible

package/src/web/search/providers/parallel.ts

@@ -139,7 +139,7 @@ async function searchWithAuthStorage(
 				max_chars_per_result: 10_000,
 			},
 		}),
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "api"),
 	});
 	if (!response.ok) {
 		throw parseParallelErrorResponse(response.status, await response.text());

package/src/web/search/providers/perplexity.ts

@@ -251,7 +251,7 @@ async function callPerplexityApi(
 			"Content-Type": "application/json",
 		},
 		body: JSON.stringify(request),
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, "llm"),
 	});
 
 	if (!response.ok) {
@@ -370,7 +370,7 @@ async function callPerplexityOAuth(
 				skip_search_enabled: true,
 			},
 		}),
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "llm"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/searxng.ts

@@ -214,7 +214,7 @@ async function callSearXNGSearch(
 
 	const response = await fetch(url, {
 		headers,
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "api"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/synthetic.ts

@@ -47,7 +47,7 @@ async function callSyntheticSearch(
 			Authorization: `Bearer ${apiKey}`,
 		},
 		body: JSON.stringify({ query }),
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, "api"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/tavily.ts

@@ -96,7 +96,7 @@ async function callTavilySearch(apiKey: string, params: TavilySearchParams): Pro
 			Authorization: `Bearer ${apiKey}`,
 		},
 		body: JSON.stringify(buildRequestBody(params)),
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "api"),
 	});
 
 	if (!response.ok) {

package/src/web/search/providers/utils.ts

@@ -44,38 +44,81 @@ export function findCredential(
 }
 
 /**
- * Default hard ceiling for a single web-search round-trip. 300s tolerates
- * legitimate slow LLM-mediated responses (anthropic web_search_20250305,
- * perplexity, gemini, OpenAI code backend) while still guaranteeing the session unfreezes
- * if Bun's `AbortSignal` fails to propagate on Windows.
- *
- * Pure search APIs (brave, exa, jina, tavily, searxng, synthetic, zai)
- * settle far faster in practice; reusing the same ceiling keeps the wiring
- * uniform without compromising correctness.
+ * Legacy hard ceiling for a single web-search round-trip, retained as the
+ * fallback for call sites that do not declare a timeout class. 300s tolerates
+ * pathological cases while still guaranteeing the session unfreezes if Bun's
+ * `AbortSignal` fails to propagate on Windows.
  */
 export const SEARCH_HARD_TIMEOUT_MS = 300_000;
 
+/**
+ * Hard ceiling for pure search APIs (brave, exa, jina, tavily, kagi,
+ * parallel, searxng, synthetic, zai, duckduckgo). These settle in ~1-3s in
+ * practice; a hung TCP/TLS connection should fall through to the next
+ * provider in seconds, not minutes. Kimi is the exception: it declares an
+ * explicit ceiling aligned with its upstream 30s request budget.
+ */
+export const SEARCH_API_TIMEOUT_MS = 15_000;
+
+/**
+ * Hard ceiling for LLM-mediated search providers (anthropic, codex, gemini,
+ * perplexity, xai, openai-compatible). These legitimately take tens of
+ * seconds because a model performs the search and synthesizes an answer.
+ */
+export const SEARCH_LLM_TIMEOUT_MS = 120_000;
+
+/** Timeout class a provider declares for its outbound round-trips. */
+export type SearchTimeoutClass = "api" | "llm";
+
+const TIMEOUT_CLASS_MS: Record<SearchTimeoutClass, number> = {
+	api: SEARCH_API_TIMEOUT_MS,
+	llm: SEARCH_LLM_TIMEOUT_MS,
+};
+
 /**
  * Runtime-configurable hard timeout, seeded from the `web_search.timeout`
- * setting via {@link setSearchHardTimeoutMs}. Falls back to
- * {@link SEARCH_HARD_TIMEOUT_MS} when unset or invalid.
+ * setting via {@link setSearchHardTimeoutMs}. When set, it overrides every
+ * class default so users keep a single knob. Unset means class defaults apply.
  */
-let configuredHardTimeoutMs = SEARCH_HARD_TIMEOUT_MS;
+let configuredHardTimeoutMs: number | undefined;
 
 /**
  * Override the hard timeout applied to every web-search round-trip.
  *
  * @param ms - Hard timeout in milliseconds. Non-finite or non-positive
- *   values reset the timeout to {@link SEARCH_HARD_TIMEOUT_MS}.
+ *   values clear the override so per-class defaults apply.
  */
 export function setSearchHardTimeoutMs(ms: number | undefined): void {
-	configuredHardTimeoutMs = typeof ms === "number" && Number.isFinite(ms) && ms > 0 ? ms : SEARCH_HARD_TIMEOUT_MS;
+	configuredHardTimeoutMs = typeof ms === "number" && Number.isFinite(ms) && ms > 0 ? ms : undefined;
+}
+
+/** Structural settings source for {@link applyConfiguredSearchTimeout}. */
+export interface SearchTimeoutSettingSource {
+	get(path: "web_search.timeout"): unknown;
+	has(path: "web_search.timeout"): boolean;
+}
+
+/**
+ * Install the `web_search.timeout` override from settings — but only when the
+ * user explicitly configured it. The settings schema ships a default value
+ * (300), and consuming that default via `get()` alone would reinstall a
+ * uniform 300s ceiling on every session, silently disabling the per-class
+ * timeout defaults. `has()` distinguishes loaded/overridden settings from
+ * schema defaults; unset clears any previous override so class defaults apply.
+ */
+export function applyConfiguredSearchTimeout(settings: SearchTimeoutSettingSource): void {
+	if (!settings.has("web_search.timeout")) {
+		setSearchHardTimeoutMs(undefined);
+		return;
+	}
+	const value = settings.get("web_search.timeout");
+	setSearchHardTimeoutMs(typeof value === "number" && Number.isFinite(value) && value > 0 ? value * 1000 : undefined);
 }
 
 /**
  * Compose a caller-supplied {@link AbortSignal} with a hard timeout so an
- * outbound `fetch()` is guaranteed to settle within `ms` even when the
- * runtime fails to propagate cancellation to the underlying transport.
+ * outbound `fetch()` is guaranteed to settle even when the runtime fails to
+ * propagate cancellation to the underlying transport.
  *
  * Bun's WinHTTP backend on Windows is known to ignore `AbortSignal` once a
  * TCP/TLS connection stalls (oven-sh/bun#15275, oven-sh/bun#18536); without
@@ -83,9 +126,16 @@ export function setSearchHardTimeoutMs(ms: number | undefined): void {
  * because the user's Esc is never delivered to the native layer.
  *
  * @param signal - Caller cancellation signal, if any.
- * @param ms - Hard timeout in milliseconds. Defaults to the configured value.
+ * @param msOrClass - Explicit timeout in milliseconds, or a
+ *   {@link SearchTimeoutClass} resolved to its class default. Omitted falls
+ *   back to the legacy {@link SEARCH_HARD_TIMEOUT_MS} ceiling. A user-set
+ *   `web_search.timeout` overrides class defaults (but not explicit ms).
  */
-export function withHardTimeout(signal: AbortSignal | undefined, ms: number = configuredHardTimeoutMs): AbortSignal {
+export function withHardTimeout(signal: AbortSignal | undefined, msOrClass?: number | SearchTimeoutClass): AbortSignal {
+	const ms =
+		typeof msOrClass === "number"
+			? msOrClass
+			: (configuredHardTimeoutMs ?? (msOrClass ? TIMEOUT_CLASS_MS[msOrClass] : SEARCH_HARD_TIMEOUT_MS));
 	const timeout = AbortSignal.timeout(ms);
 	return signal ? AbortSignal.any([signal, timeout]) : timeout;
 }

package/src/web/search/providers/xai.ts

@@ -441,7 +441,7 @@ export async function searchXai(params: XaiSearchParams): Promise<SearchResponse
 				noInlineCitations: params.no_inline_citations,
 			}),
 		),
-		signal: withHardTimeout(params.signal),
+		signal: withHardTimeout(params.signal, "llm"),
 	});
 
 	const text = await response.text();

package/src/web/search/providers/zai.ts

@@ -79,7 +79,7 @@ async function callZaiTool(apiKey: string, args: Record<string, unknown>, signal
 				arguments: args,
 			},
 		}),
-		signal: withHardTimeout(signal),
+		signal: withHardTimeout(signal, "api"),
 	});
 
 	if (!response.ok) {