@nijaru/pi-search 0.0.1

package/src/router.ts

@@ -0,0 +1,302 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Provider, ProviderId, SearchProviderSelection, SearchRequest } from "./contracts";
+import { createProviderError } from "./errors";
+import type { BraveCapacityTracker } from "./brave";
+import { validateSearchRequest } from "./search";
+
+/** Billing choices are an installation policy, not provider fallbacks. */
+export type SearchBillingPolicy = "free-only" | "prefer-free" | "allow-configured-metered";
+
+export interface SearchRouterOptions {
+	readonly openai?: Provider;
+	readonly openaiCodex?: Provider;
+	readonly gemini?: Provider;
+	readonly xai?: Provider;
+	readonly xaiX?: Provider;
+	readonly anthropic?: Provider;
+	readonly meta?: Provider;
+	readonly brave?: Provider;
+	readonly exa?: Provider;
+	readonly parallel?: Provider;
+	readonly parallelResponses?: Provider;
+	readonly braveAnswers?: Provider;
+	readonly x?: Provider;
+	/** Credential presence is supplied by the construction boundary. */
+	readonly braveConfigured?: boolean;
+	readonly exaConfigured?: boolean;
+	readonly parallelConfigured?: boolean;
+	readonly parallelResponsesConfigured?: boolean;
+	readonly braveAnswersConfigured?: boolean;
+	readonly xConfigured?: boolean;
+	/** Explicit user assertion that Brave calls are covered by free capacity. */
+	readonly braveFreeCapacityConfigured?: boolean;
+	readonly braveCapacity?: BraveCapacityTracker;
+	/** Defaults to free-only to prevent an unexpected metered request. */
+	readonly billingPolicy?: SearchBillingPolicy;
+}
+
+export type SearchProviderResolver = (request: SearchRequest, context: ExtensionContext) => SearchProviderSelection;
+
+function unavailable(message: string, provider: ProviderId = "router"): never {
+	throw createProviderError({ provider, kind: "unavailable", message, retryable: false });
+}
+
+function canServe(provider: Provider, request: SearchRequest): boolean {
+	// Search modes are retrieval hints. Providers that cannot guarantee a hint
+	// must report that limitation in their response; hard constraints and
+	// explicit model-mediated options must not be silently dropped.
+	if ((request.domains?.include?.length || request.domains?.exclude?.length) && provider.capabilities.domainFilter !== true) return false;
+	if (request.executionModel !== undefined && provider.profile.auth !== "modelRegistry") return false;
+	if (request.dateRange !== undefined && provider.capabilities.dateFilter !== true) return false;
+	if (request.social !== undefined) {
+		if (provider.capabilities.social !== true) return false;
+		if ((request.social.includeHandles !== undefined || request.social.excludeHandles !== undefined) && provider.capabilities.handleFilter !== true) return false;
+		if ((request.social.understandImages === true || request.social.understandVideos === true) && provider.capabilities.mediaUnderstanding !== true) return false;
+	}
+	if (request.searchContextSize !== undefined && provider.capabilities.searchContextSize !== true) return false;
+	if (request.returnTokenBudget !== undefined && provider.capabilities.returnTokenBudget !== true) return false;
+	if (request.externalWebAccess !== undefined && provider.capabilities.externalWebAccess !== true) return false;
+	if (request.userLocation !== undefined && provider.capabilities.userLocation !== true) return false;
+	if (request.searchContentTypes !== undefined && provider.capabilities.searchContentTypes !== true) return false;
+	if (request.imageSettings !== undefined && provider.capabilities.imageSettings !== true) return false;
+	return true;
+}
+
+/**
+ * Table-driven native registry: adding a model-mediated adapter is one row
+ * here plus the option field above. The Pi model-registry `provider`/`api`
+ * pair is the join key adapters also use in `selectModelExecution`.
+ */
+interface NativeRegistryEntry {
+	readonly modelProvider: string;
+	readonly api: string;
+	readonly option: "openai" | "openaiCodex" | "gemini" | "xai" | "xaiX" | "anthropic" | "meta";
+	readonly label: string;
+}
+
+const NATIVE_REGISTRY: Readonly<Record<string, NativeRegistryEntry>> = {
+	openai: { modelProvider: "openai", api: "openai-responses", option: "openai", label: "OpenAI" },
+	"openai-codex": { modelProvider: "openai-codex", api: "openai-codex-responses", option: "openaiCodex", label: "Codex" },
+	gemini: { modelProvider: "google", api: "google-generative-ai", option: "gemini", label: "Gemini" },
+	xai: { modelProvider: "xai", api: "openai-responses", option: "xai", label: "xAI web" },
+	"xai-x": { modelProvider: "xai", api: "openai-responses", option: "xaiX", label: "xAI X" },
+	anthropic: { modelProvider: "anthropic", api: "anthropic-messages", option: "anthropic", label: "Anthropic" },
+	meta: { modelProvider: "meta", api: "openai-responses", option: "meta", label: "Meta" },
+};
+
+function nativeEntry(provider: ProviderId): NativeRegistryEntry | undefined {
+	return NATIVE_REGISTRY[provider];
+}
+
+function nativeModelCompatible(provider: ProviderId, model: ExtensionContext["model"] | undefined): boolean {
+	if (model === undefined) return false;
+	const entry = nativeEntry(provider);
+	if (entry === undefined) return false;
+	return model.provider === entry.modelProvider && model.api === entry.api;
+}
+
+function availableNativeModel(provider: ProviderId, context: ExtensionContext, requestedModel?: string): boolean {
+	const compatible = (model: NonNullable<ExtensionContext["model"]>): boolean => nativeModelCompatible(provider, model);
+	if (requestedModel !== undefined && context.model !== undefined && compatible(context.model) && context.model.id === requestedModel) return true;
+	if (requestedModel === undefined && nativeModelCompatible(provider, context.model)) return true;
+	try {
+		return context.modelRegistry.getAvailable().some((model) => compatible(model) && (requestedModel === undefined || model.id === requestedModel));
+	} catch {
+		return false;
+	}
+}
+
+/** Active-model dispatch order: the active model's own grounding first. */
+const ACTIVE_NATIVE_IDS = ["openai-codex", "openai", "gemini", "xai", "anthropic", "meta"] as const;
+
+/** Registry fallback order: preserve Pi's built-in search for other active models. */
+const REGISTRY_NATIVE_IDS = ["openai-codex", "openai"] as const;
+
+/**
+ * Resolve the provider for an active-model native id. xAI is the one native
+ * family whose choice depends on the request: X-specific constraints select
+ * the X grounding tool over web search.
+ */
+function activeNativeProvider(id: (typeof ACTIVE_NATIVE_IDS)[number], request: SearchRequest, options: SearchRouterOptions): Provider | undefined {
+	if (id === "xai" && (request.social !== undefined || request.dateRange !== undefined)) return options.xaiX;
+	return options[NATIVE_REGISTRY[id]!.option];
+}
+
+function selection(provider: Provider, automatic: boolean, fallbacks: readonly Provider[] = []): SearchProviderSelection {
+	return { provider, automatic, fallbacks: fallbacks.slice(0, 1) };
+}
+
+function directFallback(
+	primary: Provider,
+	request: SearchRequest,
+	options: SearchRouterOptions,
+	policy: SearchBillingPolicy,
+): readonly Provider[] {
+	if (policy !== "free-only" && primary.id !== "exa" && options.exaConfigured === true && options.exa !== undefined && canServe(options.exa, request)) return [options.exa];
+	const braveAllowed = policy === "allow-configured-metered" || options.braveFreeCapacityConfigured === true;
+	if (primary.id !== "brave" && options.braveConfigured === true && options.brave !== undefined && braveAllowed && canServe(options.brave, request)) return [options.brave];
+	return [];
+}
+
+function checkBraveCapacity(options: SearchRouterOptions): void {
+	if (options.braveCapacity !== undefined && !options.braveCapacity.canAttempt()) {
+		const info = options.braveCapacity.snapshot();
+		throw createProviderError({ provider: "brave", kind: "rateLimit", message: "Brave quota window is exhausted", retryable: true, rateLimits: info, retryAfterMs: info?.retryAfterMs });
+	}
+}
+
+function explicitProvider(
+	request: SearchRequest,
+	context: ExtensionContext,
+	options: SearchRouterOptions,
+	policy: SearchBillingPolicy,
+): SearchProviderSelection {
+	const provider = request.providerHint;
+	if (provider === undefined) return unavailable("No provider was selected");
+	if (request.executionModel !== undefined && provider === "native") return unavailable("executionModel requires an explicit model-mediated provider, not the native alias", provider);
+	if (provider === "native") {
+		// Web-first native ids in registry order; xAI resolves last because the
+		// active model must choose between its web and X grounding tools.
+		for (const id of ["openai", "openai-codex", "gemini", "anthropic", "meta"] as const) {
+			const candidate = options[NATIVE_REGISTRY[id]!.option];
+			if (candidate !== undefined && nativeModelCompatible(id, context.model) && canServe(candidate, request)) return selection(candidate, false);
+		}
+		if (nativeModelCompatible("xai", context.model)) {
+			const selected = request.social !== undefined || request.dateRange !== undefined ? options.xaiX : options.xai;
+			if (selected !== undefined && canServe(selected, request)) return selection(selected, false);
+		}
+		return unavailable("Native search requires an active supported grounded model that can satisfy the requested constraints", provider);
+	}
+	const native = nativeEntry(provider);
+	if (native !== undefined) {
+		const selected = options[native.option];
+		if (selected === undefined) return unavailable(`${native.label} search is not registered`, provider);
+		if (!nativeModelCompatible(provider, context.model) && request.executionModel === undefined) return unavailable(`Cross-provider ${native.label} search requires an explicit executionModel`, provider);
+		if (!availableNativeModel(provider, context, request.executionModel)) {
+			return unavailable(
+				request.executionModel === undefined
+					? `${native.label} native search requires an available model`
+					: `Requested ${native.label} executionModel is not available`,
+				provider,
+			);
+		}
+		if (!canServe(selected, request)) return unavailable(`${native.label} search cannot satisfy the requested search constraints`, provider);
+		return selection(selected, false);
+	}
+	if (provider === "exa") {
+		if (options.exa === undefined || options.exaConfigured !== true) return unavailable("Exa search is not configured", provider);
+		if (!canServe(options.exa, request)) return unavailable("Exa cannot satisfy the requested search constraints", provider);
+		return selection(options.exa, false);
+	}
+	if (provider === "parallel") {
+		if (options.parallel === undefined || options.parallelConfigured !== true) return unavailable("Parallel search is not configured", provider);
+		if (!canServe(options.parallel, request)) return unavailable("Parallel cannot satisfy the requested search constraints", provider);
+		return selection(options.parallel, false);
+	}
+	// Opt-in synthesis providers: explicit hint only, never automatic, never
+	// the native alias. Registered only behind their enable gates.
+	if (provider === "parallel-responses") {
+		if (options.parallelResponses === undefined || options.parallelResponsesConfigured !== true) return unavailable("Parallel Responses is not enabled; set PI_SEARCH_ENABLE_PARALLEL_RESPONSES=1", provider);
+		if (!canServe(options.parallelResponses, request)) return unavailable("Parallel Responses cannot satisfy the requested search constraints", provider);
+		return selection(options.parallelResponses, false);
+	}
+	if (provider === "brave-answers") {
+		if (options.braveAnswers === undefined || options.braveAnswersConfigured !== true) return unavailable("Brave Answers is not enabled; set PI_SEARCH_ENABLE_BRAVE_ANSWERS=1", provider);
+		if (!canServe(options.braveAnswers, request)) return unavailable("Brave Answers cannot satisfy the requested search constraints", provider);
+		return selection(options.braveAnswers, false);
+	}
+	if (provider === "x") {
+		if (options.x === undefined || options.xConfigured !== true) return unavailable("X API search is not configured", provider);
+		if (!canServe(options.x, request)) return unavailable("X API search cannot satisfy the requested search constraints", provider);
+		return selection(options.x, false);
+	}
+	if (provider === "brave") {
+		if (options.brave === undefined || options.braveConfigured !== true) return unavailable("Brave search is not configured", provider);
+		if (policy !== "allow-configured-metered" && options.braveFreeCapacityConfigured !== true) return unavailable("Brave free-mode admission is disabled; set PI_SEARCH_BRAVE_FREE_ONLY=1 or PI_SEARCH_ALLOW_METERED=1", provider);
+		checkBraveCapacity(options);
+		if (!canServe(options.brave, request)) return unavailable("Brave cannot satisfy the requested search constraints", provider);
+		return selection(options.brave, false);
+	}
+	return unavailable(`Search provider ${provider} is not configured`, provider);
+}
+
+/** Human-readable names of the hard constraints a request carries. */
+function unmetConstraintNames(request: SearchRequest): readonly string[] {
+	const names: string[] = [];
+	if (request.domains?.include?.length || request.domains?.exclude?.length) names.push("domain filters");
+	if (request.dateRange !== undefined) names.push("a date range");
+	if (request.social !== undefined) names.push("social/X constraints");
+	if (request.searchContextSize !== undefined) names.push("search context size");
+	if (request.returnTokenBudget !== undefined) names.push("a returned-token budget");
+	if (request.externalWebAccess !== undefined) names.push("live-access selection");
+	if (request.userLocation !== undefined) names.push("a user location");
+	if (request.searchContentTypes !== undefined) names.push("content-type selection");
+	if (request.imageSettings !== undefined) names.push("image result settings");
+	return names;
+}
+
+/** Select one primary provider plus at most one automatic alternative. */
+export function createSearchRouter(options: SearchRouterOptions): SearchProviderResolver {
+	const policy = options.billingPolicy ?? "free-only";
+	return (request, context) => {
+		const normalized = validateSearchRequest(request);
+		if (normalized.executionModel !== undefined && (normalized.providerHint === undefined || normalized.providerHint === "native")) {
+			return unavailable("executionModel requires an explicit model-mediated provider hint", "router");
+		}
+		if (normalized.providerHint !== undefined) return explicitProvider(normalized, context, options, policy);
+
+		// A compatible active native model is the primary choice. A model using a
+		// different API variant (for example OpenAI chat completions) is not a
+		// grounded search backend; continue to registry/native or direct routing
+		// instead of making the user configure a provider manually. When the
+		// active model's native tool cannot honor a hard constraint, continue to
+		// the next eligible path rather than failing after dispatch.
+		for (const id of ACTIVE_NATIVE_IDS) {
+			if (!nativeModelCompatible(id, context.model)) continue;
+			const candidate = activeNativeProvider(id, normalized, options);
+			if (candidate !== undefined && canServe(candidate, normalized)) {
+				return selection(candidate, true, directFallback(candidate, normalized, options, policy));
+			}
+		}
+
+		// Preserve Pi's built-in search when an authenticated same-provider model
+		// exists, even if the active model is OpenRouter, Anthropic, or local.
+		for (const id of REGISTRY_NATIVE_IDS) {
+			const candidate = options[NATIVE_REGISTRY[id]!.option];
+			if (candidate !== undefined && availableNativeModel(id, context) && canServe(candidate, normalized)) {
+				return selection(candidate, true, directFallback(candidate, normalized, options, policy));
+			}
+		}
+
+		const exaConfigured = options.exaConfigured === true;
+		const exaAllowed = policy !== "free-only";
+		const exaCanMatchMode = exaAllowed && options.exa !== undefined && canServe(options.exa, normalized);
+
+		const braveCanMatchMode = options.brave !== undefined && canServe(options.brave, normalized);
+		const braveConfigured = options.braveConfigured === true;
+		const braveAllowed = policy === "allow-configured-metered" || options.braveFreeCapacityConfigured === true;
+		// prefer-free chooses the admitted Brave path before a metered Exa call.
+		if (policy === "prefer-free" && braveCanMatchMode && braveConfigured && braveAllowed) {
+			checkBraveCapacity(options);
+			return selection(options.brave!, true);
+		}
+		if (exaConfigured && exaCanMatchMode) return selection(options.exa!, true, directFallback(options.exa!, normalized, options, policy));
+		if (braveCanMatchMode && braveConfigured && braveAllowed) {
+			checkBraveCapacity(options);
+			return selection(options.brave!, true);
+		}
+		// No direct provider was eligible; name the hard constraints the
+		// configured providers could not honor instead of blaming the retrieval
+		// mode, which never blocks selection on its own.
+		if (exaAllowed && exaConfigured && options.exa !== undefined) {
+			const unmet = unmetConstraintNames(normalized);
+			return unavailable(`Exa cannot satisfy the requested ${unmet.join(", ") || "search constraints"}`, "exa");
+		}
+		if (braveConfigured && !braveAllowed) return unavailable("Brave is configured but free-mode admission is disabled; set PI_SEARCH_BRAVE_FREE_ONLY=1 or PI_SEARCH_ALLOW_METERED=1", "router");
+		if (braveConfigured && options.brave !== undefined) {
+			const unmet = unmetConstraintNames(normalized);
+			return unavailable(`Brave cannot satisfy the requested ${unmet.join(", ") || "search constraints"}`, "brave");
+		}
+		return unavailable("No eligible search provider is configured; configure a provider or use an active grounded model", "router");
+	};
+}

package/src/search-cleanup.ts

@@ -0,0 +1,219 @@
+import type { ProviderId, SearchAnswer, SearchCitation, SearchRequest, SearchResponse, SearchResult, SearchWarning } from "./contracts";
+
+export const MAX_SEARCH_URL_LENGTH = 8_192;
+export const MAX_SEARCH_TITLE_LENGTH = 500;
+export const MAX_SEARCH_EXCERPT_LENGTH = 4_000;
+export const MAX_SEARCH_DOMAIN_LENGTH = 253;
+export const MAX_SEARCH_SOURCE_ID_LENGTH = 500;
+export const MAX_SEARCH_QUERY_LENGTH = 2_000;
+const MAX_SEARCH_ANSWER_LENGTH = 8_000;
+const MAX_SEARCH_CITATIONS = 20;
+// A run this deep is almost always an accidentally nested URL encoding. Keep
+// one safe path prefix rather than surfacing or fetching the encoded tail.
+const REPEATED_PERCENT_ENCODING = /%(?:25){3,}/i;
+
+export interface CanonicalSearchUrl {
+	readonly url: string;
+	readonly domain: string;
+	readonly sourceUrl?: string;
+}
+
+function boundedString(value: unknown, maxLength: number): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	return trimmed.slice(0, maxLength);
+}
+
+/** Normalize URL identity while preserving opaque encoding except for bounded nested-encoding tails. */
+export function normalizeSearchUrl(value: unknown): CanonicalSearchUrl | undefined {
+	if (typeof value !== "string") return undefined;
+	const raw = value.trim();
+	if (raw.length === 0 || raw.length > MAX_SEARCH_URL_LENGTH) return undefined;
+	try {
+		const parsed = new URL(raw);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return undefined;
+		if (parsed.username || parsed.password) return undefined;
+		const repeatedEncoding = REPEATED_PERCENT_ENCODING.exec(parsed.pathname);
+		if (repeatedEncoding !== null && repeatedEncoding.index > 0) {
+			// The prefix is the useful page path. Dropping the encoded suffix is
+			// safer than repeatedly decoding reserved URL characters or sending
+			// a provider-generated encoding bomb through source enrichment.
+			parsed.pathname = parsed.pathname.slice(0, repeatedEncoding.index);
+			parsed.search = "";
+		}
+		parsed.hash = "";
+		parsed.hostname = parsed.hostname.toLowerCase().replace(/\.$/, "");
+		const url = parsed.href;
+		if (url.length > MAX_SEARCH_URL_LENGTH) return undefined;
+		const domain = parsed.hostname.toLowerCase().replace(/\.$/, "");
+		if (domain.length === 0 || domain.length > MAX_SEARCH_DOMAIN_LENGTH) return undefined;
+		return {
+			url,
+			domain,
+			...(url === raw ? {} : { sourceUrl: raw }),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/** Return the conservative identity used to deduplicate search and fetch URLs. */
+export function searchUrlIdentity(value: unknown): string | undefined {
+	return normalizeSearchUrl(value)?.url;
+}
+
+/** Match a canonical result hostname against an exact host or its subdomains. */
+export function matchesSearchDomain(hostname: string, domain: string): boolean {
+	const normalizedHostname = hostname.toLowerCase().replace(/\.$/, "");
+	const normalizedDomain = domain.toLowerCase().replace(/\.$/, "");
+	return normalizedHostname === normalizedDomain || normalizedHostname.endsWith(`.${normalizedDomain}`);
+}
+
+function resultMatchesDomainFilter(result: SearchResult, request: SearchRequest): boolean {
+	const include = request.domains?.include;
+	const exclude = request.domains?.exclude;
+	if (include !== undefined && include.length > 0 && !include.some((domain) => matchesSearchDomain(result.domain ?? "", domain))) {
+		return false;
+	}
+	return exclude === undefined || !exclude.some((domain) => matchesSearchDomain(result.domain ?? "", domain));
+}
+
+function optionalTimestamp(value: unknown): string | undefined {
+	const candidate = boundedString(value, 100);
+	return candidate !== undefined && Number.isFinite(Date.parse(candidate)) ? candidate : undefined;
+}
+
+function optionalScore(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	return Math.max(0, Math.min(1, value));
+}
+
+function normalizeResult(value: unknown, request: SearchRequest, provider: ProviderId): SearchResult | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const result = value as Partial<SearchResult>;
+	const parsed = normalizeSearchUrl(result.url);
+	if (parsed === undefined) return undefined;
+	const title = boundedString(result.title, MAX_SEARCH_TITLE_LENGTH);
+	const publishedAt = optionalTimestamp(result.publishedAt);
+	const excerpt = boundedString(result.excerpt, MAX_SEARCH_EXCERPT_LENGTH);
+	const sourceId = boundedString(result.sourceId, MAX_SEARCH_SOURCE_ID_LENGTH);
+	const score = optionalScore(result.score);
+	const suppliedSource = normalizeSearchUrl(result.sourceUrl);
+	const sourcePage = normalizeSearchUrl(result.sourcePageUrl);
+	const sourceUrl = suppliedSource === undefined
+		? parsed.sourceUrl
+		: suppliedSource.url === parsed.url
+			? parsed.sourceUrl
+			: boundedString(result.sourceUrl, MAX_SEARCH_URL_LENGTH);
+	return {
+		url: parsed.url,
+		...(sourceUrl === undefined ? {} : { sourceUrl }),
+		...(sourcePage === undefined || sourcePage.url === parsed.url ? {} : { sourcePageUrl: sourcePage.url }),
+		...(title === undefined ? {} : { title }),
+		domain: parsed.domain,
+		...(publishedAt === undefined ? {} : { publishedAt }),
+		...(excerpt === undefined ? {} : { excerpt }),
+		provider,
+		searchQuery: request.query,
+		...(sourceId === undefined ? {} : { sourceId }),
+		...(score === undefined ? {} : { score }),
+	};
+}
+
+function normalizeAnswer(answer: SearchAnswer | undefined, provider: ProviderId, results: readonly SearchResult[], request: SearchRequest): SearchAnswer | undefined {
+	if (answer === undefined || request.answerMode === "evidence") return undefined;
+	const text = boundedString(answer.text, MAX_SEARCH_ANSWER_LENGTH);
+	if (text === undefined) return undefined;
+	const resultUrls = new Set(results.map((result) => result.url));
+	const citations: SearchCitation[] = [];
+	for (const citationValue of Array.isArray(answer.citations) ? answer.citations : []) {
+		if (typeof citationValue !== "object" || citationValue === null || Array.isArray(citationValue)) continue;
+		const citation = citationValue as Partial<SearchCitation>;
+		const parsed = normalizeSearchUrl(citation.url);
+		if (parsed === undefined || !resultUrls.has(parsed.url) || citations.some((item) => item.url === parsed.url)) continue;
+		const title = boundedString(citation.title, MAX_SEARCH_TITLE_LENGTH);
+		const sourceId = boundedString(citation.sourceId, MAX_SEARCH_SOURCE_ID_LENGTH);
+		const startIndex = typeof citation.startIndex === "number" && Number.isInteger(citation.startIndex) && citation.startIndex >= 0 && citation.startIndex <= text.length ? citation.startIndex : undefined;
+		const endIndex = typeof citation.endIndex === "number" && Number.isInteger(citation.endIndex) && citation.endIndex >= (startIndex ?? 0) && citation.endIndex <= text.length ? citation.endIndex : undefined;
+		citations.push({
+			url: parsed.url,
+			...(title === undefined ? {} : { title }),
+			...(sourceId === undefined ? {} : { sourceId }),
+			...(startIndex === undefined ? {} : { startIndex }),
+			...(endIndex === undefined ? {} : { endIndex }),
+		});
+		if (citations.length >= MAX_SEARCH_CITATIONS) break;
+	}
+	if (citations.length === 0) return undefined;
+	return {
+		text,
+		contentTrust: "untrusted",
+		provider,
+		...(typeof answer.executionModel === "string" ? { executionModel: answer.executionModel.slice(0, 500) } : {}),
+		citations,
+	};
+}
+
+function mergeResult(current: SearchResult, candidate: SearchResult): SearchResult {
+	return {
+		...current,
+		...(current.sourceUrl === undefined && candidate.sourceUrl !== undefined ? { sourceUrl: candidate.sourceUrl } : {}),
+		...(current.sourcePageUrl === undefined && candidate.sourcePageUrl !== undefined ? { sourcePageUrl: candidate.sourcePageUrl } : {}),
+		...(current.title === undefined && candidate.title !== undefined ? { title: candidate.title } : {}),
+		...(current.publishedAt === undefined && candidate.publishedAt !== undefined ? { publishedAt: candidate.publishedAt } : {}),
+		...(current.excerpt === undefined && candidate.excerpt !== undefined ? { excerpt: candidate.excerpt } : {}),
+		...(current.sourceId === undefined && candidate.sourceId !== undefined ? { sourceId: candidate.sourceId } : {}),
+		...(current.score === undefined && candidate.score !== undefined ? { score: candidate.score } : {}),
+	};
+}
+
+/** Normalize provider output once at the shared search boundary. */
+export function cleanupSearchResponse(response: SearchResponse, request: SearchRequest, provider: ProviderId): SearchResponse {
+	const candidates = Array.isArray(response.results) ? response.results : [];
+	const results = new Map<string, SearchResult>();
+	let discarded = Array.isArray(response.results) ? 0 : 1;
+	let domainDiscarded = 0;
+	for (const value of candidates) {
+		const normalized = normalizeResult(value, request, provider);
+		if (normalized === undefined) {
+			discarded += 1;
+			continue;
+		}
+		if (!resultMatchesDomainFilter(normalized, request)) {
+			domainDiscarded += 1;
+			continue;
+		}
+		const current = results.get(normalized.url);
+		results.set(normalized.url, current === undefined ? normalized : mergeResult(current, normalized));
+	}
+	const warnings: SearchWarning[] = Array.isArray(response.warnings) ? [...response.warnings] : [];
+	if (discarded > 0) {
+		warnings.push({
+			code: "partial-results",
+			message: `Search discarded ${discarded} malformed result entr${discarded === 1 ? "y" : "ies"}`,
+		});
+	}
+	if (domainDiscarded > 0) {
+		warnings.push({
+			code: "partial-results",
+			message: `Search removed ${domainDiscarded} result entr${domainDiscarded === 1 ? "y" : "ies"} outside the requested domain constraints`,
+		});
+	}
+	const normalizedResults = [...results.values()].slice(0, request.maxResults ?? 10);
+	const appliedOptions = [...response.appliedOptions];
+	if ((request.domains?.include?.length ?? 0) > 0 || (request.domains?.exclude?.length ?? 0) > 0) {
+		if (!appliedOptions.includes("domains")) appliedOptions.push("domains");
+	}
+	const answer = normalizeAnswer(response.answer, provider, normalizedResults, request);
+	const { answer: _ignoredAnswer, ...responseWithoutAnswer } = response;
+	return {
+		...responseWithoutAnswer,
+		query: request.query,
+		provider,
+		results: normalizedResults,
+		...(answer === undefined ? {} : { answer }),
+		appliedOptions,
+		warnings,
+	};
+}