@nijaru/pi-search 0.0.1

package/src/direct-transport.ts

@@ -0,0 +1,141 @@
+import http, { STATUS_CODES, type IncomingHttpHeaders, type IncomingMessage, type RequestOptions } from "node:http";
+import https from "node:https";
+import net from "node:net";
+import { SafeFetchError } from "./fetch-errors";
+import type { DirectTransportInit, ResponseBody, TransportResponse, ValidatedRemoteUrl } from "./ssrf";
+
+/**
+ * A transport is deliberately narrower than fetch(): the caller has already
+ * resolved and validated the URL, and this implementation must connect to the
+ * selected address while retaining the URL hostname for Host/SNI validation.
+ */
+export type DirectTransport = (
+	target: ValidatedRemoteUrl,
+	init: DirectTransportInit,
+) => Promise<TransportResponse>;
+
+export const directTransport: DirectTransport = (target, init) => requestDirect(target, init);
+
+function requestDirect(target: ValidatedRemoteUrl, init: DirectTransportInit): Promise<TransportResponse> {
+	if (init.signal.aborted) {
+		return Promise.reject(new SafeFetchError({ kind: "canceled", message: "Fetch canceled" }));
+	}
+
+	const isHttps = target.url.protocol === "https:";
+	const hostname = target.url.hostname.replace(/^\[|\]$/g, "");
+	const port = target.url.port === "" ? (isHttps ? 443 : 80) : Number(target.url.port);
+	const path = `${target.url.pathname || "/"}${target.url.search}`;
+	const requestOptions: RequestOptions = {
+		protocol: target.url.protocol,
+		hostname,
+		port,
+		method: "GET",
+		path,
+		headers: {
+			accept: "text/markdown, text/html;q=0.9, text/plain;q=0.8, application/json;q=0.7, application/xml;q=0.6, */*;q=0.1",
+			"user-agent": "pi-search (+https://github.com/nijaru/pi-search)",
+			...init.headers,
+		},
+		lookup: (_lookupHostname, lookupOptions, callback) => {
+			if (lookupOptions.all) {
+				callback(null, [{ address: target.address, family: target.family }]);
+			} else {
+				callback(null, target.address, target.family);
+			}
+		},
+		...(isHttps && net.isIP(hostname) === 0 ? { servername: hostname } : {}),
+	};
+
+	return new Promise<TransportResponse>((resolve, reject) => {
+		let settled = false;
+		let response: IncomingMessage | undefined;
+		let removeAbortListener: (() => void) | undefined;
+
+		const fail = (error: unknown): void => {
+			if (settled) return;
+			settled = true;
+			removeAbortListener?.();
+			if (error instanceof SafeFetchError) {
+				reject(error);
+				return;
+			}
+			reject(
+				new SafeFetchError({
+					kind: "network",
+					message: "Direct HTTP request failed",
+					retryable: true,
+					cause: error,
+				}),
+			);
+		};
+
+		const req = (isHttps ? https : http).request(requestOptions, (incoming) => {
+			response = incoming;
+			const body = makeResponseBody(incoming, req, init.signal, () => removeAbortListener?.());
+			settled = true;
+			removeAbortListener?.();
+			resolve({
+				status: incoming.statusCode ?? 0,
+				statusText: STATUS_CODES[incoming.statusCode ?? 0] ?? "",
+				headers: toHeaders(incoming.headers),
+				body,
+			});
+		});
+
+		const onAbort = (): void => {
+			if (response) {
+				response.destroy();
+			} else {
+				req.destroy();
+			}
+			fail(new SafeFetchError({ kind: "canceled", message: "Fetch canceled" }));
+		};
+		removeAbortListener = () => init.signal.removeEventListener("abort", onAbort);
+		init.signal.addEventListener("abort", onAbort, { once: true });
+		req.once("error", fail);
+		req.end();
+	});
+}
+
+function makeResponseBody(
+	incoming: IncomingMessage,
+	req: { destroy: () => void },
+	signal: AbortSignal,
+	onClose: () => void,
+): ResponseBody {
+	let closed = false;
+	const close = (): void => {
+		if (closed) return;
+		closed = true;
+		signal.removeEventListener("abort", onAbort);
+		onClose();
+		incoming.destroy();
+		req.destroy();
+	};
+	const onAbort = (): void => close();
+	signal.addEventListener("abort", onAbort, { once: true });
+	return {
+		async *[Symbol.asyncIterator](): AsyncIterator<Uint8Array> {
+			try {
+				for await (const chunk of incoming) {
+					yield chunk;
+				}
+			} finally {
+				signal.removeEventListener("abort", onAbort);
+			}
+		},
+		cancel: close,
+		destroy: close,
+	};
+}
+
+function toHeaders(raw: IncomingHttpHeaders): Headers {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(raw)) {
+		if (value === undefined) continue;
+		for (const entry of Array.isArray(value) ? value : [value]) {
+			headers.append(name, entry);
+		}
+	}
+	return headers;
+}

package/src/errors.ts

@@ -0,0 +1,185 @@
+import type { ProviderError, ProviderId, ProviderRateLimitInfo, RequestId } from "./contracts";
+
+export interface ProviderErrorOptions {
+	readonly provider: ProviderId;
+	readonly kind: ProviderError["kind"];
+	readonly message: string;
+	readonly retryable: boolean;
+	readonly status?: number;
+	readonly requestId?: RequestId;
+	readonly retryAfterMs?: number;
+	readonly rateLimits?: ProviderRateLimitInfo;
+	readonly cause?: unknown;
+}
+
+/** An adapter error with a stable, provider-neutral classification. */
+export class SearchProviderError extends Error implements ProviderError {
+	readonly provider: ProviderId;
+	readonly kind: ProviderError["kind"];
+	readonly retryable: boolean;
+	readonly status?: number;
+	readonly requestId?: RequestId;
+	readonly retryAfterMs?: number;
+	readonly rateLimits?: ProviderRateLimitInfo;
+
+	constructor(options: ProviderErrorOptions) {
+		super(options.message, { cause: options.cause });
+		this.name = "SearchProviderError";
+		this.provider = options.provider;
+		this.kind = options.kind;
+		this.retryable = options.retryable;
+		this.status = options.status;
+		this.requestId = options.requestId;
+		this.retryAfterMs = options.retryAfterMs;
+		this.rateLimits = options.rateLimits;
+	}
+}
+
+export function isProviderError(error: unknown): error is ProviderError {
+	return (
+		error instanceof SearchProviderError ||
+		(typeof error === "object" &&
+			error !== null &&
+			"provider" in error &&
+			"kind" in error &&
+			"retryable" in error &&
+			error instanceof Error)
+	);
+}
+
+export function createProviderError(options: ProviderErrorOptions): SearchProviderError {
+	return new SearchProviderError(options);
+}
+
+export type SearchToolErrorCode =
+	| "WEB_SEARCH_INVALID_REQUEST"
+	| "WEB_SEARCH_AUTH"
+	| "WEB_SEARCH_RATE_LIMIT"
+	| "WEB_SEARCH_BAD_REQUEST"
+	| "WEB_SEARCH_MALFORMED_RESPONSE"
+	| "WEB_SEARCH_TIMEOUT"
+	| "WEB_SEARCH_CANCELED"
+	| "WEB_SEARCH_NETWORK"
+	| "WEB_SEARCH_HTTP"
+	| "WEB_SEARCH_UNSUPPORTED"
+	| "WEB_SEARCH_PROVIDER_UNAVAILABLE"
+	| "WEB_SEARCH_UNKNOWN"
+	| "WEB_RESEARCH_INVALID_REQUEST"
+	| "WEB_RESEARCH_BUDGET"
+	| "WEB_RESEARCH_TIMEOUT"
+	| "WEB_RESEARCH_CANCELED"
+	| "WEB_RESEARCH_PROVIDER"
+	| "WEB_RESEARCH_UNKNOWN";
+
+/** A stable error shape thrown so Pi records an unsuccessful tool call. */
+export class SearchToolError extends Error {
+	readonly code: SearchToolErrorCode;
+	readonly provider?: ProviderId;
+	readonly kind?: ProviderError["kind"];
+	readonly retryable?: boolean;
+	readonly status?: number;
+	readonly requestId?: RequestId;
+	readonly retryAfterMs?: number;
+	readonly rateLimits?: ProviderRateLimitInfo;
+
+	constructor(
+		code: SearchToolErrorCode,
+		message: string,
+		options: {
+			readonly provider?: ProviderId;
+			readonly kind?: ProviderError["kind"];
+			readonly retryable?: boolean;
+			readonly status?: number;
+			readonly requestId?: RequestId;
+			readonly retryAfterMs?: number;
+			readonly rateLimits?: ProviderRateLimitInfo;
+		} = {},
+	) {
+		super(`${code}: ${message}`);
+		this.name = "SearchToolError";
+		this.code = code;
+		this.provider = options.provider;
+		this.kind = options.kind;
+		this.retryable = options.retryable;
+		this.status = options.status;
+		this.requestId = options.requestId;
+		this.retryAfterMs = options.retryAfterMs;
+		this.rateLimits = options.rateLimits;
+	}
+}
+
+function providerDiagnosticMessage(error: ProviderError): string {
+	const details = {
+		provider: error.provider,
+		...(error.status === undefined ? {} : { status: error.status }),
+		...(error.requestId === undefined ? {} : { requestId: error.requestId.slice(0, 200) }),
+		...(error.retryAfterMs === undefined ? {} : { retryAfterMs: Math.max(0, Math.round(error.retryAfterMs)) }),
+		...(error.rateLimits === undefined
+			? {}
+			: {
+				rateLimits: {
+					windows: error.rateLimits.windows.slice(0, 8),
+					...(error.rateLimits.retryAfterMs === undefined ? {} : { retryAfterMs: error.rateLimits.retryAfterMs }),
+				},
+			}),
+	};
+	return `${error.message} [${JSON.stringify(details)}]`;
+}
+
+const TOOL_ERROR_CODE_BY_KIND: Readonly<Record<ProviderError["kind"], SearchToolErrorCode>> = {
+	network: "WEB_SEARCH_NETWORK",
+	auth: "WEB_SEARCH_AUTH",
+	rateLimit: "WEB_SEARCH_RATE_LIMIT",
+	badRequest: "WEB_SEARCH_BAD_REQUEST",
+	malformed: "WEB_SEARCH_MALFORMED_RESPONSE",
+	timeout: "WEB_SEARCH_TIMEOUT",
+	canceled: "WEB_SEARCH_CANCELED",
+	unsupported: "WEB_SEARCH_UNSUPPORTED",
+	http: "WEB_SEARCH_HTTP",
+	unavailable: "WEB_SEARCH_PROVIDER_UNAVAILABLE",
+	unknown: "WEB_SEARCH_UNKNOWN",
+};
+
+/** Convert an adapter failure into the stable shape exposed by web_search. */
+export function toSearchToolError(error: unknown, provider: ProviderId): SearchToolError {
+	if (error instanceof SearchToolError) {
+		return error;
+	}
+	if (isProviderError(error)) {
+		return new SearchToolError(TOOL_ERROR_CODE_BY_KIND[error.kind], providerDiagnosticMessage(error), {
+			provider: error.provider,
+			kind: error.kind,
+			retryable: error.retryable,
+			status: error.status,
+			requestId: error.requestId,
+			retryAfterMs: error.retryAfterMs,
+			rateLimits: error.rateLimits,
+		});
+	}
+	const message = error instanceof Error ? error.message : "Unknown search failure";
+	return new SearchToolError("WEB_SEARCH_UNKNOWN", message, { provider, kind: "unknown" });
+}
+
+export interface SearchToolFailureDetails {
+	readonly code: SearchToolErrorCode;
+	readonly provider?: ProviderId;
+	readonly kind?: ProviderError["kind"];
+	readonly retryable?: boolean;
+	readonly status?: number;
+	readonly requestId?: RequestId;
+	readonly retryAfterMs?: number;
+	readonly rateLimits?: ProviderRateLimitInfo;
+}
+
+export function searchToolFailureDetails(error: SearchToolError): SearchToolFailureDetails {
+	return {
+		code: error.code,
+		...(error.provider === undefined ? {} : { provider: error.provider }),
+		...(error.kind === undefined ? {} : { kind: error.kind }),
+		...(error.retryable === undefined ? {} : { retryable: error.retryable }),
+		...(error.status === undefined ? {} : { status: error.status }),
+		...(error.requestId === undefined ? {} : { requestId: error.requestId }),
+		...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }),
+		...(error.rateLimits === undefined ? {} : { rateLimits: error.rateLimits }),
+	};
+}

package/src/exa.ts

@@ -0,0 +1,204 @@
+import type {
+	Provider,
+	ProviderCapabilities,
+	ProviderContext,
+	ProviderProfile,
+	ProviderRateLimitInfo,
+	SearchOption,
+	SearchRequest,
+	SearchResponse,
+	SearchResult,
+	SearchWarning,
+} from "./contracts";
+import { createProviderError } from "./errors";
+import { postJson, requireApiKey, httpSource, objectValue, optionalString, optionalTimestamp, type SearchHttpFetch } from "./provider-http";
+import { validateSearchRequest } from "./search";
+
+export const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
+export const DEFAULT_EXA_RESPONSE_BYTES = 4 * 1024 * 1024;
+/** Current published cost for one standard search returning up to 10 results. */
+export const EXA_ESTIMATED_SEARCH_COST_USD = 0.007;
+
+export interface ExaAdapterOptions {
+	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",
+	estimatedCostUsd: EXA_ESTIMATED_SEARCH_COST_USD,
+};
+
+function domainQuery(request: SearchRequest): Record<string, unknown> {
+	return {
+		...(request.domains?.include === undefined ? {} : { includeDomains: [...request.domains.include] }),
+		...(request.domains?.exclude === undefined ? {} : { excludeDomains: [...request.domains.exclude] }),
+	};
+}
+
+function exaDate(value: string, endOfDay: boolean): string {
+	if (value.includes("T")) return value;
+	return `${value}T${endOfDay ? "23:59:59.999" : "00:00:00.000"}Z`;
+}
+
+export interface ExaRequestPlan {
+	readonly body: Record<string, unknown>;
+	readonly appliedOptions: readonly SearchOption[];
+	readonly warnings: readonly SearchWarning[];
+}
+
+export function buildExaRequest(request: SearchRequest): ExaRequestPlan {
+	const normalized = validateSearchRequest(request);
+	if (normalized.social !== undefined) {
+		throw createProviderError({ provider: "exa", kind: "unsupported", message: "Exa search does not provide a dedicated social/X constraint contract", retryable: false });
+	}
+	const warnings: SearchWarning[] = [];
+	const appliedOptions: SearchOption[] = ["maxResults", "mode"];
+	if (normalized.mode === "keyword") {
+		warnings.push({ code: "unsupported-option", option: "mode", message: "Exa's current search API uses automatic retrieval; keyword-only ranking is not guaranteed" });
+	}
+	if (normalized.mode === "fresh") {
+		warnings.push({ code: "unsupported-option", option: "mode", message: "Exa search can return recent sources but this request does not impose a date cutoff" });
+	}
+	if (normalized.domains?.include !== undefined || normalized.domains?.exclude !== undefined) appliedOptions.push("domains");
+	if (normalized.dateRange !== undefined) appliedOptions.push("dateRange");
+	return {
+		body: {
+			query: normalized.query,
+			type: "auto",
+			numResults: normalized.maxResults,
+			contents: { highlights: true },
+			...(normalized.dateRange?.from === undefined ? {} : { startPublishedDate: exaDate(normalized.dateRange.from, false) }),
+			...(normalized.dateRange?.to === undefined ? {} : { endPublishedDate: exaDate(normalized.dateRange.to, true) }),
+			...domainQuery(normalized),
+		},
+		appliedOptions,
+		warnings,
+	};
+}
+
+function malformed(message: string): never {
+	throw createProviderError({ provider: "exa", kind: "malformed", message: `Exa 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 excerptFromRecord(record: Record<string, unknown>): string | undefined {
+	if (Array.isArray(record.highlights)) {
+		const highlights = record.highlights
+			.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+			.slice(0, 3);
+		if (highlights.length > 0) return highlights.join("\n").slice(0, 4_000);
+	}
+	for (const value of [record.text, record.summary]) {
+		const excerpt = optionalString(value, 4_000);
+		if (excerpt !== undefined) return excerpt;
+	}
+	return undefined;
+}
+
+function costFromResponse(value: unknown): number | undefined {
+	if (!isRecord(value)) return undefined;
+	const total = value.total;
+	return typeof total === "number" && Number.isFinite(total) && total >= 0 ? total : undefined;
+}
+
+function normalizeExaResponse(payload: unknown, request: SearchRequest, metadata: { readonly requestId?: string; readonly rateLimits?: ProviderRateLimitInfo }): SearchResponse {
+	const normalized = validateSearchRequest(request);
+	const root = objectValue(payload, "response", "exa");
+	if (!Array.isArray(root.results)) return malformed("results is not an array");
+	const results: SearchResult[] = [];
+	let discarded = 0;
+	for (const value of root.results) {
+		// A single malformed result should not hide otherwise usable evidence.
+		if (!isRecord(value)) {
+			discarded += 1;
+			continue;
+		}
+		const parsed = httpSource(value.url, "exa");
+		if (parsed === undefined) {
+			discarded += 1;
+			continue;
+		}
+		const score = typeof value.score === "number" && Number.isFinite(value.score) ? Math.max(0, Math.min(1, value.score)) : undefined;
+		results.push({
+			url: parsed.url,
+			title: optionalString(value.title, 500),
+			domain: parsed.domain,
+			publishedAt: optionalTimestamp(value.publishedDate),
+			excerpt: excerptFromRecord(value),
+			provider: "exa",
+			searchQuery: normalized.query,
+			sourceId: optionalString(value.id, 500),
+			score,
+		});
+	}
+	if (discarded > 0 && results.length === 0) return malformed("results contained no parseable HTTP URLs");
+	// Billing metadata is useful but non-essential. Ignore an invalid optional
+	// cost object rather than turning a successful search into a hard failure.
+	const costUsd = costFromResponse(root.costDollars);
+	const bodyRequestId = optionalString(root.requestId, 500);
+	const usage = costUsd === undefined && metadata.rateLimits === undefined
+		? undefined
+		: { ...(costUsd === undefined ? {} : { costUsd }), ...(metadata.rateLimits === undefined ? {} : { rateLimits: metadata.rateLimits }) };
+	return {
+		query: normalized.query,
+		results: results.slice(0, normalized.maxResults ?? 10),
+		provider: "exa",
+		appliedOptions: [],
+		warnings: discarded > 0 ? [{ code: "partial-results", message: `Exa discarded ${discarded} malformed result entr${discarded === 1 ? "y" : "ies"}` }] : [],
+		...(metadata.requestId === undefined && bodyRequestId === undefined ? {} : { requestId: metadata.requestId ?? bodyRequestId }),
+		...(usage === undefined ? {} : { usage }),
+	};
+}
+
+export class ExaProvider implements Provider {
+	readonly id = "exa" 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: ExaAdapterOptions) {
+		this.apiKey = options.apiKey;
+		this.endpoint = options.endpoint ?? EXA_SEARCH_ENDPOINT;
+		this.fetchImpl = options.fetchImpl ?? (fetch as SearchHttpFetch);
+		this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_EXA_RESPONSE_BYTES;
+	}
+
+	async search(request: SearchRequest, signal: AbortSignal, _context: ProviderContext): Promise<SearchResponse> {
+		const normalized = validateSearchRequest(request);
+		const plan = buildExaRequest(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 response = normalizeExaResponse(result.payload, normalized, result);
+		return { ...response, appliedOptions: plan.appliedOptions, warnings: [...plan.warnings, ...response.warnings] };
+	}
+}
+
+export function createExaProvider(options: ExaAdapterOptions): ExaProvider {
+	return new ExaProvider(options);
+}

package/src/fetch-errors.ts

@@ -0,0 +1,134 @@
+export type FetchErrorKind =
+	| "invalidRequest"
+	| "ssrf"
+	| "redirect"
+	| "network"
+	| "http"
+	| "timeout"
+	| "canceled"
+	| "responseTooLarge"
+	| "unsupportedContentType"
+	| "extraction"
+	| "unknown";
+
+export interface FetchErrorOptions {
+	readonly kind: FetchErrorKind;
+	readonly message: string;
+	readonly status?: number;
+	readonly retryable?: boolean;
+	readonly cause?: unknown;
+}
+
+export class SafeFetchError extends Error {
+	readonly kind: FetchErrorKind;
+	readonly status?: number;
+	readonly retryable: boolean;
+
+	constructor(options: FetchErrorOptions) {
+		super(options.message, { cause: options.cause });
+		this.name = "SafeFetchError";
+		this.kind = options.kind;
+		this.status = options.status;
+		this.retryable = options.retryable ?? false;
+	}
+}
+
+export type FetchToolErrorCode =
+	| "WEB_FETCH_INVALID_REQUEST"
+	| "WEB_FETCH_SSRF_BLOCKED"
+	| "WEB_FETCH_REDIRECT_ERROR"
+	| "WEB_FETCH_NETWORK"
+	| "WEB_FETCH_HTTP"
+	| "WEB_FETCH_TIMEOUT"
+	| "WEB_FETCH_CANCELED"
+	| "WEB_FETCH_RESPONSE_TOO_LARGE"
+	| "WEB_FETCH_UNSUPPORTED_CONTENT_TYPE"
+	| "WEB_FETCH_EXTRACTION_FAILED"
+	| "WEB_FETCH_UNKNOWN";
+
+export class FetchToolError extends Error {
+	readonly code: FetchToolErrorCode;
+	readonly kind: FetchErrorKind;
+	readonly status?: number;
+	readonly retryable: boolean;
+
+	constructor(options: {
+		readonly code: FetchToolErrorCode;
+		readonly kind: FetchErrorKind;
+		readonly message: string;
+		readonly status?: number;
+		readonly retryable?: boolean;
+	}) {
+		super(`${options.code}: ${options.message}`);
+		this.name = "FetchToolError";
+		this.code = options.code;
+		this.kind = options.kind;
+		this.status = options.status;
+		this.retryable = options.retryable ?? false;
+	}
+}
+
+export function isSafeFetchError(error: unknown): error is SafeFetchError {
+	return error instanceof SafeFetchError;
+}
+
+function errorCode(kind: FetchErrorKind): FetchToolErrorCode {
+	switch (kind) {
+		case "invalidRequest":
+			return "WEB_FETCH_INVALID_REQUEST";
+		case "ssrf":
+			return "WEB_FETCH_SSRF_BLOCKED";
+		case "redirect":
+			return "WEB_FETCH_REDIRECT_ERROR";
+		case "network":
+			return "WEB_FETCH_NETWORK";
+		case "http":
+			return "WEB_FETCH_HTTP";
+		case "timeout":
+			return "WEB_FETCH_TIMEOUT";
+		case "canceled":
+			return "WEB_FETCH_CANCELED";
+		case "responseTooLarge":
+			return "WEB_FETCH_RESPONSE_TOO_LARGE";
+		case "unsupportedContentType":
+			return "WEB_FETCH_UNSUPPORTED_CONTENT_TYPE";
+		case "extraction":
+			return "WEB_FETCH_EXTRACTION_FAILED";
+		case "unknown":
+			return "WEB_FETCH_UNKNOWN";
+	}
+}
+
+export function toFetchToolError(error: unknown): FetchToolError {
+	if (error instanceof FetchToolError) return error;
+	if (isSafeFetchError(error)) {
+		return new FetchToolError({
+			code: errorCode(error.kind),
+			kind: error.kind,
+			message: error.message,
+			status: error.status,
+			retryable: error.retryable,
+		});
+	}
+	return new FetchToolError({
+		code: "WEB_FETCH_UNKNOWN",
+		kind: "unknown",
+		message: error instanceof Error ? error.message : "Unknown fetch failure",
+	});
+}
+
+export interface FetchToolFailureDetails {
+	readonly code: FetchToolErrorCode;
+	readonly kind: FetchErrorKind;
+	readonly status?: number;
+	readonly retryable: boolean;
+}
+
+export function fetchToolFailureDetails(error: FetchToolError): FetchToolFailureDetails {
+	return {
+		code: error.code,
+		kind: error.kind,
+		...(error.status === undefined ? {} : { status: error.status }),
+		retryable: error.retryable,
+	};
+}