@nijaru/pi-search 0.0.2 → 0.0.4

package/README.md

@@ -34,7 +34,7 @@ Pi tools:
   is allowed; Exa returns semantic results with excerpts and reported usage.
 - In free-only mode, configured Brave is the conservative paced keyword/fresh
   path. Set `PI_SEARCH_PREFER_FREE=1` to prefer it before metered Exa.
-  Parallel and the official X API remain explicit providers.
+  Parallel, Cloudflare Web Search, and the official X API remain explicit providers.
 - Automatic routing permits at most one visible fallback after a safe
   authentication, rate-limit, or unavailable failure. Network, timeout, and
   post-dispatch HTTP failures remain final because their effects are uncertain.
@@ -88,8 +88,11 @@ export X_API_BEARER_TOKEN=...         # explicit official X API search
 # from Brave search's free-mode admission.
 ```
 
-Gemini and xAI credentials come from Pi's model-registry authentication
-context. Active Gemini/xAI models use native search automatically. For
+Native-provider credentials come from Pi's model-registry authentication
+context. Anthropic supports API keys, registry-owned bearer headers, and
+workload identity federation; federation exchanges use the official SDK
+protocol with bounded, cancellable requests. Anthropic Pro/Max subscription
+search is not supported; its tokens are rejected before dispatch. Active Gemini/xAI models use native search automatically. For
 search-only Gemini grounding, prefer Pi's current `gemini-flash-lite-latest`
 model alias rather than full Flash/Pro or legacy model IDs. Explicit
 `provider: "gemini"`, `"xai"`, `"xai-x"`, `"anthropic"`, or `"meta"` can use a
@@ -105,13 +108,45 @@ selected source pages are needed; this reuses the safe local fetch path. For
 when a multi-query run should use a specific Gemini, xAI, Anthropic, Meta,
 OpenAI, or Codex model.
 
-### Local OpenAI-compatible endpoints
+### Cloudflare Web Search
 
-The extension keeps the public and runtime 2,000-character query limit. For
-local/private OpenAI-compatible endpoints, it applies a compatibility-only
-outgoing schema adjustment for llama.cpp's nested-string grammar boundary; the
-schema sent to hosted GPT and other public providers is unchanged. No setting
-or tool toggle is required.
+Cloudflare routes search through Ceramic, Exa, or Linkup. It is an explicit
+secondary provider, never an automatic choice or fallback:
+
+```bash
+export CLOUDFLARE_ACCOUNT_ID=...
+export CLOUDFLARE_API_TOKEN=...
+export PI_SEARCH_CLOUDFLARE_PROVIDER=exa  # required: exa, linkup, or ceramic
+# export PI_SEARCH_CLOUDFLARE_GATEWAY_ID=default
+# export PI_SEARCH_CLOUDFLARE_BYOK_ALIAS=default
+```
+
+Use `provider: "cloudflare"` with `web_search` or `web_research`. The API token
+needs **Workers AI Read** and **AI Gateway Read** permissions. Queries are
+limited to 1,024 characters and results to 10. Domain/date/social filters and
+native-model controls are rejected, not silently dropped. Results identify
+both Cloudflare and the configured upstream.
+
+An explicit BYOK alias fails if its stored key is missing. Without an alias,
+Cloudflare uses the upstream's stored `default` key when present, otherwise
+prepaid gateway credits. See [Cloudflare's API and billing instructions](https://developers.cloudflare.com/web-search/how-to-use/).
+
+**Keep direct Exa as the default direct search choice for now.** It provides
+richer controls than the gateway. Ceramic has an independent web index and
+long result descriptions; it is not merely a keyword-only engine. Its much
+lower advertised price does not establish comparable quality. More
+importantly, [Ceramic's terms §7(n)–(p)](https://www.ceramic.ai/terms-of-service)
+restrict result retention and extractability in ways that appear incompatible
+with saved/exportable Pi transcripts unless contractually permitted. Clarify
+those rights before using Ceramic. Zero Data Retention describes provider
+handling, not permission to retain results yourself.
+
+### Local and virtual models
+
+Research queries retain the 2,000-character runtime limit. The tool schema
+omits that nested string bound because llama.cpp cannot compile it; validation
+still rejects overlong queries before search. This works with direct local
+models and virtual routes without endpoint detection or request rewriting.
 
 ## Fetch coverage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nijaru/pi-search",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Provider-neutral web search and fetching tools for Pi",
   "type": "module",
   "license": "MIT",
@@ -41,9 +41,9 @@
     "live:smoke": "bun scripts/live-smoke.ts"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@types/bun": "1.3.14",
     "@types/turndown": "^5.0.6",
     "typebox": "1.3.10",
@@ -60,6 +60,7 @@
     "node-domexception": "npm:@profoundlogic/node-domexception@1.0.2"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "0.129.0",
     "@firecrawl/anydoc": "0.2.4",
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",

package/src/anthropic-auth.ts

@@ -0,0 +1,108 @@
+import { open } from "node:fs/promises";
+import type { ModelExecution } from "./model-selection";
+import { hasExplicitHeader, modelAuthHeaders } from "./model-selection";
+import { createProviderError } from "./errors";
+import { readBoundedResponseText } from "./http";
+import type { SearchHttpFetch } from "./provider-http";
+
+export const ANTHROPIC_VERSION = "2023-06-01";
+const OAUTH_BETA = "oauth-2025-04-20";
+const MAX_IDENTITY_BYTES = 16 * 1024;
+
+async function identityToken(path: string, signal: AbortSignal): Promise<string> {
+	signal.throwIfAborted();
+	const file = await open(path, "r");
+	try {
+		const buffer = Buffer.alloc(MAX_IDENTITY_BYTES + 1);
+		let size = 0;
+		while (size < buffer.length) {
+			signal.throwIfAborted();
+			const { bytesRead } = await file.read(buffer, size, buffer.length - size, null);
+			if (bytesRead === 0) break;
+			size += bytesRead;
+		}
+		const token = buffer.subarray(0, size).toString("utf8").trim();
+		if (size > MAX_IDENTITY_BYTES || token.length === 0) throw new Error("Invalid identity token file");
+		return token;
+	} finally {
+		await file.close();
+	}
+}
+
+/** Adapter-owned cache; auth configuration and credentials come only from Pi. */
+export class AnthropicSearchAuth {
+	private cached?: { key: string; token: string; expiresAt: number | null };
+
+	constructor(private readonly fetchImpl: SearchHttpFetch) {}
+
+	invalidate(): void {
+		this.cached = undefined;
+	}
+
+	async headers(execution: ModelExecution, endpoint: string, signal: AbortSignal): Promise<Readonly<Record<string, string>>> {
+		const headers = modelAuthHeaders(execution, { bearerApiKey: false });
+		const sources = [execution.model.headers, execution.auth.headers];
+		const apiKey = execution.auth.apiKey;
+		// Pro/Max OAuth requires Pi's Claude Code request identity, not just
+		// a bearer header. Do not dispatch an incomplete subscription request.
+		if ((apiKey?.startsWith("sk-ant-oat") && !headers.has("authorization") && !headers.has("x-api-key"))
+			|| /^Bearer\s+sk-ant-oat/i.test(headers.get("authorization") ?? "")) {
+			throw createProviderError({ provider: "anthropic", kind: "unsupported", message: "Anthropic subscription search is not supported; use an API key, API bearer credential, or workload identity", retryable: false });
+		}
+		if (apiKey?.trim() && !hasExplicitHeader(sources, "x-api-key") && !headers.has("authorization")) {
+			headers.set("x-api-key", apiKey);
+		}
+
+		if (!headers.has("x-api-key") && !headers.has("authorization")) {
+			// A null authorization is an explicit deletion, not permission to
+			// replace it with a separately exchanged credential.
+			if (hasExplicitHeader(sources, "authorization")) throw this.missingAuth();
+			const env = execution.auth.env;
+			const federationRuleId = env?.ANTHROPIC_FEDERATION_RULE_ID;
+			const organizationId = env?.ANTHROPIC_ORGANIZATION_ID;
+			const path = env?.ANTHROPIC_IDENTITY_TOKEN_FILE;
+			if (!federationRuleId || !organizationId || !path) throw this.missingAuth();
+			// The SDK token endpoint is /v1/oauth/token, relative to the API root.
+			const tokenBase = new URL(endpoint);
+			tokenBase.pathname = tokenBase.pathname.replace(/\/(?:v1\/)?messages\/?$/, "");
+			tokenBase.search = "";
+			tokenBase.hash = "";
+			const baseURL = tokenBase.toString().replace(/\/$/, "");
+			const key = JSON.stringify([baseURL, federationRuleId, organizationId, path, env?.ANTHROPIC_SERVICE_ACCOUNT_ID, env?.ANTHROPIC_WORKSPACE_ID]);
+			let cached = this.cached;
+			if (cached?.key !== key || (cached.expiresAt !== null && cached.expiresAt <= Date.now() / 1_000 + 60)) {
+				try {
+					// Reuse the official exchange protocol without its ambient
+					// credential chain, background refresh, or hidden request retries.
+					const { oidcFederationProvider } = await import("@anthropic-ai/sdk/lib/credentials/oidc-federation");
+					const exchange = oidcFederationProvider({
+						baseURL,
+						federationRuleId,
+						organizationId,
+						serviceAccountId: env?.ANTHROPIC_SERVICE_ACCOUNT_ID ?? undefined,
+						workspaceId: env?.ANTHROPIC_WORKSPACE_ID ?? undefined,
+						identityTokenProvider: () => identityToken(path, signal),
+						fetch: async (input, init) => {
+							const response = await this.fetchImpl(input, { ...init, signal, redirect: "error" });
+							const body = await readBoundedResponseText(response, 64 * 1024, signal);
+							return new Response(body, { status: response.status, headers: response.headers });
+						},
+					});
+					const token = await exchange();
+					signal.throwIfAborted();
+					cached = this.cached = { key, ...token };
+				} catch (error) {
+					throw createProviderError({ provider: "anthropic", kind: signal.aborted ? "canceled" : "auth", message: signal.aborted ? "Search canceled" : "Anthropic workload identity token exchange failed", retryable: false, cause: error });
+				}
+			}
+			headers.set("authorization", `Bearer ${cached.token}`);
+			headers.set("anthropic-beta", [headers.get("anthropic-beta"), OAUTH_BETA].filter(Boolean).join(","));
+		}
+		headers.set("anthropic-version", ANTHROPIC_VERSION);
+		return Object.fromEntries(headers.entries());
+	}
+
+	private missingAuth(): Error {
+		return createProviderError({ provider: "anthropic", kind: "auth", fallbackSafe: true, message: "Anthropic authentication returned no API key, bearer header, or workload identity configuration", retryable: false });
+	}
+}

package/src/anthropic.ts

@@ -10,20 +10,19 @@ import type {
 	SearchResult,
 	SearchWarning,
 } from "./contracts";
-import { createProviderError } from "./errors";
+import { createProviderError, isProviderError } from "./errors";
 import {
-	appendEndpointSuffix,
 	assertHttpEndpoint,
 	executeGroundedSearch,
 	tokenUsage,
 	type GroundingPlan,
 } from "./grounding";
-import { hasExplicitHeader, modelAuthHeaders, type ModelExecution } from "./model-selection";
+import { AnthropicSearchAuth } from "./anthropic-auth";
 import { httpSource, objectValue, optionalString, type SearchHttpFetch } from "./provider-http";
 import { validateSearchRequest } from "./search";
 
 export const ANTHROPIC_MESSAGES_ENDPOINT = "https://api.anthropic.com/v1/messages";
-export const ANTHROPIC_VERSION = "2023-06-01";
+export { ANTHROPIC_VERSION } from "./anthropic-auth";
 export const ANTHROPIC_WEB_SEARCH_TOOL = "web_search_20250305";
 export const DEFAULT_ANTHROPIC_RESPONSE_BYTES = 4 * 1024 * 1024;
 const MAX_ANTHROPIC_ANSWER_LENGTH = 8_000;
@@ -41,6 +40,7 @@ const capabilities: ProviderCapabilities = {
 	semantic: true,
 	excerpts: true,
 	domainFilter: true,
+	combinedDomainFilters: false,
 	nativeGrounding: true,
 	userLocation: true,
 };
@@ -118,26 +118,12 @@ export function buildAnthropicRequest(request: SearchRequest, toolType = ANTHROP
 }
 
 function endpointFor(model: ProviderModel, override?: string): string {
-	const base = override ?? (model.baseUrl.trim().length > 0 ? model.baseUrl : ANTHROPIC_MESSAGES_ENDPOINT);
-	return assertHttpEndpoint(appendEndpointSuffix(base, "/messages"), "anthropic", "Anthropic Messages endpoint");
-}
-
-function anthropicHeaders(execution: ModelExecution): Readonly<Record<string, string>> {
-	const headers = modelAuthHeaders(execution, { bearerApiKey: false });
-	const apiKey = execution.auth.apiKey;
-	// An explicit x-api-key (value or null deletion) wins over a derived key.
-	if (
-		apiKey !== undefined &&
-		apiKey.trim().length > 0 &&
-		!hasExplicitHeader([execution.model.headers, execution.auth.headers], "x-api-key")
-	) {
-		headers.set("x-api-key", apiKey);
-	}
-	if (!headers.has("x-api-key")) {
-		throw createProviderError({ provider: "anthropic", kind: "auth", message: "Anthropic authentication returned no API key", retryable: false });
-	}
-	headers.set("anthropic-version", ANTHROPIC_VERSION);
-	return Object.fromEntries(headers.entries());
+	if (override !== undefined) return assertHttpEndpoint(override, "anthropic", "Anthropic Messages endpoint");
+	const base = model.baseUrl.trim().length > 0 ? model.baseUrl : ANTHROPIC_MESSAGES_ENDPOINT;
+	const url = new URL(assertHttpEndpoint(base, "anthropic", "Anthropic Messages endpoint"));
+	const path = url.pathname.replace(/\/+$/, "");
+	if (!path.endsWith("/messages")) url.pathname = `${path}${path.endsWith("/v1") ? "/messages" : "/v1/messages"}`;
+	return url.toString();
 }
 
 interface AnthropicCandidate {
@@ -155,9 +141,8 @@ function candidateFromUrl(url: unknown, title: unknown): AnthropicCandidate | un
 
 function throwResultError(code: unknown): never {
 	const errorCode = optionalString(code, 100) ?? "unknown";
-	// Errored searches are not billed, so retry/fallback is safe. The router
-	// treats `unavailable` like auth/rate-limit failures and may consume its
-	// single bounded automatic fallback.
+	// Search errors can still follow billed model tokens or successful searches.
+	// Retryability is not evidence that a paid fallback is safe.
 	const retryable = errorCode === "too_many_requests" || errorCode === "unavailable";
 	throw createProviderError({
 		provider: "anthropic",
@@ -167,8 +152,35 @@ function throwResultError(code: unknown): never {
 	});
 }
 
-/** Normalize a Messages API payload into evidence-first results. */
+function reportedUsage(root: Record<string, unknown>, searchQueries = 0) {
+	const usageRecord = root.usage !== null && typeof root.usage === "object" && !Array.isArray(root.usage)
+		? root.usage as Record<string, unknown>
+		: undefined;
+	const serverToolUse = usageRecord?.server_tool_use !== null && typeof usageRecord?.server_tool_use === "object" && !Array.isArray(usageRecord?.server_tool_use)
+		? usageRecord.server_tool_use as Record<string, unknown>
+		: undefined;
+	const reportedQueries = typeof serverToolUse?.web_search_requests === "number" && Number.isFinite(serverToolUse.web_search_requests) && serverToolUse.web_search_requests >= 0
+		? Math.floor(serverToolUse.web_search_requests)
+		: undefined;
+	const usage = tokenUsage(usageRecord?.input_tokens, usageRecord?.output_tokens, undefined);
+	const usageDetails = usage === undefined && (reportedQueries ?? searchQueries) === 0
+		? undefined
+		: { ...usage, ...((reportedQueries ?? searchQueries) === 0 ? {} : { searchQueries: reportedQueries ?? searchQueries }) };
+	return usageDetails;
+}
+
+/** Preserve known usage even when normalization rejects a billed response. */
 export function normalizeAnthropicResponse(payload: unknown, request: SearchRequest): SearchResponse {
+	try {
+		return normalizeEvidence(payload, request);
+	} catch (error) {
+		if (!isProviderError(error)) throw error;
+		const root = objectValue(payload, "response", "anthropic");
+		throw createProviderError({ ...error, message: error.message, usage: reportedUsage(root), fallbackSafe: false, cause: error });
+	}
+}
+
+function normalizeEvidence(payload: unknown, request: SearchRequest): SearchResponse {
 	const normalized = validateSearchRequest(request);
 	const root = objectValue(payload, "response", "anthropic");
 	if (!Array.isArray(root.content)) {
@@ -285,19 +297,7 @@ export function normalizeAnthropicResponse(payload: unknown, request: SearchRequ
 	const answer = normalized.answerMode !== "evidence" && answerText.length > 0 && citations.length > 0
 		? { text: answerText, contentTrust: "untrusted" as const, provider: "anthropic" as const, citations }
 		: undefined;
-	const usageRecord = root.usage !== null && typeof root.usage === "object" && !Array.isArray(root.usage)
-		? root.usage as Record<string, unknown>
-		: undefined;
-	const serverToolUse = usageRecord?.server_tool_use !== null && typeof usageRecord?.server_tool_use === "object" && !Array.isArray(usageRecord?.server_tool_use)
-		? usageRecord.server_tool_use as Record<string, unknown>
-		: undefined;
-	const reportedQueries = typeof serverToolUse?.web_search_requests === "number" && Number.isFinite(serverToolUse.web_search_requests) && serverToolUse.web_search_requests >= 0
-		? Math.floor(serverToolUse.web_search_requests)
-		: undefined;
-	const usage = tokenUsage(usageRecord?.input_tokens, usageRecord?.output_tokens, undefined);
-	const usageDetails = usage === undefined && (reportedQueries ?? searchQueries) === 0
-		? undefined
-		: { ...usage, ...((reportedQueries ?? searchQueries) === 0 ? {} : { searchQueries: reportedQueries ?? searchQueries }) };
+	const usageDetails = reportedUsage(root, searchQueries);
 	const warnings: SearchWarning[] = discarded > 0
 		? [{ code: "partial-results", message: `Anthropic discarded ${discarded} malformed result entr${discarded === 1 ? "y" : "ies"}` }]
 		: [];
@@ -321,6 +321,7 @@ export class AnthropicProvider implements Provider {
 	private readonly fetchImpl: SearchHttpFetch;
 	private readonly maxResponseBytes: number;
 	private readonly toolType: string;
+	private readonly auth: AnthropicSearchAuth;
 
 	constructor(options: AnthropicAdapterOptions = {}) {
 		this.endpoint = options.endpoint;
@@ -330,25 +331,33 @@ export class AnthropicProvider implements Provider {
 			throw new Error("Anthropic maxResponseBytes must be a positive integer");
 		}
 		this.toolType = options.toolType ?? ANTHROPIC_WEB_SEARCH_TOOL;
+		this.auth = new AnthropicSearchAuth(this.fetchImpl);
 	}
 
 	async search(request: SearchRequest, signal: AbortSignal, context: ProviderContext): Promise<SearchResponse> {
 		const normalized = validateSearchRequest(request);
 		const plan = buildAnthropicRequest(normalized, this.toolType);
-		return executeGroundedSearch({
-			provider: this.id,
-			modelProvider: "anthropic",
-			api: "anthropic-messages",
-			request: normalized,
-			signal,
-			context,
-			fetchImpl: this.fetchImpl,
-			maxResponseBytes: this.maxResponseBytes,
-			endpointFor: (model) => endpointFor(model, this.endpoint),
-			headersFor: anthropicHeaders,
-			plan,
-			normalize: normalizeAnthropicResponse,
-		});
+		try {
+			return await executeGroundedSearch({
+				provider: this.id,
+				modelProvider: "anthropic",
+				api: "anthropic-messages",
+				request: normalized,
+				signal,
+				context,
+				fetchImpl: this.fetchImpl,
+				maxResponseBytes: this.maxResponseBytes,
+				endpointFor: (model) => endpointFor(model, this.endpoint),
+				headersFor: (execution, signal) => this.auth.headers(execution, endpointFor(execution.model, this.endpoint), signal),
+				plan,
+				normalize: normalizeAnthropicResponse,
+			});
+		} catch (error) {
+			// Do not retry the search. A subsequent explicit call may exchange
+			// fresh identity after the server rejects a cached access token.
+			if (isProviderError(error) && error.kind === "auth") this.auth.invalidate();
+			throw error;
+		}
 	}
 }
 

package/src/brave-answers.ts

@@ -248,11 +248,13 @@ async function readSseChunks(response: Response, provider: "brave-answers", sign
 	const text = await readBoundedResponseText(response, maxBytes, signal);
 	const events: Record<string, unknown>[] = [];
 	let dataLines: string[] = [];
+	let completed = false;
 	const flush = (): void => {
 		if (dataLines.length === 0) return;
 		const data = dataLines.join("\n").trim();
 		dataLines = [];
-		if (data.length === 0 || data === "[DONE]") return;
+		if (data === "[DONE]") { completed = true; return; }
+		if (data.length === 0) return;
 		try {
 			const parsed = JSON.parse(data) as unknown;
 			if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) events.push(parsed as Record<string, unknown>);
@@ -271,6 +273,10 @@ async function readSseChunks(response: Response, provider: "brave-answers", sign
 		if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
 	}
 	flush();
+	if (!completed) malformed("stream ended before completion");
+	if (events.some(event => event.error != null)) {
+		throw createProviderError({ provider, kind: "http", message: "Brave answer stream reported an error", retryable: false });
+	}
 	return events;
 }
 
@@ -303,6 +309,7 @@ export class BraveAnswersProvider implements Provider {
 		try {
 			response = await this.fetchImpl(this.endpoint, {
 				method: "POST",
+				redirect: "error",
 				headers: {
 					"x-subscription-token": requireApiKey(this.id, this.apiKey),
 					accept: "text/event-stream",
@@ -324,7 +331,7 @@ export class BraveAnswersProvider implements Provider {
 		};
 		if (response.status === 401 || response.status === 403) {
 			const message = await statusMessage();
-			throw createProviderError({ provider: this.id, kind: "auth", message, status: response.status, retryable: false, ...(requestId === undefined ? {} : { requestId }) });
+			throw createProviderError({ provider: this.id, kind: "auth", fallbackSafe: true, message, status: response.status, retryable: false, ...(requestId === undefined ? {} : { requestId }) });
 		}
 		if (response.status === 429) {
 			const message = await statusMessage();

package/src/brave.ts

@@ -25,7 +25,7 @@ export type BraveFetch = (input: string | URL | Request, init?: RequestInit) =>
 export interface BraveCapacityTracker {
 	/** True when no known finite quota window currently blocks a call. */
 	readonly canAttempt: () => boolean;
-	/** Reserve a local request slot, returning false when the caller canceled. */
+	/** Wait for local admission, returning false when the caller canceled. */
 	readonly waitForTurn?: (signal: AbortSignal) => Promise<boolean>;
 	/** Record provider observations without inventing or persisting counters. */
 	readonly observe: (info: ProviderRateLimitInfo | undefined) => void;
@@ -48,6 +48,8 @@ export class BraveQuotaTracker implements BraveCapacityTracker {
 	private observedAtMs = 0;
 	private readonly minimumIntervalMs: number;
 	private nextRequestAtMs = 0;
+	private readonly waiting = new Set<{ signal: AbortSignal; finish: (admitted: boolean) => void }>();
+	private admissionTimer: ReturnType<typeof setTimeout> | undefined;
 
 	constructor(options: BraveQuotaTrackerOptions = {}) {
 		const minimumIntervalMs = options.minimumIntervalMs ?? 0;
@@ -57,30 +59,48 @@ export class BraveQuotaTracker implements BraveCapacityTracker {
 		this.minimumIntervalMs = minimumIntervalMs;
 	}
 
-	async waitForTurn(signal: AbortSignal): Promise<boolean> {
-		if (signal.aborted) return false;
-		const now = Date.now();
-		const startAt = Math.max(now, this.nextRequestAtMs);
-		this.nextRequestAtMs = startAt + this.minimumIntervalMs;
-		const delayMs = startAt - now;
-		if (delayMs <= 0) return true;
+	waitForTurn(signal: AbortSignal): Promise<boolean> {
+		if (signal.aborted) return Promise.resolve(false);
+		if (this.minimumIntervalMs === 0) return Promise.resolve(true);
 		return new Promise<boolean>((resolve) => {
-			let settled = false;
-			let timer: ReturnType<typeof setTimeout> | undefined;
-			const finish = (admitted: boolean): void => {
-				if (settled) return;
-				settled = true;
-				if (timer !== undefined) clearTimeout(timer);
-				signal.removeEventListener("abort", onAbort);
-				resolve(admitted);
+			const waiter = {
+				signal,
+				finish: (admitted: boolean): void => {
+					if (!this.waiting.delete(waiter)) return;
+					signal.removeEventListener("abort", onAbort);
+					if (this.waiting.size === 0 && this.admissionTimer !== undefined) {
+						clearTimeout(this.admissionTimer);
+						this.admissionTimer = undefined;
+					}
+					resolve(admitted);
+				},
 			};
-			const onAbort = (): void => finish(false);
-			timer = setTimeout(() => finish(true), delayMs);
+			const onAbort = (): void => { waiter.finish(false); };
+			this.waiting.add(waiter);
 			signal.addEventListener("abort", onAbort, { once: true });
 			if (signal.aborted) onAbort();
+			this.admitNext();
 		});
 	}
 
+	private admitNext(): void {
+		if (this.admissionTimer !== undefined) return;
+		for (const waiter of this.waiting) {
+			if (waiter.signal.aborted) { waiter.finish(false); continue; }
+			const now = Date.now(), delayMs = this.nextRequestAtMs - now;
+			if (delayMs > 0) {
+				this.admissionTimer = setTimeout(() => {
+					this.admissionTimer = undefined;
+					this.admitNext();
+				}, delayMs);
+				return;
+			}
+			// Only actual admissions consume spacing. Late timers cannot release a burst.
+			this.nextRequestAtMs = now + this.minimumIntervalMs;
+			waiter.finish(true);
+		}
+	}
+
 	canAttempt(): boolean {
 		const info = this.snapshot();
 		if (info === undefined) return true;
@@ -363,6 +383,7 @@ export class BraveProvider implements Provider {
 			throw createProviderError({
 				provider: this.id,
 				kind: "rateLimit",
+				fallbackSafe: true,
 				message: "Brave quota window is exhausted",
 				retryable: true,
 				rateLimits: observed,
@@ -379,6 +400,7 @@ export class BraveProvider implements Provider {
 				throw createProviderError({
 					provider: this.id,
 					kind: "rateLimit",
+					fallbackSafe: true,
 					message: "Brave quota window is exhausted",
 					retryable: true,
 					rateLimits: latest,
@@ -388,16 +410,17 @@ export class BraveProvider implements Provider {
 		}
 		const apiKey = this.apiKey;
 		if (apiKey === undefined || apiKey.trim().length === 0) {
-			throw createProviderError({ provider: this.id, kind: "auth", message: "Brave API key is not configured", retryable: false });
+			throw createProviderError({ provider: this.id, kind: "auth", fallbackSafe: true, message: "Brave API key is not configured", retryable: false });
 		}
 
 		let response: Response;
 		try {
 			response = await this.fetchImpl(plan.url, {
-			method: "GET",
-			headers: { accept: "application/json", "x-subscription-token": apiKey },
-			signal,
-		});
+				method: "GET",
+				redirect: "error",
+				headers: { accept: "application/json", "x-subscription-token": apiKey },
+				signal,
+			});
 		} catch (error) {
 			if (signal.aborted) {
 				throw createProviderError({ provider: this.id, kind: "canceled", message: "Search canceled", retryable: false, cause: error });
@@ -411,7 +434,7 @@ export class BraveProvider implements Provider {
 		const requestId = response.headers.get("x-request-id") ?? response.headers.get("x-brave-request-id") ?? undefined;
 		if (response.status === 401 || response.status === 403) {
 			await cancelResponseBody(response);
-			throw createProviderError({ provider: this.id, kind: "auth", message: `Brave rejected the API key (HTTP ${response.status})`, status: response.status, retryable: false, requestId, rateLimits });
+			throw createProviderError({ provider: this.id, kind: "auth", fallbackSafe: true, message: `Brave rejected the API key (HTTP ${response.status})`, status: response.status, retryable: false, requestId, rateLimits });
 		}
 		if (response.status === 429) {
 			await cancelResponseBody(response);