@nijaru/pi-search 0.0.2 → 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

@@ -152,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. */
@@ -343,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. */
@@ -368,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. */
@@ -419,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[];
@@ -558,6 +566,7 @@ export type ProviderId =
 	| "gemini"
 	| "brave"
 	| "exa"
+	| "cloudflare"
 	| "parallel"
 	| "parallel-responses"
 	| "brave-answers"
@@ -575,6 +584,7 @@ export const SEARCH_PROVIDER_HINT_IDS = [
 	"gemini",
 	"brave",
 	"exa",
+	"cloudflare",
 	"parallel",
 	"parallel-responses",
 	"brave-answers",
@@ -613,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

@@ -97,7 +97,7 @@ function authHeaders(execution: ModelExecution): Readonly<Record<string, string>
 		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,10 +104,10 @@ 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 });
 	}
 	// A provider-resolved endpoint wins over the catalog base URL, matching
 	// `ModelRegistry.stream()`; adapters build their request URL from this model.

package/src/openai.ts

@@ -16,7 +16,7 @@ import type {
 import { createProviderError, isProviderError } from "./errors";
 import { applyProviderHeaders, hasExplicitHeader } from "./model-selection";
 import { cancelResponseBody, readBoundedResponseText } from "./http";
-import { parseProviderRateLimits } from "./provider-http";
+import { parseProviderRateLimits, retryAfterMsFromHeaders as parseRetryAfter } from "./provider-http";
 import { validateSearchRequest } from "./search";
 import { normalizeSearchUrl } from "./search-cleanup";
 
@@ -420,7 +420,7 @@ function searchModelCandidates(
 async function selectSearchExecution(active: ProviderModel | undefined, registry: ProviderContext["modelRegistry"], request: SearchRequest): Promise<SearchExecution> {
 	const provider = "openai" as const;
 	if (registry === undefined) {
-		throw createProviderError({ provider, kind: "auth", message: "Pi model authentication is unavailable", retryable: false });
+		throw createProviderError({ provider, kind: "auth", fallbackSafe: true, message: "Pi model authentication is unavailable", retryable: false });
 	}
 	const candidates = searchModelCandidates(active, registry, request.executionModel);
 	const selectedCandidates = request.executionModel === undefined
@@ -442,19 +442,19 @@ async function selectSearchExecution(active: ProviderModel | undefined, registry
 		try {
 			auth = await registry.getApiKeyAndHeaders(selected);
 		} catch (error) {
-			throw createProviderError({ provider, kind: "auth", message: "Pi model authentication could not be resolved", retryable: false, cause: error });
+			throw createProviderError({ provider, kind: "auth", fallbackSafe: true, message: "Pi model authentication could not be resolved", retryable: false, cause: error });
 		}
 		// A provider-resolved endpoint wins over the catalog base URL; the adapter
 		// builds its request URL from this model. Mirrors selectModelExecution().
 		if (auth.ok) return { model: auth.baseUrl ? { ...selected, baseUrl: auth.baseUrl } : selected, auth };
 		if (request.executionModel !== undefined) {
-			throw createProviderError({ provider, kind: "auth", message: `Pi model authentication is not configured for ${selected.id}`, retryable: false });
+			throw createProviderError({ provider, kind: "auth", fallbackSafe: true, message: `Pi model authentication is not configured for ${selected.id}`, retryable: false });
 		}
 	}
 
 	throw createProviderError({
 		provider,
-		kind: "auth",
+		kind: "auth", fallbackSafe: true,
 		message: `No authenticated ${provider} Responses model is available for native search`,
 		retryable: false,
 	});
@@ -616,22 +616,6 @@ async function readBody(response: Response, signal: AbortSignal, maxBytes: numbe
 	}
 }
 
-function parseRetryAfter(headers: Headers): number | undefined {
-	const milliseconds = headers.get("retry-after-ms");
-	if (milliseconds !== null && /^\d+(?:\.\d+)?$/.test(milliseconds.trim())) {
-		const value = Number(milliseconds);
-		if (Number.isFinite(value)) return Math.max(0, Math.round(value));
-	}
-	const retryAfter = headers.get("retry-after");
-	if (retryAfter === null) return undefined;
-	if (/^\d+(?:\.\d+)?$/.test(retryAfter.trim())) {
-		const value = Number(retryAfter);
-		return Number.isFinite(value) ? Math.max(0, Math.round(value * 1_000)) : undefined;
-	}
-	const date = Date.parse(retryAfter);
-	return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
-}
-
 function parseSseEventData(body: string, provider: OpenAIProviderId): readonly Record<string, unknown>[] {
 	const events: Record<string, unknown>[] = [];
 	let dataLines: string[] = [];
@@ -661,7 +645,7 @@ function parseSseEventData(body: string, provider: OpenAIProviderId): readonly R
 	return events;
 }
 
-function parseResponseBody(body: string, provider: OpenAIProviderId): Record<string, unknown> {
+function parseResponseBody(body: string, provider: OpenAIProviderId, secrets: readonly string[]): Record<string, unknown> {
 	const trimmed = body.trim();
 	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
 		try {
@@ -682,7 +666,8 @@ function parseResponseBody(body: string, provider: OpenAIProviderId): Record<str
 	for (const event of parseSseEventData(body, provider)) {
 		const type = String(event.type ?? "");
 		if (type === "error") {
-			throw createProviderError({ provider, kind: "http", message: "OpenAI web search returned an error event", retryable: false });
+			const diagnostic = sanitizeErrorDiagnostic(JSON.stringify(event), secrets);
+			throw createProviderError({ provider, kind: "http", message: `OpenAI web search returned an error event${diagnostic === undefined ? "" : `: ${diagnostic}`}`, retryable: false });
 		}
 		if (type === "response.output_item.done" && event.item !== undefined) output.push(event.item);
 		if (["response.done", "response.completed", "response.incomplete", "response.failed"].includes(type)) {
@@ -770,11 +755,7 @@ export class OpenAIProvider implements Provider {
 			throw createProviderError({ provider: this.id, kind: "canceled", message: "Search canceled", retryable: false });
 		}
 
-		const body = {
-			...plan.body,
-			model: execution.model.id,
-			max_output_tokens: 2_048,
-		};
+		const endpoint = endpointFor(execution.model, this.endpoint);
 		const headers = new Headers();
 		applyProviderHeaders(headers, execution.model.headers);
 		applyProviderHeaders(headers, execution.auth.headers);
@@ -786,8 +767,17 @@ export class OpenAIProvider implements Provider {
 			headers.set("Authorization", `Bearer ${execution.auth.apiKey}`);
 		}
 		if (!headers.has("authorization")) {
-			throw createProviderError({ provider: this.id, kind: "auth", message: "Pi model authentication returned no authorization header", retryable: false });
+			throw createProviderError({ provider: this.id, kind: "auth", fallbackSafe: true, message: "Pi model authentication returned no authorization header", retryable: false });
 		}
+		// Pi's direct ChatGPT sign-in uses a non-sk bearer on the OpenAI API.
+		// That auth path rejects max_output_tokens; API keys and proxies do not.
+		const bearer = headers.get("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+		const chatGPT = endpoint === OPENAI_RESPONSES_ENDPOINT && bearer !== undefined && !bearer.startsWith("sk-");
+		const body = {
+			...plan.body,
+			model: execution.model.id,
+			...(chatGPT ? {} : { max_output_tokens: 2_048 }),
+		};
 		const diagnosticSecrets = [
 			execution.auth.apiKey,
 			...Object.entries(execution.model.headers ?? {}).filter(([key]) => /authorization|api[-_]?key|token|secret|cookie/i.test(key)).map(([, value]) => value),
@@ -798,8 +788,9 @@ export class OpenAIProvider implements Provider {
 
 		let response: Response;
 		try {
-			response = await this.fetchImpl(endpointFor(execution.model, this.endpoint), {
+			response = await this.fetchImpl(endpoint, {
 				method: "POST",
+				redirect: "error",
 				headers,
 				body: JSON.stringify(body),
 				signal,
@@ -817,7 +808,7 @@ export class OpenAIProvider implements Provider {
 		const responseRateLimits = parseProviderRateLimits(response.headers);
 		if (response.status === 401 || response.status === 403) {
 			const diagnostic = await readErrorDiagnostic(response, diagnosticSecrets, signal);
-			throw createProviderError({ provider: this.id, kind: "auth", message: `OpenAI web search authentication failed (HTTP ${response.status})${diagnostic === undefined ? "" : `: ${diagnostic}`}`, status: response.status, requestId, retryAfterMs, rateLimits: responseRateLimits, retryable: false });
+			throw createProviderError({ provider: this.id, kind: "auth", fallbackSafe: true, message: `OpenAI web search authentication failed (HTTP ${response.status})${diagnostic === undefined ? "" : `: ${diagnostic}`}`, status: response.status, requestId, retryAfterMs, rateLimits: responseRateLimits, retryable: false });
 		}
 		if (response.status === 429) {
 			const diagnostic = await readErrorDiagnostic(response, diagnosticSecrets, signal);
@@ -830,7 +821,7 @@ export class OpenAIProvider implements Provider {
 
 		try {
 			const responseBody = await readBody(response, signal, this.maxResponseBytes, this.id);
-			const payload = parseResponseBody(responseBody, this.id);
+			const payload = parseResponseBody(responseBody, this.id, diagnosticSecrets);
 			responseStatusFailure(this.id, payload);
 			const normalizedResponse = normalizeOpenAIResponse(payload, normalized, this.id);
 			const usage = normalizedResponse.usage === undefined && responseRateLimits === undefined

package/src/parallel-responses.ts

@@ -165,6 +165,7 @@ function usageFromPayload(root: Record<string, unknown>): ProviderUsage | undefi
 export function normalizeParallelResponsesPayload(payload: unknown, request: SearchRequest): SearchResponse {
 	const normalized = validateSearchRequest(request);
 	const root = objectValue(payload, "response", "parallel-responses");
+	if (root.status !== "completed" || root.error != null) malformed("response did not complete successfully");
 	const { text, citations: rawCitations } = answerFromPayload(root);
 	if (text.trim().length === 0) malformed("answer text is empty");
 	const limitedText = text.slice(0, MAX_ANSWER_LENGTH);

package/src/parallel.ts

@@ -52,6 +52,9 @@ export function buildParallelRequest(request: SearchRequest): ParallelRequestPla
 	if (normalized.dateRange?.to !== undefined) {
 		throw createProviderError({ provider: "parallel", kind: "unsupported", message: "Parallel Search supports a date-range start but not an upper date bound", retryable: false });
 	}
+	if (normalized.dateRange?.from?.includes("T")) {
+		throw createProviderError({ provider: "parallel", kind: "unsupported", message: "Parallel Search supports a date-only start, not an exact timestamp", retryable: false });
+	}
 	if (normalized.domains?.include?.length && normalized.domains?.exclude?.length) {
 		throw createProviderError({ provider: "parallel", kind: "unsupported", message: "Parallel Search accepts either included or excluded domains, not both", retryable: false });
 	}
@@ -63,7 +66,7 @@ export function buildParallelRequest(request: SearchRequest): ParallelRequestPla
 	const sourcePolicy = {
 		...(normalized.domains?.include === undefined ? {} : { include_domains: [...normalized.domains.include] }),
 		...(normalized.domains?.exclude === undefined ? {} : { exclude_domains: [...normalized.domains.exclude] }),
-		...(normalized.dateRange?.from === undefined ? {} : { after_date: normalized.dateRange.from.slice(0, 10) }),
+		...(normalized.dateRange?.from === undefined ? {} : { after_date: normalized.dateRange.from }),
 	};
 	const appliedOptions: SearchOption[] = ["maxResults", "mode"];
 	if (normalized.domains !== undefined && (normalized.domains.include !== undefined || normalized.domains.exclude !== undefined)) appliedOptions.push("domains");