@nijaru/pi-search 0.0.1 → 0.0.3

package/src/cloudflare.ts

@@ -0,0 +1,175 @@
+import type {
+	Provider,
+	ProviderCapabilities,
+	ProviderContext,
+	ProviderProfile,
+	SearchOption,
+	SearchRequest,
+	SearchResponse,
+	SearchResult,
+	SearchWarning,
+} from "./contracts";
+import { createProviderError } from "./errors";
+import {
+	DEFAULT_SEARCH_PROVIDER_RESPONSE_BYTES,
+	objectValue,
+	optionalString,
+	postJson,
+	type JsonResponse,
+	type SearchHttpFetch,
+} from "./provider-http";
+import { validateSearchRequest } from "./search";
+import { normalizeSearchUrl } from "./search-cleanup";
+
+export type CloudflareUpstream = "ceramic" | "exa" | "linkup";
+
+export interface CloudflareAdapterOptions {
+	/** Required even though Cloudflare itself defaults to Ceramic. */
+	readonly upstream: CloudflareUpstream;
+	readonly accountId?: string;
+	readonly apiToken?: string;
+	readonly gatewayId?: string;
+	/** An explicit alias makes Cloudflare fail rather than fall back to gateway credits. */
+	readonly byokAlias?: string;
+	readonly fetchImpl?: SearchHttpFetch;
+	readonly maxResponseBytes?: number;
+}
+
+const capabilities: ProviderCapabilities = { semantic: true, excerpts: true };
+// BYOK agreements and gateway credits do not establish actual billed costs.
+const profile: ProviderProfile = { auth: "environment", costModel: "unknown" };
+const unsupportedOptions = [
+	"domains", "dateRange", "social", "executionModel", "searchContextSize",
+	"returnTokenBudget", "externalWebAccess", "userLocation", "searchContentTypes", "imageSettings",
+] as const satisfies readonly SearchOption[];
+
+function configurationError(message: string, kind: "auth" | "badRequest" = "badRequest"): never {
+	throw createProviderError({ provider: "cloudflare", kind, message, retryable: false });
+}
+
+function requiredSetting(value: string | undefined, name: string, kind: "auth" | "badRequest"): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return configurationError(`Cloudflare ${name} is not configured`, kind);
+	}
+	return value.trim();
+}
+
+function malformed(message: string): never {
+	throw createProviderError({ provider: "cloudflare", kind: "malformed", message: `Cloudflare returned a malformed response (${message})`, retryable: false });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeResponse(result: JsonResponse, request: SearchRequest, upstream: CloudflareUpstream): SearchResponse {
+	const root = objectValue(result.payload, "response", "cloudflare");
+	if (!Array.isArray(root.items)) return malformed("items is not an array");
+	const metadata = isRecord(root.metadata) ? root.metadata : {};
+	const query = request.query;
+	const results: SearchResult[] = [];
+	let discarded = 0;
+	for (const item of root.items) {
+		const parsed = isRecord(item) ? normalizeSearchUrl(item.url) : undefined;
+		if (!isRecord(item) || parsed === undefined) {
+			discarded += 1;
+			continue;
+		}
+		results.push({
+			...parsed,
+			title: optionalString(item.title, 500),
+			excerpt: optionalString(item.description, 4_000),
+			// Keep both the gateway service and the selected upstream inspectable.
+			provider: "cloudflare",
+			upstreamProvider: upstream,
+			searchQuery: query,
+		});
+	}
+	if (discarded > 0 && results.length === 0) return malformed("items contained no parseable HTTP URLs");
+	const requestId = result.requestId ?? optionalString(metadata.requestId, 500);
+	const latencyMs = typeof metadata.latencyMs === "number" && Number.isFinite(metadata.latencyMs) && metadata.latencyMs >= 0 ? metadata.latencyMs : undefined;
+	// imageUrl/faviconUrl have no evidence-result contract; lastModifiedDate is
+	// not a publication date. Do not mislabel these optional documented fields.
+	return {
+		query,
+		results: results.slice(0, request.maxResults ?? 10),
+		provider: "cloudflare",
+		upstreamProvider: upstream,
+		appliedOptions: ["maxResults"],
+		warnings: discarded > 0 ? [{ code: "partial-results", message: `Cloudflare discarded ${discarded} malformed result entr${discarded === 1 ? "y" : "ies"}` }] : [],
+		...(requestId === undefined ? {} : { requestId }),
+		...(latencyMs === undefined ? {} : { latencyMs }),
+		...(result.rateLimits === undefined ? {} : { usage: { rateLimits: result.rateLimits } }),
+	};
+}
+
+export class CloudflareProvider implements Provider {
+	readonly id = "cloudflare" as const;
+	readonly capabilities = capabilities;
+	readonly profile = profile;
+	private readonly upstream: CloudflareUpstream;
+	private readonly accountId?: string;
+	private readonly apiToken?: string;
+	private readonly gatewayId: string;
+	private readonly byokAlias?: string;
+	private readonly fetchImpl: SearchHttpFetch;
+	private readonly maxResponseBytes: number;
+
+	constructor(options: CloudflareAdapterOptions) {
+		this.upstream = options.upstream;
+		this.accountId = options.accountId;
+		this.apiToken = options.apiToken;
+		this.gatewayId = options.gatewayId ?? "default";
+		this.byokAlias = options.byokAlias;
+		this.fetchImpl = options.fetchImpl ?? (fetch as SearchHttpFetch);
+		this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_SEARCH_PROVIDER_RESPONSE_BYTES;
+		if (!Number.isInteger(this.maxResponseBytes) || this.maxResponseBytes < 1) {
+			throw new Error("Cloudflare maxResponseBytes must be a positive integer");
+		}
+	}
+
+	async search(request: SearchRequest, signal: AbortSignal, _context: ProviderContext): Promise<SearchResponse> {
+		const normalized = validateSearchRequest(request);
+		if (normalized.query.length > 1_024) return configurationError("Cloudflare search query must be at most 1024 characters");
+		if ((normalized.maxResults ?? 10) > 10) return configurationError("Cloudflare search maxResults must be at most 10");
+		for (const option of unsupportedOptions) {
+			if (normalized[option] !== undefined) {
+				throw createProviderError({ provider: this.id, kind: "unsupported", message: `Cloudflare Web Search does not support ${option}`, retryable: false });
+			}
+		}
+		if (!["ceramic", "exa", "linkup"].includes(this.upstream)) {
+			return configurationError("Cloudflare upstream must be explicitly configured as ceramic, exa, or linkup");
+		}
+		const accountId = requiredSetting(this.accountId, "account ID", "auth");
+		const apiToken = requiredSetting(this.apiToken, "API token", "auth");
+		const gatewayId = requiredSetting(this.gatewayId, "gateway ID", "badRequest");
+		if (this.byokAlias !== undefined && !/^[A-Za-z0-9_-]{1,64}$/.test(this.byokAlias)) {
+			return configurationError("Cloudflare byokAlias must contain 1-64 letters, digits, underscores, or hyphens");
+		}
+		const warnings: SearchWarning[] = normalized.mode === "keyword" || normalized.mode === "fresh"
+			? [{ code: "unsupported-option", option: "mode", message: `Cloudflare Web Search does not guarantee ${normalized.mode === "keyword" ? "keyword-only ranking" : "freshness"}; the configured upstream uses its standard retrieval mode` }]
+			: [];
+		const result = await postJson({
+			provider: this.id,
+			url: `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/websearch/`,
+			headers: { authorization: `Bearer ${apiToken}` },
+			body: {
+				query: normalized.query,
+				provider: this.upstream,
+				limit: normalized.maxResults,
+				options: { gateway: { id: gatewayId } },
+				...(this.byokAlias === undefined ? {} : { byokAlias: this.byokAlias }),
+			},
+			signal,
+			fetchImpl: this.fetchImpl,
+			maxResponseBytes: this.maxResponseBytes,
+		});
+		const response = normalizeResponse(result, normalized, this.upstream);
+		return { ...response, warnings: [...warnings, ...response.warnings] };
+	}
+}
+
+/** Register only for explicitly opted-in calls; this factory performs no I/O or global credential lookup. */
+export function createCloudflareProvider(options: CloudflareAdapterOptions): CloudflareProvider {
+	return new CloudflareProvider(options);
+}

package/src/codex.ts

@@ -252,17 +252,17 @@ function normalizeCodexResponse(payload: unknown, request: SearchRequest): Searc
 
 function codexHeaders(execution: ModelExecution): Readonly<Record<string, string>> {
 	const headers = modelAuthHeaders(execution);
-	if (execution.auth.apiKey === undefined || execution.auth.apiKey.trim().length === 0) {
-		throw createProviderError({ provider: "openai-codex", kind: "auth", message: "Codex authentication returned no token", retryable: false });
+	if (!headers.get("authorization")?.trim()) {
+		throw createProviderError({ provider: "openai-codex", kind: "auth", fallbackSafe: true, message: "Codex authentication returned no token", retryable: false });
 	}
-	const parts = execution.auth.apiKey.split(".");
+	const parts = headers.get("authorization")!.replace(/^Bearer\s+/i, "").split(".");
 	if (parts.length === 3 && parts[1] !== undefined) {
 		try {
 			const decoded = JSON.parse(Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(parts[1].length / 4) * 4, "="), "base64").toString("utf8")) as Record<string, unknown>;
 			const auth = decoded["https://api.openai.com/auth"];
 			if (auth !== null && typeof auth === "object" && !Array.isArray(auth)) {
 				const accountId = optionalString((auth as Record<string, unknown>).chatgpt_account_id, 500);
-				if (accountId !== undefined) headers.set("chatgpt-account-id", accountId);
+				if (accountId !== undefined && !headers.has("chatgpt-account-id")) headers.set("chatgpt-account-id", accountId);
 			}
 		} catch {
 			// The backend may authenticate non-JWT tokens through headers alone.

package/src/contracts.ts

@@ -55,6 +55,10 @@ export type ProviderAuthResult =
 			readonly ok: true;
 			readonly apiKey?: string;
 			readonly headers?: ProviderHeaders;
+			/** Provider-resolved endpoint override; wins over the catalog `baseUrl`. */
+			readonly baseUrl?: string;
+			/** Provider-scoped environment credentials resolved with the request. */
+			readonly env?: Readonly<Record<string, string>>;
 		}
 	| {
 			readonly ok: false;
@@ -148,6 +152,8 @@ export interface ProviderCapabilities {
 	readonly excerpts?: boolean;
 	/** Supports domain include/exclude filters. */
 	readonly domainFilter?: boolean;
+	/** False when includes and excludes are individually supported but cannot be combined. */
+	readonly combinedDomainFilters?: boolean;
 	/** Supports provider-enforced date ranges. */
 	readonly dateFilter?: boolean;
 	/** Searches social sources such as X. */
@@ -339,8 +345,10 @@ export interface SearchResult {
 	 * when the provider exposes any text; never synthesized.
 	 */
 	readonly excerpt?: string;
-	/** The provider that produced this result. */
+	/** Adapter that served this result. */
 	readonly provider: ProviderId;
+	/** Search backend behind a gateway adapter, when applicable. */
+	readonly upstreamProvider?: ProviderId;
 	/** The query that produced this result. */
 	readonly searchQuery: string;
 	/** Provider-internal id for the result, for citation/debugging. */
@@ -364,8 +372,10 @@ export interface SearchResponse {
 	readonly answer?: SearchAnswer;
 	/** Bounded source pages fetched after search when requested. */
 	readonly sourceContents?: readonly FetchedContent[];
-	/** Which provider actually served the request. */
+	/** Which adapter actually served the request. */
 	readonly provider: ProviderId;
+	/** Search backend behind a gateway adapter, when applicable. */
+	readonly upstreamProvider?: ProviderId;
 	/** Model used by a model-mediated provider, when available. */
 	readonly executionModel?: string;
 	/** Providers attempted by bounded automatic routing, in order. */
@@ -415,8 +425,10 @@ export type ResearchStopReason = "completed" | "partial" | "budget" | "deadline"
 
 export interface ResearchResponse {
 	readonly question: string;
-	/** The single provider selected for the whole research invocation. */
+	/** The single adapter selected for the whole research invocation. */
 	readonly provider: ProviderId;
+	/** Search backend behind a gateway adapter, when applicable. */
+	readonly upstreamProvider?: ProviderId;
 	/** Model used when the selected provider is model-mediated. */
 	readonly executionModel?: string;
 	readonly results: readonly SearchResult[];
@@ -554,6 +566,7 @@ export type ProviderId =
 	| "gemini"
 	| "brave"
 	| "exa"
+	| "cloudflare"
 	| "parallel"
 	| "parallel-responses"
 	| "brave-answers"
@@ -571,6 +584,7 @@ export const SEARCH_PROVIDER_HINT_IDS = [
 	"gemini",
 	"brave",
 	"exa",
+	"cloudflare",
 	"parallel",
 	"parallel-responses",
 	"brave-answers",
@@ -609,6 +623,10 @@ export interface ProviderError extends Error {
 	readonly retryAfterMs?: number;
 	/** Provider-reported quota metadata. */
 	readonly rateLimits?: ProviderRateLimitInfo;
+	/** Usage already reported even when a dispatched call fails. */
+	readonly usage?: ProviderUsage;
+	/** Explicit proof that another provider cannot compound uncertain billing. */
+	readonly fallbackSafe?: boolean;
 	/** Whether retrying the same provider could help. */
 	readonly retryable: boolean;
 }

package/src/errors.ts

@@ -1,4 +1,4 @@
-import type { ProviderError, ProviderId, ProviderRateLimitInfo, RequestId } from "./contracts";
+import type { ProviderError, ProviderId, ProviderRateLimitInfo, ProviderUsage, RequestId } from "./contracts";
 
 export interface ProviderErrorOptions {
 	readonly provider: ProviderId;
@@ -9,6 +9,8 @@ export interface ProviderErrorOptions {
 	readonly requestId?: RequestId;
 	readonly retryAfterMs?: number;
 	readonly rateLimits?: ProviderRateLimitInfo;
+	readonly fallbackSafe?: boolean;
+	readonly usage?: ProviderUsage;
 	readonly cause?: unknown;
 }
 
@@ -21,6 +23,8 @@ export class SearchProviderError extends Error implements ProviderError {
 	readonly requestId?: RequestId;
 	readonly retryAfterMs?: number;
 	readonly rateLimits?: ProviderRateLimitInfo;
+	readonly fallbackSafe: boolean;
+	readonly usage?: ProviderUsage;
 
 	constructor(options: ProviderErrorOptions) {
 		super(options.message, { cause: options.cause });
@@ -32,6 +36,8 @@ export class SearchProviderError extends Error implements ProviderError {
 		this.requestId = options.requestId;
 		this.retryAfterMs = options.retryAfterMs;
 		this.rateLimits = options.rateLimits;
+		this.fallbackSafe = options.fallbackSafe === true;
+		this.usage = options.usage;
 	}
 }
 
@@ -81,6 +87,8 @@ export class SearchToolError extends Error {
 	readonly requestId?: RequestId;
 	readonly retryAfterMs?: number;
 	readonly rateLimits?: ProviderRateLimitInfo;
+	readonly fallbackSafe: boolean;
+	readonly usage?: ProviderUsage;
 
 	constructor(
 		code: SearchToolErrorCode,
@@ -93,6 +101,8 @@ export class SearchToolError extends Error {
 			readonly requestId?: RequestId;
 			readonly retryAfterMs?: number;
 			readonly rateLimits?: ProviderRateLimitInfo;
+			readonly fallbackSafe?: boolean;
+			readonly usage?: ProviderUsage;
 		} = {},
 	) {
 		super(`${code}: ${message}`);
@@ -105,6 +115,8 @@ export class SearchToolError extends Error {
 		this.requestId = options.requestId;
 		this.retryAfterMs = options.retryAfterMs;
 		this.rateLimits = options.rateLimits;
+		this.fallbackSafe = options.fallbackSafe === true;
+		this.usage = options.usage;
 	}
 }
 
@@ -154,6 +166,8 @@ export function toSearchToolError(error: unknown, provider: ProviderId): SearchT
 			requestId: error.requestId,
 			retryAfterMs: error.retryAfterMs,
 			rateLimits: error.rateLimits,
+			fallbackSafe: error.fallbackSafe,
+			usage: error.usage,
 		});
 	}
 	const message = error instanceof Error ? error.message : "Unknown search failure";

package/src/gemini.ts

@@ -14,7 +14,7 @@ import { createProviderError } from "./errors";
 import { cancelResponseBody } from "./http";
 import { executeGroundedSearch } from "./grounding";
 import { httpSource, objectValue, optionalString, type SearchHttpFetch } from "./provider-http";
-import { modelAuthHeaders, type ModelExecution } from "./model-selection";
+import { hasExplicitHeader, modelAuthHeaders, type ModelExecution } from "./model-selection";
 import { validateSearchRequest } from "./search";
 
 export const GEMINI_GENERATE_CONTENT_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta";
@@ -88,9 +88,16 @@ function endpointFor(model: ProviderModel, override?: string): string {
 
 function authHeaders(execution: ModelExecution): Readonly<Record<string, string>> {
 	const headers = modelAuthHeaders(execution, { bearerApiKey: false });
-	if (execution.auth.apiKey !== undefined && execution.auth.apiKey.trim().length > 0) headers.set("x-goog-api-key", execution.auth.apiKey);
+	// An explicit x-goog-api-key (value or null deletion) wins over a derived key.
+	if (
+		execution.auth.apiKey !== undefined &&
+		execution.auth.apiKey.trim().length > 0 &&
+		!hasExplicitHeader([execution.model.headers, execution.auth.headers], "x-goog-api-key")
+	) {
+		headers.set("x-goog-api-key", execution.auth.apiKey);
+	}
 	if (!headers.has("x-goog-api-key")) {
-		throw createProviderError({ provider: "gemini", kind: "auth", message: "Gemini authentication returned no API key", retryable: false });
+		throw createProviderError({ provider: "gemini", kind: "auth", fallbackSafe: true, message: "Gemini authentication returned no API key", retryable: false });
 	}
 	return Object.fromEntries(headers.entries());
 }

package/src/grounding.ts

@@ -1,3 +1,4 @@
+import type { Usage } from "@earendil-works/pi-ai";
 import type {
 	ProviderContext,
 	ProviderId,
@@ -52,6 +53,19 @@ export function tokenUsage(
 	};
 }
 
+/** Report known nested usage to Pi; unknown token/cost categories stay zero. */
+export function toolUsage(usage: ProviderUsage | undefined): Usage | undefined {
+	if (usage === undefined || (usage.inputTokens === undefined && usage.outputTokens === undefined && usage.totalTokens === undefined && usage.costUsd === undefined)) return undefined;
+	return {
+		input: usage.inputTokens ?? 0,
+		output: usage.outputTokens ?? 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0),
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: usage.costUsd ?? 0 },
+	};
+}
+
 /** Merge provider-reported usage with observed transport rate limits. */
 export function usageWithRateLimits(
 	usage: ProviderUsage | undefined,
@@ -85,7 +99,7 @@ export function assertHttpEndpoint(candidate: string, provider: ProviderId, labe
 export function bearerAuthHeaders(execution: ModelExecution, provider: ProviderId): Readonly<Record<string, string>> {
 	const headers = modelAuthHeaders(execution);
 	if (!headers.has("authorization")) {
-		throw createProviderError({ provider, kind: "auth", message: "Model authentication returned no authorization header", retryable: false });
+		throw createProviderError({ provider, kind: "auth", fallbackSafe: true, message: "Model authentication returned no authorization header", retryable: false });
 	}
 	return Object.fromEntries(headers.entries());
 }
@@ -105,7 +119,7 @@ export interface GroundedSearchOptions {
 	 */
 	readonly includeModel?: boolean;
 	readonly endpointFor: (model: ProviderModel) => string;
-	readonly headersFor: (execution: ModelExecution) => Readonly<Record<string, string>>;
+	readonly headersFor: (execution: ModelExecution, signal: AbortSignal) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
 	readonly plan: GroundingPlan;
 	readonly normalize: (
 		payload: unknown,
@@ -145,7 +159,7 @@ export async function executeGroundedSearch(options: GroundedSearchOptions): Pro
 	const result = await postJson({
 		provider: options.provider,
 		url: options.endpointFor(execution.model),
-		headers: options.headersFor(execution),
+		headers: await options.headersFor(execution, options.signal),
 		body: options.includeModel === false ? options.plan.body : { ...options.plan.body, model: execution.model.id },
 		signal: options.signal,
 		fetchImpl: options.fetchImpl,

package/src/index.ts

@@ -4,6 +4,7 @@ import { createBraveProvider, BraveQuotaTracker } from "./brave";
 import { createBraveAnswersProvider } from "./brave-answers";
 import { createCodexProvider } from "./codex";
 import { createExaProvider } from "./exa";
+import { createCloudflareProvider, type CloudflareUpstream } from "./cloudflare";
 import { createGeminiProvider } from "./gemini";
 import { registerWebFetch } from "./fetch-tool";
 import { createOpenAIProvider } from "./openai";
@@ -13,7 +14,6 @@ import { createMetaProvider } from "./meta";
 import { createSearchRouter } from "./router";
 import { createXProvider } from "./x";
 import { createXAIProvider } from "./xai";
-import { adaptLocalLlamaPayload, isLocalOpenAICompatibleModel } from "./local-llama-compat";
 import { availableProviderHints } from "./provider-availability";
 import { registerWebResearch } from "./research-tool";
 import { registerWebSearch } from "./search-tool";
@@ -43,6 +43,19 @@ export default function (pi: ExtensionAPI): void {
 	const parallelKey = process.env.PARALLEL_API_KEY;
 	const xToken = process.env.X_API_BEARER_TOKEN;
 	const exa = createExaProvider({ apiKey: exaKey });
+	const cloudflareUpstream = process.env.PI_SEARCH_CLOUDFLARE_PROVIDER;
+	const cloudflareAccount = process.env.CLOUDFLARE_ACCOUNT_ID;
+	const cloudflareToken = process.env.CLOUDFLARE_API_TOKEN;
+	// Credentials alone do not enable gateway spending or select Ceramic.
+	const cloudflareConfigured = ["ceramic", "exa", "linkup"].includes(cloudflareUpstream ?? "")
+		&& Boolean(cloudflareAccount?.trim()) && Boolean(cloudflareToken?.trim());
+	const cloudflare = cloudflareConfigured ? createCloudflareProvider({
+		upstream: cloudflareUpstream as CloudflareUpstream,
+		accountId: cloudflareAccount,
+		apiToken: cloudflareToken,
+		gatewayId: process.env.PI_SEARCH_CLOUDFLARE_GATEWAY_ID,
+		byokAlias: process.env.PI_SEARCH_CLOUDFLARE_BYOK_ALIAS,
+	}) : undefined;
 	const parallel = createParallelProvider({ apiKey: parallelKey });
 	const x = createXProvider({ bearerToken: xToken });
 	// Opt-in answer-synthesis providers: the enable gate alone controls
@@ -66,6 +79,8 @@ export default function (pi: ExtensionAPI): void {
 		anthropic,
 		meta,
 		exa,
+		cloudflare,
+		cloudflareConfigured,
 		parallel,
 		parallelResponses,
 		braveAnswers,
@@ -87,14 +102,11 @@ export default function (pi: ExtensionAPI): void {
 		brave: braveKey !== undefined && braveKey.trim().length > 0,
 		braveAnswers: braveAnswersEnabled,
 		exa: exaKey !== undefined && exaKey.trim().length > 0,
+		cloudflare: cloudflareConfigured,
 		parallel: parallelKey !== undefined && parallelKey.trim().length > 0,
 		parallelResponses: parallelResponsesEnabled,
 		x: xToken !== undefined && xToken.trim().length > 0,
 	});
-	pi.on("before_provider_request", (event, context) => {
-		if (!isLocalOpenAICompatibleModel(context.model)) return;
-		return adaptLocalLlamaPayload(event.payload);
-	});
 	registerWebSearch(pi, route, { availableProviderHints: availableHints });
 	registerWebFetch(pi);
 	registerWebResearch(pi, route, { availableProviderHints: availableHints });

package/src/model-selection.ts

@@ -54,7 +54,7 @@ function candidates(options: ModelSelectionOptions): ProviderModel[] {
 export async function selectModelExecution(options: ModelSelectionOptions): Promise<ModelExecution> {
 	const registry = options.context.modelRegistry;
 	if (registry === undefined) {
-		throw createProviderError({ provider: options.searchProvider, kind: "auth", message: "Pi model authentication is unavailable", retryable: false });
+		throw createProviderError({ provider: options.searchProvider, kind: "auth", fallbackSafe: true, message: "Pi model authentication is unavailable", retryable: false });
 	}
 	const available = candidates(options);
 	const requested = options.request.executionModel;
@@ -104,12 +104,14 @@ async function authenticate(model: ProviderModel, registry: NonNullable<Provider
 	try {
 		auth = await registry.getApiKeyAndHeaders(model);
 	} catch (error) {
-		throw createProviderError({ provider: options.searchProvider, kind: "auth", message: "Pi model authentication could not be resolved", retryable: false, cause: error });
+		throw createProviderError({ provider: options.searchProvider, kind: "auth", fallbackSafe: true, message: "Pi model authentication could not be resolved", retryable: false, cause: error });
 	}
 	if (!auth.ok) {
-		throw createProviderError({ provider: options.searchProvider, kind: "auth", message: `Pi model authentication is not configured for ${model.id}`, retryable: false });
+		throw createProviderError({ provider: options.searchProvider, kind: "auth", fallbackSafe: true, message: `Pi model authentication is not configured for ${model.id}`, retryable: false });
 	}
-	return { model, auth };
+	// A provider-resolved endpoint wins over the catalog base URL, matching
+	// `ModelRegistry.stream()`; adapters build their request URL from this model.
+	return { model: auth.baseUrl ? { ...model, baseUrl: auth.baseUrl } : model, auth };
 }
 
 export interface ModelAuthHeaderOptions {
@@ -125,10 +127,26 @@ export function applyProviderHeaders(headers: Headers, source: ProviderHeaders |
 	}
 }
 
+/**
+ * Whether any source declares a header, including a `null` deletion. An explicit
+ * `authorization` entry must win over a bearer synthesized from the API key.
+ */
+export function hasExplicitHeader(sources: readonly (ProviderHeaders | undefined)[], name: string): boolean {
+	const lower = name.toLowerCase();
+	return sources.some((source) => source !== undefined && Object.keys(source).some((key) => key.toLowerCase() === lower));
+}
+
 export function modelAuthHeaders(execution: ModelExecution, options: ModelAuthHeaderOptions = {}): Headers {
 	const headers = new Headers();
 	applyProviderHeaders(headers, execution.model.headers);
 	applyProviderHeaders(headers, execution.auth.headers);
-	if (options.bearerApiKey !== false && execution.auth.apiKey !== undefined && execution.auth.apiKey.trim().length > 0) headers.set("authorization", `Bearer ${execution.auth.apiKey}`);
+	if (
+		options.bearerApiKey !== false &&
+		execution.auth.apiKey !== undefined &&
+		execution.auth.apiKey.trim().length > 0 &&
+		!hasExplicitHeader([execution.model.headers, execution.auth.headers], "authorization")
+	) {
+		headers.set("authorization", `Bearer ${execution.auth.apiKey}`);
+	}
 	return headers;
 }