@nijaru/pi-search 0.0.1

package/src/parallel-responses.ts

@@ -0,0 +1,260 @@
+import type {
+	Provider,
+	ProviderCapabilities,
+	ProviderContext,
+	ProviderProfile,
+	ProviderUsage,
+	SearchOption,
+	SearchRequest,
+	SearchResponse,
+	SearchResult,
+	SearchWarning,
+} from "./contracts";
+import { createProviderError } from "./errors";
+import { httpSource, objectValue, optionalString, postJson, requireApiKey, type SearchHttpFetch } from "./provider-http";
+import { validateSearchRequest } from "./search";
+
+/**
+ * Parallel Responses API — opt-in answer-synthesis provider.
+ *
+ * POST https://api.parallel.ai/v1/responses with model "parallel"; the
+ * reasoning tier (low/medium/high, default medium) is selected through
+ * `reasoning.effort` and grounds the answer in live web research
+ * automatically. Citations arrive as `url_citation` annotations carrying
+ * start/end indexes over the answer text. Registered only when
+ * `PI_SEARCH_ENABLE_PARALLEL_RESPONSES=1`; explicit provider hint only —
+ * never automatic routing, never the `native` alias.
+ */
+
+export const PARALLEL_RESPONSES_ENDPOINT = "https://api.parallel.ai/v1/responses";
+export const DEFAULT_PARALLEL_RESPONSES_BYTES = 4 * 1024 * 1024;
+const MAX_ANSWER_LENGTH = 8_000;
+const MAX_SOURCE_URL_LENGTH = 8_192;
+const MAX_SOURCE_TITLE_LENGTH = 500;
+const EFFORTS = ["low", "medium", "high"] as const;
+export type ParallelResponsesEffort = (typeof EFFORTS)[number];
+
+export interface ParallelResponsesAdapterOptions {
+	readonly apiKey?: string;
+	readonly endpoint?: string;
+	readonly fetchImpl?: SearchHttpFetch;
+	readonly maxResponseBytes?: number;
+}
+
+const capabilities: ProviderCapabilities = {
+	semantic: true,
+	freshness: true,
+	excerpts: false,
+	nativeGrounding: true,
+	searchContextSize: true,
+};
+
+const profile: ProviderProfile = {
+	auth: "environment",
+	costModel: "usage-based",
+};
+
+export interface ParallelResponsesPlan {
+	readonly body: Record<string, unknown>;
+	readonly appliedOptions: readonly SearchOption[];
+	readonly warnings: readonly SearchWarning[];
+}
+
+/** Map the contract's provider-native context size onto the reasoning tier. */
+export function effortFor(request: SearchRequest): ParallelResponsesEffort {
+	return request.searchContextSize ?? "medium";
+}
+
+export function buildParallelResponsesRequest(request: SearchRequest): ParallelResponsesPlan {
+	const normalized = validateSearchRequest(request);
+	const hardConstraints: SearchOption[] = [];
+	if (normalized.domains?.include?.length || normalized.domains?.exclude?.length) hardConstraints.push("domains");
+	if (normalized.dateRange !== undefined) hardConstraints.push("dateRange");
+	if (normalized.social !== undefined) hardConstraints.push("social");
+	if (normalized.returnTokenBudget !== undefined) hardConstraints.push("returnTokenBudget");
+	if (normalized.externalWebAccess !== undefined) hardConstraints.push("externalWebAccess");
+	if (normalized.userLocation !== undefined) hardConstraints.push("userLocation");
+	if (normalized.searchContentTypes !== undefined) hardConstraints.push("searchContentTypes");
+	if (normalized.imageSettings !== undefined) hardConstraints.push("imageSettings");
+	if (hardConstraints.length > 0) {
+		throw createProviderError({
+			provider: "parallel-responses",
+			kind: "unsupported",
+			message: `Parallel Responses does not expose ${hardConstraints.join(", ")} controls`,
+			retryable: false,
+		});
+	}
+	const warnings: SearchWarning[] = [];
+	if (normalized.mode === "keyword") warnings.push({ code: "unsupported-option", option: "mode", message: "Parallel Responses researches the question semantically; keyword-only ranking is not guaranteed" });
+	if (normalized.mode === "fresh") warnings.push({ code: "unsupported-option", option: "mode", message: "Parallel Responses uses current sources but does not guarantee a freshness-only ranking" });
+	if (normalized.maxResults !== undefined) warnings.push({ code: "unsupported-option", option: "maxResults", message: "Parallel Responses returns the sources its research cited; the result count is not configurable" });
+	const appliedOptions: SearchOption[] = ["mode", ...(normalized.searchContextSize === undefined ? [] : ["searchContextSize" as const])];
+	return {
+		body: {
+			model: "parallel",
+			input: normalized.query,
+			reasoning: { effort: effortFor(normalized) },
+		},
+		appliedOptions,
+		warnings,
+	};
+}
+
+function malformed(message: string): never {
+	throw createProviderError({ provider: "parallel-responses", kind: "malformed", message: `Parallel Responses returned a malformed response (${message})`, retryable: false });
+}
+
+interface CitationCandidate {
+	readonly url: string;
+	readonly title?: string;
+	readonly startIndex?: number;
+	readonly endIndex?: number;
+}
+
+/** Collect message output text and its url_citation annotations. */
+function answerFromPayload(payload: unknown): { text: string; citations: CitationCandidate[] } {
+	const root = objectValue(payload, "response", "parallel-responses");
+	const output = Array.isArray(root.output) ? root.output : malformed("output is not an array");
+	let text: string | undefined;
+	const citations: CitationCandidate[] = [];
+	for (const item of output) {
+		if (typeof item !== "object" || item === null || Array.isArray(item)) continue;
+		const record = item as Record<string, unknown>;
+		if (record.type !== "message") continue;
+		const content = Array.isArray(record.content) ? record.content : [];
+		for (const part of content) {
+			if (typeof part !== "object" || part === null || Array.isArray(part)) continue;
+			const contentPart = part as Record<string, unknown>;
+			if (contentPart.type !== "output_text" || typeof contentPart.text !== "string") continue;
+			text = text === undefined ? contentPart.text : `${text}\n${contentPart.text}`;
+			for (const annotation of Array.isArray(contentPart.annotations) ? contentPart.annotations : []) {
+				if (typeof annotation !== "object" || annotation === null || Array.isArray(annotation)) continue;
+				const record2 = annotation as Record<string, unknown>;
+				if (record2.type !== "url_citation") continue;
+				const parsed = httpSource(record2.url, "parallel-responses");
+				if (parsed === undefined || parsed.url.length > MAX_SOURCE_URL_LENGTH) continue;
+				citations.push({
+					url: parsed.url,
+					...(optionalString(record2.title, MAX_SOURCE_TITLE_LENGTH) === undefined ? {} : { title: optionalString(record2.title, MAX_SOURCE_TITLE_LENGTH) }),
+					...(typeof record2.start_index === "number" && Number.isFinite(record2.start_index) && record2.start_index >= 0 ? { startIndex: Math.round(record2.start_index) } : {}),
+					...(typeof record2.end_index === "number" && Number.isFinite(record2.end_index) && record2.end_index >= 0 ? { endIndex: Math.round(record2.end_index) } : {}),
+				});
+			}
+		}
+	}
+	if (text === undefined) malformed("no message output text");
+	return { text, citations };
+}
+
+function usageFromPayload(root: Record<string, unknown>): ProviderUsage | undefined {
+	const value = root.usage;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const usage = value as Record<string, unknown>;
+	const number = (key: string): number | undefined => typeof usage[key] === "number" && Number.isFinite(usage[key] as number) && (usage[key] as number) >= 0 ? usage[key] as number : undefined;
+	const inputTokens = number("input_tokens");
+	const outputTokens = number("output_tokens");
+	const totalTokens = number("total_tokens");
+	if (inputTokens === undefined && outputTokens === undefined && totalTokens === undefined) return undefined;
+	return {
+		...(inputTokens === undefined ? {} : { inputTokens }),
+		...(outputTokens === undefined ? {} : { outputTokens }),
+		...(totalTokens === undefined ? {} : { totalTokens, billedUnits: totalTokens, billedUnit: "tokens" }),
+	};
+}
+
+export function normalizeParallelResponsesPayload(payload: unknown, request: SearchRequest): SearchResponse {
+	const normalized = validateSearchRequest(request);
+	const root = objectValue(payload, "response", "parallel-responses");
+	const { text, citations: rawCitations } = answerFromPayload(root);
+	if (text.trim().length === 0) malformed("answer text is empty");
+	const limitedText = text.slice(0, MAX_ANSWER_LENGTH);
+
+	// Deduplicate citations by URL, preserving first-seen order and indexes.
+	const byUrl = new Map<string, CitationCandidate>();
+	for (const citation of rawCitations) {
+		if (!byUrl.has(citation.url)) byUrl.set(citation.url, citation);
+	}
+	const results: SearchResult[] = [];
+	for (const citation of byUrl.values()) {
+		const parsed = httpSource(citation.url, "parallel-responses");
+		if (parsed === undefined) continue;
+		results.push({
+			url: parsed.url,
+			...(citation.title === undefined ? {} : { title: citation.title }),
+			domain: parsed.domain,
+			provider: "parallel-responses",
+			searchQuery: normalized.query,
+		});
+	}
+	if (results.length === 0) malformed("answer cites no HTTP sources");
+	const answer = {
+		text: limitedText,
+		contentTrust: "untrusted" as const,
+		provider: "parallel-responses" as const,
+		citations: [...byUrl.values()].slice(0, normalized.maxResults ?? 10).map((citation) => ({
+			url: citation.url,
+			...(citation.title === undefined ? {} : { title: citation.title }),
+			...(citation.startIndex === undefined ? {} : { startIndex: citation.startIndex }),
+			...(citation.endIndex === undefined ? {} : { endIndex: citation.endIndex }),
+		})),
+	};
+	return {
+		query: normalized.query,
+		results,
+		...(normalized.answerMode === "evidence" ? {} : { answer }),
+		provider: "parallel-responses",
+		appliedOptions: [],
+		warnings: [],
+		...(usageFromPayload(root) === undefined ? {} : { usage: usageFromPayload(root) }),
+	};
+}
+
+/** Response id from the payload, used when the transport supplied none. */
+export function parallelResponsesRequestId(payload: unknown): string | undefined {
+	const root = objectValue(payload, "response", "parallel-responses");
+	return optionalString(root.id, 500);
+}
+
+export class ParallelResponsesProvider implements Provider {
+	readonly id = "parallel-responses" as const;
+	readonly capabilities = capabilities;
+	readonly profile = profile;
+	private readonly apiKey?: string;
+	private readonly endpoint: string;
+	private readonly fetchImpl: SearchHttpFetch;
+	private readonly maxResponseBytes: number;
+
+	constructor(options: ParallelResponsesAdapterOptions = {}) {
+		this.apiKey = options.apiKey;
+		this.endpoint = options.endpoint ?? PARALLEL_RESPONSES_ENDPOINT;
+		this.fetchImpl = options.fetchImpl ?? (fetch as SearchHttpFetch);
+		this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_PARALLEL_RESPONSES_BYTES;
+		if (!Number.isInteger(this.maxResponseBytes) || this.maxResponseBytes < 1) throw new Error("Parallel Responses maxResponseBytes must be a positive integer");
+	}
+
+	async search(request: SearchRequest, signal: AbortSignal, _context: ProviderContext): Promise<SearchResponse> {
+		const normalized = validateSearchRequest(request);
+		const plan = buildParallelResponsesRequest(normalized);
+		const result = await postJson({
+			provider: this.id,
+			url: this.endpoint,
+			headers: { authorization: `Bearer ${requireApiKey(this.id, this.apiKey)}` },
+			body: plan.body,
+			signal,
+			fetchImpl: this.fetchImpl,
+			maxResponseBytes: this.maxResponseBytes,
+		});
+		const response = normalizeParallelResponsesPayload(result.payload, normalized);
+		const requestId = result.requestId ?? parallelResponsesRequestId(result.payload);
+		return {
+			...response,
+			...(requestId === undefined ? {} : { requestId }),
+			appliedOptions: plan.appliedOptions,
+			warnings: [...plan.warnings, ...response.warnings],
+		};
+	}
+}
+
+export function createParallelResponsesProvider(options: ParallelResponsesAdapterOptions): ParallelResponsesProvider {
+	return new ParallelResponsesProvider(options);
+}

package/src/parallel.ts

@@ -0,0 +1,173 @@
+import type {
+	Provider,
+	ProviderCapabilities,
+	ProviderContext,
+	ProviderProfile,
+	ProviderRateLimitInfo,
+	SearchOption,
+	SearchRequest,
+	SearchResponse,
+	SearchResult,
+	SearchWarning,
+} from "./contracts";
+import { createProviderError } from "./errors";
+import { httpSource, optionalString, optionalTimestamp, objectValue, postJson, requireApiKey, type SearchHttpFetch } from "./provider-http";
+import { validateSearchRequest } from "./search";
+
+export const PARALLEL_SEARCH_ENDPOINT = "https://api.parallel.ai/v1/search";
+export const DEFAULT_PARALLEL_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+export interface ParallelAdapterOptions {
+	readonly apiKey?: string;
+	readonly endpoint?: string;
+	readonly fetchImpl?: SearchHttpFetch;
+	readonly maxResponseBytes?: number;
+}
+
+const capabilities: ProviderCapabilities = {
+	keyword: true,
+	freshness: true,
+	semantic: true,
+	excerpts: true,
+	domainFilter: true,
+	dateFilter: true,
+};
+
+const profile: ProviderProfile = {
+	auth: "environment",
+	costModel: "usage-based",
+};
+
+export interface ParallelRequestPlan {
+	readonly body: Record<string, unknown>;
+	readonly appliedOptions: readonly SearchOption[];
+	readonly warnings: readonly SearchWarning[];
+}
+
+export function buildParallelRequest(request: SearchRequest): ParallelRequestPlan {
+	const normalized = validateSearchRequest(request);
+	if (normalized.social !== undefined) {
+		throw createProviderError({ provider: "parallel", kind: "unsupported", message: "Parallel Search does not expose dedicated social/X constraints", retryable: false });
+	}
+	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.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 });
+	}
+	const warnings: SearchWarning[] = [];
+	if (normalized.mode === "fresh") {
+		warnings.push({ code: "unsupported-option", option: "mode", message: "Parallel Search can prioritize current sources but this request does not impose a date cutoff" });
+	}
+	const maxResults = normalized.maxResults ?? 10;
+	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) }),
+	};
+	const appliedOptions: SearchOption[] = ["maxResults", "mode"];
+	if (normalized.domains !== undefined && (normalized.domains.include !== undefined || normalized.domains.exclude !== undefined)) appliedOptions.push("domains");
+	if (normalized.dateRange !== undefined && normalized.dateRange.from !== undefined) appliedOptions.push("dateRange");
+	// Mode mapping per docs.parallel.ai/search/modes (checked 2026-09-06):
+	// fast is the recommended high-quality default for agents ($1/1K, ~700ms);
+	// basic returns extended snippets for keyword/reference probes ($5/1K);
+	// advanced is the multi-hop depth pipeline for recency-sensitive work
+	// ($5/1K, ~3s). turbo is a latency tier with no quality advantage and
+	// partial language coverage, so it is deliberately not used.
+	const mode = normalized.mode === "keyword" ? "basic" : normalized.mode === "fresh" ? "advanced" : "fast";
+	return {
+		body: {
+			objective: normalized.query,
+			search_queries: [normalized.query],
+			mode,
+			advanced_settings: {
+				max_results: maxResults,
+				...(Object.keys(sourcePolicy).length === 0 ? {} : { source_policy: sourcePolicy }),
+			},
+			max_chars_total: Math.min(24_000, Math.max(2_000, maxResults * 2_000)),
+		},
+		appliedOptions,
+		warnings,
+	};
+}
+
+function malformed(message: string): never {
+	throw createProviderError({ provider: "parallel", kind: "malformed", message: `Parallel returned a malformed response (${message})`, retryable: false });
+}
+
+function normalizeParallelResponse(payload: unknown, request: SearchRequest, metadata: { readonly requestId?: string; readonly rateLimits?: ProviderRateLimitInfo } = {}): SearchResponse {
+	const normalized = validateSearchRequest(request);
+	const root = objectValue(payload, "response", "parallel");
+	if (!Array.isArray(root.results)) return malformed("results is not an array");
+	const results: SearchResult[] = [];
+	let discarded = 0;
+	for (const value of root.results) {
+		const record = objectValue(value, "results[]", "parallel");
+		const parsed = httpSource(record.url, "parallel");
+		if (parsed === undefined) {
+			discarded += 1;
+			continue;
+		}
+		const excerpts = Array.isArray(record.excerpts)
+			? record.excerpts.filter((item): item is string => typeof item === "string").slice(0, 3).join("\n")
+			: undefined;
+		results.push({
+			url: parsed.url,
+			title: optionalString(record.title, 500),
+			domain: parsed.domain,
+			publishedAt: optionalTimestamp(record.publish_date),
+			...(excerpts === undefined ? {} : { excerpt: excerpts.slice(0, 4_000) }),
+			provider: "parallel",
+			searchQuery: normalized.query,
+		});
+	}
+	if (discarded > 0 && results.length === 0) return malformed("results contained no parseable HTTP URLs");
+	return {
+		query: normalized.query,
+		results: results.slice(0, normalized.maxResults ?? 10),
+		provider: "parallel",
+		appliedOptions: [],
+		warnings: discarded > 0 ? [{ code: "partial-results", message: `Parallel discarded ${discarded} malformed result entr${discarded === 1 ? "y" : "ies"}` }] : [],
+		...(metadata.requestId === undefined ? {} : { requestId: metadata.requestId }),
+		...(metadata.rateLimits === undefined ? {} : { usage: { rateLimits: metadata.rateLimits } }),
+	};
+}
+
+export class ParallelProvider implements Provider {
+	readonly id = "parallel" as const;
+	readonly capabilities = capabilities;
+	readonly profile = profile;
+	private readonly apiKey?: string;
+	private readonly endpoint: string;
+	private readonly fetchImpl: SearchHttpFetch;
+	private readonly maxResponseBytes: number;
+
+	constructor(options: ParallelAdapterOptions) {
+		this.apiKey = options.apiKey;
+		this.endpoint = options.endpoint ?? PARALLEL_SEARCH_ENDPOINT;
+		this.fetchImpl = options.fetchImpl ?? (fetch as SearchHttpFetch);
+		this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_PARALLEL_RESPONSE_BYTES;
+	}
+
+	async search(request: SearchRequest, signal: AbortSignal, _context: ProviderContext): Promise<SearchResponse> {
+		const normalized = validateSearchRequest(request);
+		const plan = buildParallelRequest(normalized);
+		const result = await postJson({
+			provider: this.id,
+			url: this.endpoint,
+			headers: { "x-api-key": requireApiKey(this.id, this.apiKey) },
+			body: plan.body,
+			signal,
+			fetchImpl: this.fetchImpl,
+			maxResponseBytes: this.maxResponseBytes,
+		});
+		const payload = result.payload !== null && typeof result.payload === "object" && !Array.isArray(result.payload) ? result.payload as Record<string, unknown> : undefined;
+		const searchId = typeof payload?.search_id === "string" ? payload.search_id : undefined;
+		const response = normalizeParallelResponse(result.payload, normalized, { requestId: result.requestId ?? searchId, ...(result.rateLimits === undefined ? {} : { rateLimits: result.rateLimits }) });
+		return { ...response, appliedOptions: plan.appliedOptions, warnings: [...plan.warnings, ...response.warnings] };
+	}
+}
+
+export function createParallelProvider(options: ParallelAdapterOptions): ParallelProvider {
+	return new ParallelProvider(options);
+}

package/src/pdf.ts

@@ -0,0 +1,153 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SafeFetchError } from "./fetch-errors";
+
+// AnyDoc owns the default PDF path. This bounded Poppler path remains for
+// explicit maxPages requests because AnyDoc has no page-range option.
+export const DEFAULT_PDF_MAX_PAGES = 100;
+export const MAX_PDF_PAGES = 500;
+export const DEFAULT_PDF_TEXT_BYTES = 2 * 1024 * 1024;
+
+export interface PdfExtractorOptions {
+	readonly command?: string;
+	readonly maxPages?: number;
+	readonly maxOutputBytes?: number;
+	readonly signal: AbortSignal;
+	readonly spawnImpl?: (command: string, args: readonly string[], options: Record<string, unknown>) => any;
+}
+
+export interface PdfTextResult {
+	readonly text: string;
+	readonly bytesRead: number;
+}
+
+function canceled(): SafeFetchError {
+	return new SafeFetchError({ kind: "canceled", message: "PDF extraction canceled" });
+}
+
+function extraction(message: string, cause?: unknown): SafeFetchError {
+	return new SafeFetchError({ kind: "extraction", message, cause });
+}
+
+function appendBytes(chunks: Uint8Array[], chunk: unknown, current: number, max: number): number {
+	const bytes = chunk instanceof Uint8Array ? chunk : new TextEncoder().encode(String(chunk));
+	const next = current + bytes.byteLength;
+	if (next > max) throw new SafeFetchError({ kind: "responseTooLarge", message: "PDF text exceeds the configured extraction limit" });
+	chunks.push(bytes);
+	return next;
+}
+
+async function runPdfToText(
+	command: string,
+	inputPath: string,
+	maxPages: number,
+	maxOutputBytes: number,
+	signal: AbortSignal,
+	spawnImpl: NonNullable<PdfExtractorOptions["spawnImpl"]>,
+): Promise<Uint8Array> {
+	if (signal.aborted) return Promise.reject(canceled());
+	return new Promise<Uint8Array>((resolve, reject) => {
+		let child: any;
+		let settled = false;
+		let terminationError: SafeFetchError | undefined;
+		let fallbackTimer: ReturnType<typeof setTimeout> | undefined;
+		let stdoutBytes = 0;
+		const stdout: Uint8Array[] = [];
+		const stderr: Uint8Array[] = [];
+		const finish = (error?: unknown): void => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			if (fallbackTimer !== undefined) clearTimeout(fallbackTimer);
+			if (error !== undefined) reject(error);
+			else {
+				const result = new Uint8Array(stdoutBytes);
+				let offset = 0;
+				for (const chunk of stdout) {
+					result.set(chunk, offset);
+					offset += chunk.byteLength;
+				}
+				resolve(result);
+			}
+		};
+		const kill = (): void => {
+			try {
+				if (child?.pid && process.platform !== "win32") {
+					try { process.kill(-child.pid, "SIGKILL"); } catch { /* group may already be gone */ }
+				}
+				child?.kill?.("SIGKILL");
+			} catch {
+				// Cleanup is best effort; the process result remains failed.
+			}
+		};
+		const terminate = (error: SafeFetchError): void => {
+			if (settled || terminationError !== undefined) return;
+			terminationError = error;
+			kill();
+			fallbackTimer = setTimeout(() => finish(error), 1_000);
+		};
+		const onAbort = (): void => terminate(canceled());
+		try {
+			child = spawnImpl(command, ["-q", "-enc", "UTF-8", "-f", "1", "-l", String(maxPages), inputPath, "-"], {
+				stdio: ["ignore", "pipe", "pipe"],
+				detached: process.platform !== "win32",
+			});
+			signal.addEventListener("abort", onAbort, { once: true });
+			child.stdout?.on("data", (chunk: unknown) => {
+				if (settled) return;
+				try {
+					stdoutBytes = appendBytes(stdout, chunk, stdoutBytes, maxOutputBytes);
+				} catch (error) {
+					terminate(error instanceof SafeFetchError ? error : extraction("PDF output exceeded the extraction limit", error));
+				}
+			});
+			child.stderr?.on("data", (chunk: unknown) => {
+				if (stderr.reduce((sum, item) => sum + item.byteLength, 0) < 16_384) {
+					try { appendBytes(stderr, chunk, stderr.reduce((sum, item) => sum + item.byteLength, 0), 16_384); } catch { /* diagnostics are bounded */ }
+				}
+			});
+			child.once("error", (error: unknown) => finish(terminationError ?? extraction(`PDF extraction command failed: ${error instanceof Error ? error.message : String(error)}`, error)));
+			if (signal.aborted) onAbort();
+			child.once("close", (code: number | null) => {
+				if (settled) return;
+				if (terminationError !== undefined) return finish(terminationError);
+				if (signal.aborted) return finish(canceled());
+				if (code !== 0) {
+					const diagnostic = new TextDecoder().decode(Uint8Array.from(stderr.flatMap((chunk) => [...chunk]))).trim().slice(0, 500);
+					return finish(extraction(diagnostic.length > 0 ? `PDF parser exited with ${code}: ${diagnostic}` : `PDF parser exited with ${code}`));
+				}
+				finish();
+			});
+		} catch (error) {
+			finish(extraction(`PDF extraction command could not start: ${error instanceof Error ? error.message : String(error)}`, error));
+		}
+	});
+}
+
+export async function extractPdfText(bytes: Uint8Array, options: PdfExtractorOptions): Promise<PdfTextResult> {
+	if (options.signal.aborted) throw canceled();
+	if (bytes.byteLength < 5 || new TextDecoder().decode(bytes.slice(0, 5)) !== "%PDF-") {
+		throw extraction("Response was identified as PDF but did not contain a valid PDF header");
+	}
+	const maxPages = options.maxPages ?? DEFAULT_PDF_MAX_PAGES;
+	if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > MAX_PDF_PAGES) {
+		throw new SafeFetchError({ kind: "invalidRequest", message: `maxPages must be between 1 and ${MAX_PDF_PAGES}` });
+	}
+	const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_PDF_TEXT_BYTES;
+	if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > DEFAULT_PDF_TEXT_BYTES) {
+		throw new SafeFetchError({ kind: "invalidRequest", message: "max PDF text bytes are outside the supported bound" });
+	}
+	const directory = await mkdtemp(join(tmpdir(), "pi-search-pdf-"));
+	const inputPath = join(directory, "document.pdf");
+	try {
+		await writeFile(inputPath, bytes);
+		const output = await runPdfToText(options.command ?? "pdftotext", inputPath, maxPages, maxOutputBytes, options.signal, options.spawnImpl ?? (spawn as unknown as NonNullable<PdfExtractorOptions["spawnImpl"]>));
+		const text = new TextDecoder("utf-8", { fatal: false }).decode(output).trim();
+		if (text.length === 0) throw extraction("PDF contains no extractable text; scanned PDFs require OCR, which is not enabled");
+		return { text, bytesRead: output.byteLength };
+	} finally {
+		await rm(directory, { recursive: true, force: true }).catch(() => undefined);
+	}
+}

package/src/provider-availability.ts

@@ -0,0 +1,35 @@
+import { SEARCH_PROVIDER_HINT_IDS, type SearchProviderHintId } from "./contracts";
+
+/**
+ * Provider hints that can actually be dispatched by the current installation.
+ *
+ * The tool schemas expose only these ids (plus `native`, which any supported
+ * grounded active model can serve), so a calling model never sees options
+ * whose keys or enable gates are absent. Native grounding adapters are
+ * always listed: any of them can serve through an active or registry model
+ * without extra configuration.
+ */
+export interface ProviderHintAvailability {
+	readonly brave?: boolean;
+	readonly braveAnswers?: boolean;
+	readonly exa?: boolean;
+	readonly parallel?: boolean;
+	readonly parallelResponses?: boolean;
+	readonly x?: boolean;
+}
+
+/** Native grounding adapters always stay exposed: any can serve through an
+ * active or registry model without extra configuration. */
+const NATIVE_HINT_IDS = ["openai", "openai-codex", "gemini", "xai", "xai-x", "anthropic", "meta"] as const satisfies readonly SearchProviderHintId[];
+
+/** Compute the dispatchable explicit-hint ids for this installation. */
+export function availableProviderHints(availability: ProviderHintAvailability): readonly SearchProviderHintId[] {
+	return SEARCH_PROVIDER_HINT_IDS.filter((id) =>
+		NATIVE_HINT_IDS.includes(id as (typeof NATIVE_HINT_IDS)[number])
+		|| (id === "brave" && availability.brave === true)
+		|| (id === "brave-answers" && availability.braveAnswers === true)
+		|| (id === "exa" && availability.exa === true)
+		|| (id === "parallel" && availability.parallel === true)
+		|| (id === "parallel-responses" && availability.parallelResponses === true)
+		|| (id === "x" && availability.x === true));
+}