@oh-my-pi/pi-coding-agent 3.20.0 → 3.21.0

package/src/core/tools/review.ts

@@ -72,7 +72,9 @@ export const reportFindingTool: AgentTool<typeof ReportFindingParams, ReportFind
 			content: [
 				{
 					type: "text",
-					text: `Finding recorded: ${PRIORITY_LABELS[priority]} ${title}\nLocation: ${location}\nConfidence: ${(confidence * 100).toFixed(0)}%`,
+					text: `Finding recorded: ${PRIORITY_LABELS[priority]} ${title}\nLocation: ${location}\nConfidence: ${(
+						confidence * 100
+					).toFixed(0)}%`,
 				},
 			],
 			details: { title, body, priority, confidence, file_path, line_start, line_end },
@@ -84,7 +86,10 @@ export const reportFindingTool: AgentTool<typeof ReportFindingParams, ReportFind
 		const color = args.priority === 0 ? "error" : args.priority === 1 ? "warning" : "muted";
 		const titleText = String(args.title).replace(/^\[P\d\]\s*/, "");
 		return new Text(
-			`${theme.fg("toolTitle", theme.bold("report_finding "))}${theme.fg(color, `[${priority}]`)} ${theme.fg("dim", titleText)}`,
+			`${theme.fg("toolTitle", theme.bold("report_finding "))}${theme.fg(color, `[${priority}]`)} ${theme.fg(
+				"dim",
+				titleText,
+			)}`,
 			0,
 			0,
 		);
@@ -99,7 +104,9 @@ export const reportFindingTool: AgentTool<typeof ReportFindingParams, ReportFind
 
 		const priority = PRIORITY_LABELS[details.priority] ?? "P?";
 		const color = details.priority === 0 ? "error" : details.priority === 1 ? "warning" : "muted";
-		const location = `${details.file_path}:${details.line_start}${details.line_end !== details.line_start ? `-${details.line_end}` : ""}`;
+		const location = `${details.file_path}:${details.line_start}${
+			details.line_end !== details.line_start ? `-${details.line_end}` : ""
+		}`;
 
 		return new Text(
 			`${theme.fg("success", theme.status.success)} ${theme.fg(color, `[${priority}]`)} ${theme.fg("dim", location)}`,
@@ -141,7 +148,11 @@ export const submitReviewTool: AgentTool<typeof SubmitReviewParams, SubmitReview
 		const { overall_correctness, explanation, confidence } = params;
 
 		let summary = `## Review Summary\n\n`;
-		summary += `**Verdict:** ${overall_correctness === "correct" ? `${theme.status.success} Patch is correct` : `${theme.status.error} Patch is incorrect`}\n`;
+		summary += `**Verdict:** ${
+			overall_correctness === "correct"
+				? `${theme.status.success} Patch is correct`
+				: `${theme.status.error} Patch is incorrect`
+		}\n`;
 		summary += `**Confidence:** ${(confidence * 100).toFixed(0)}%\n\n`;
 		summary += explanation;
 
@@ -155,7 +166,10 @@ export const submitReviewTool: AgentTool<typeof SubmitReviewParams, SubmitReview
 		const verdict = args.overall_correctness === "correct" ? "correct" : "incorrect";
 		const color = args.overall_correctness === "correct" ? "success" : "error";
 		return new Text(
-			`${theme.fg("toolTitle", theme.bold("submit_review "))}${theme.fg(color, verdict)} ${theme.fg("dim", `(${((args.confidence as number) * 100).toFixed(0)}%)`)}`,
+			`${theme.fg("toolTitle", theme.bold("submit_review "))}${theme.fg(color, verdict)} ${theme.fg(
+				"dim",
+				`(${((args.confidence as number) * 100).toFixed(0)}%)`,
+			)}`,
 			0,
 			0,
 		);
@@ -174,7 +188,10 @@ export const submitReviewTool: AgentTool<typeof SubmitReviewParams, SubmitReview
 
 		container.addChild(
 			new Text(
-				`${theme.fg(verdictColor, verdictIcon)} Patch is ${theme.fg(verdictColor, details.overall_correctness)} ${theme.fg("dim", `(${(details.confidence * 100).toFixed(0)}% confidence)`)}`,
+				`${theme.fg(verdictColor, verdictIcon)} Patch is ${theme.fg(
+					verdictColor,
+					details.overall_correctness,
+				)} ${theme.fg("dim", `(${(details.confidence * 100).toFixed(0)}% confidence)`)}`,
 				0,
 				0,
 			),
@@ -264,7 +281,9 @@ subprocessToolRegistry.register<SubmitReviewDetails>("submit_review", {
 		const verdictColor = data.overall_correctness === "correct" ? "success" : "error";
 		const verdictIcon = data.overall_correctness === "correct" ? theme.status.success : theme.status.error;
 		return new Text(
-			`${theme.fg(verdictColor, verdictIcon)} Review: ${theme.fg(verdictColor, data.overall_correctness)} (${(data.confidence * 100).toFixed(0)}%)`,
+			`${theme.fg(verdictColor, verdictIcon)} Review: ${theme.fg(verdictColor, data.overall_correctness)} (${(
+				data.confidence * 100
+			).toFixed(0)}%)`,
 			0,
 			0,
 		);

package/src/core/tools/rulebook.ts

@@ -37,7 +37,9 @@ export function createRulebookTool(rules: Rule[]): AgentTool<typeof rulebookSche
 	return {
 		name: "rulebook",
 		label: "Rulebook",
-		description: `Fetch the full content of a project rule by name. Use this when a rule listed in <available_rules> is relevant to your current task. Available: ${ruleNames.join(", ") || "(none)"}`,
+		description: `Fetch the full content of a project rule by name. Use this when a rule listed in <available_rules> is relevant to your current task. Available: ${
+			ruleNames.join(", ") || "(none)"
+		}`,
 		parameters: rulebookSchema,
 		execute: async (_toolCallId: string, { name }: { name: string }) => {
 			const rule = ruleMap.get(name);

package/src/core/tools/task/index.ts

@@ -13,8 +13,8 @@
  *   - Session artifacts for debugging
  */
 
+import type { Usage } from "@mariozechner/pi-ai";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import type { Usage } from "@oh-my-pi/pi-ai";
 import type { Theme } from "../../../modes/interactive/theme/theme";
 import { formatDuration } from "../render-utils";
 import { cleanupTempDir, createTempArtifactsDir, getArtifactsDir } from "./artifacts";
@@ -175,6 +175,12 @@ async function buildDescription(cwd: string): Promise<string> {
 	lines.push("");
 	lines.push("Usage notes:");
 	lines.push("- Always include a short description of the task in the task parameter");
+	lines.push(
+		"- Prefer plan-then-execute: put shared constraints in context, keep each task focused, and specify output format and acceptance criteria",
+	);
+	lines.push(
+		"- Minimize tool chatter: avoid repeating large context and use the Output tool with output ids for full logs",
+	);
 	lines.push("- Launch multiple agents concurrently whenever possible, to maximize performance");
 	lines.push(
 		"- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.",
@@ -510,9 +516,18 @@ export async function createTaskTool(
 
 				const skippedNote =
 					skippedSelfRecursion > 0
-						? ` (${skippedSelfRecursion} ${blockedAgent} task${skippedSelfRecursion > 1 ? "s" : ""} skipped - self-recursion blocked)`
+						? ` (${skippedSelfRecursion} ${blockedAgent} task${
+								skippedSelfRecursion > 1 ? "s" : ""
+							} skipped - self-recursion blocked)`
+						: "";
+				const outputIds = resultsWithUsage.map((r) => `${r.agent}_${r.index}`);
+				const outputHint =
+					hasOutputTool && outputIds.length > 0
+						? `\n\nUse output tool for full logs: output ids ${outputIds.join(", ")}`
 						: "";
-				const summary = `${successCount}/${resultsWithUsage.length} succeeded${skippedNote} [${formatDuration(totalDuration)}]\n\n${summaries.join("\n\n---\n\n")}`;
+				const summary = `${successCount}/${resultsWithUsage.length} succeeded${skippedNote} [${formatDuration(
+					totalDuration,
+				)}]\n\n${summaries.join("\n\n---\n\n")}${outputHint}`;
 
 				// Cleanup temp directory if used
 				if (tempArtifactsDir) {

package/src/core/tools/task/render.ts

@@ -111,8 +111,8 @@ export function renderCall(args: TaskParams, theme: Theme): Component {
 		return new Text(`${label} ${theme.fg("accent", task.agent)}: ${theme.fg("muted", taskPreview)}`, 0, 0);
 	}
 
-	// Multiple tasks - show count and agent names
-	const agents = args.tasks.map((t) => t.agent).join(", ");
+	// Multiple tasks - show count and descriptions (or agent names as fallback)
+	const agents = args.tasks.map((t) => t.description?.trim() || t.agent).join(", ");
 	return new Text(
 		`${label} ${theme.fg("muted", `${args.tasks.length} agents: ${truncate(agents, 50, theme.format.ellipsis)}`)}`,
 		0,
@@ -475,3 +475,8 @@ export function renderResult(
 
 	return new Text(lines.join("\n"), 0, 0);
 }
+
+export const taskToolRenderer = {
+	renderCall,
+	renderResult,
+};

package/src/core/tools/task/types.ts

@@ -1,4 +1,4 @@
-import type { Usage } from "@oh-my-pi/pi-ai";
+import type { Usage } from "@mariozechner/pi-ai";
 import { type Static, Type } from "@sinclair/typebox";
 
 /** Source of an agent definition */

package/src/core/tools/truncate.ts

@@ -5,7 +5,8 @@
  * - Line limit (default: 2000 lines)
  * - Byte limit (default: 50KB)
  *
- * Never returns partial lines (except bash tail truncation edge case).
+ * Never returns partial lines (except bash tail truncation edge case
+ * and the read tool's long-line snippet fallback).
  */
 
 export const DEFAULT_MAX_LINES = 2000;
@@ -250,6 +251,31 @@ function truncateStringToBytesFromEnd(str: string, maxBytes: number): string {
 	return buf.slice(start).toString("utf-8");
 }
 
+/**
+ * Truncate a string to fit within a byte limit (from the start).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+export function truncateStringToBytesFromStart(str: string, maxBytes: number): { text: string; bytes: number } {
+	const buf = Buffer.from(str, "utf-8");
+	if (buf.length <= maxBytes) {
+		return { text: str, bytes: buf.length };
+	}
+
+	let end = maxBytes;
+
+	// Find a valid UTF-8 boundary (start of a character)
+	while (end > 0 && (buf[end] & 0xc0) === 0x80) {
+		end--;
+	}
+
+	if (end <= 0) {
+		return { text: "", bytes: 0 };
+	}
+
+	const text = buf.slice(0, end).toString("utf-8");
+	return { text, bytes: Buffer.byteLength(text, "utf-8") };
+}
+
 /**
  * Truncate a single line to max characters, adding [truncated] suffix.
  * Used for grep match lines.

package/src/core/tools/web-fetch.ts

@@ -66,8 +66,6 @@ const CONVERTIBLE_EXTENSIONS = new Set([
 	".ogg",
 ]);
 
-const isWindows = process.platform === "win32";
-
 const USER_AGENTS = [
 	"curl/8.0",
 	"Mozilla/5.0 (compatible; TextBot/1.0)",
@@ -211,13 +209,7 @@ function exec(
  * Check if a command exists (cross-platform)
  */
 function hasCommand(cmd: string): boolean {
-	const checkCmd = isWindows ? "where" : "which";
-	const result = Bun.spawnSync([checkCmd, cmd], {
-		stdin: "ignore",
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	return result.exitCode === 0;
+	return Boolean(Bun.which(cmd));
 }
 
 /**
@@ -626,7 +618,18 @@ async function fetchBinary(
 
 		const contentType = response.headers.get("content-type") ?? "";
 		const contentDisposition = response.headers.get("content-disposition") ?? undefined;
+		const contentLength = response.headers.get("content-length");
+		if (contentLength) {
+			const size = Number.parseInt(contentLength, 10);
+			if (Number.isFinite(size) && size > MAX_BYTES) {
+				return { buffer: Buffer.alloc(0), contentType, contentDisposition, ok: false };
+			}
+		}
+
 		const buffer = Buffer.from(await response.arrayBuffer());
+		if (buffer.length > MAX_BYTES) {
+			return { buffer: Buffer.alloc(0), contentType, contentDisposition, ok: false };
+		}
 
 		return { buffer, contentType, contentDisposition, ok: true };
 	} catch {
@@ -1959,16 +1962,16 @@ async function renderUrl(url: string, timeout: number, raw: boolean = false): Pr
 	const notes: string[] = [];
 	const fetchedAt = new Date().toISOString();
 
-	// Step 0: Try special handlers for known sites (unless raw mode)
+	// Step 0: Normalize URL (ensure scheme for special handlers)
+	url = normalizeUrl(url);
+	const origin = getOrigin(url);
+
+	// Step 1: Try special handlers for known sites (unless raw mode)
 	if (!raw) {
 		const specialResult = await handleSpecialUrls(url, timeout);
 		if (specialResult) return specialResult;
 	}
 
-	// Step 1: Normalize URL
-	url = normalizeUrl(url);
-	const origin = getOrigin(url);
-
 	// Step 2: Fetch page
 	const response = await loadPage(url, { timeout });
 	if (!response.ok) {
@@ -2270,7 +2273,7 @@ export interface WebFetchToolDetails {
 export function createWebFetchTool(_cwd: string): AgentTool<typeof webFetchSchema> {
 	return {
 		name: "web_fetch",
-		label: "web_fetch",
+		label: "Web Fetch",
 		description: webFetchDescription,
 		parameters: webFetchSchema,
 		execute: async (
@@ -2483,6 +2486,11 @@ export function renderWebFetchResult(
 	return new Text(text, 0, 0);
 }
 
+export const webFetchToolRenderer = {
+	renderCall: renderWebFetchCall,
+	renderResult: renderWebFetchResult,
+};
+
 type WebFetchParams = { url: string; timeout?: number; raw?: boolean };
 
 /** Web fetch tool as CustomTool (for TUI rendering support) */

package/src/core/tools/web-search/index.ts

@@ -21,11 +21,13 @@ import { callExaTool, findApiKey as findExaKey, formatSearchResults, isSearchRes
 import { renderExaCall, renderExaResult } from "../exa/render";
 import type { ExaRenderDetails } from "../exa/types";
 import { formatAge } from "../render-utils";
+import { findAnthropicAuth } from "./auth";
 import { searchAnthropic } from "./providers/anthropic";
 import { searchExa } from "./providers/exa";
 import { findApiKey as findPerplexityKey, searchPerplexity } from "./providers/perplexity";
 import { renderWebSearchCall, renderWebSearchResult, type WebSearchRenderDetails } from "./render";
 import type { WebSearchProvider, WebSearchResponse } from "./types";
+import { WebSearchProviderError } from "./types";
 
 /** Web search parameters schema */
 export const webSearchSchema = Type.Object({
@@ -95,18 +97,78 @@ export type WebSearchParams = {
 	return_related_questions?: boolean;
 };
 
-/** Detect provider based on available API keys (priority: exa > perplexity > anthropic) */
-async function detectProvider(): Promise<WebSearchProvider> {
-	// Exa takes highest priority if key exists
+/** Preferred provider set via settings (default: auto) */
+let preferredProvider: WebSearchProvider | "auto" = "auto";
+
+/** Set the preferred web search provider from settings */
+export function setPreferredWebSearchProvider(provider: WebSearchProvider | "auto"): void {
+	preferredProvider = provider;
+}
+
+/** Determine which providers are configured (priority order) */
+async function getAvailableProviders(): Promise<WebSearchProvider[]> {
+	const providers: WebSearchProvider[] = [];
+
 	const exaKey = await findExaKey();
-	if (exaKey) return "exa";
+	if (exaKey) providers.push("exa");
 
-	// Perplexity second priority
 	const perplexityKey = await findPerplexityKey();
-	if (perplexityKey) return "perplexity";
+	if (perplexityKey) providers.push("perplexity");
+
+	const anthropicAuth = await findAnthropicAuth();
+	if (anthropicAuth) providers.push("anthropic");
+
+	return providers;
+}
+
+function formatProviderLabel(provider: WebSearchProvider): string {
+	switch (provider) {
+		case "exa":
+			return "Exa";
+		case "perplexity":
+			return "Perplexity";
+		case "anthropic":
+			return "Anthropic";
+		default:
+			return provider;
+	}
+}
+
+function formatProviderList(providers: WebSearchProvider[]): string {
+	return providers.map((provider) => formatProviderLabel(provider)).join(", ");
+}
+
+function buildNoProviderError(): string {
+	return "No web search provider configured. Set EXA_API_KEY, PERPLEXITY_API_KEY, ANTHROPIC_SEARCH_API_KEY, or ANTHROPIC_API_KEY.";
+}
+
+function formatProviderError(error: unknown, provider: WebSearchProvider): string {
+	if (error instanceof WebSearchProviderError) {
+		if (error.provider === "anthropic" && error.status === 404) {
+			return "Anthropic web search returned 404 (model or endpoint not found). Set ANTHROPIC_SEARCH_MODEL/ANTHROPIC_SEARCH_BASE_URL, or configure EXA_API_KEY or PERPLEXITY_API_KEY.";
+		}
+		if (error.status === 401 || error.status === 403) {
+			return `${formatProviderLabel(error.provider)} authorization failed (${error.status}). Check API key or base URL.`;
+		}
+		return error.message;
+	}
+	if (error instanceof Error) return error.message;
+	return `Unknown error from ${formatProviderLabel(provider)}`;
+}
+
+async function resolveProviderChain(
+	requestedProvider?: WebSearchProvider | "auto",
+): Promise<{ providers: WebSearchProvider[]; allowFallback: boolean }> {
+	if (requestedProvider && requestedProvider !== "auto") {
+		return { providers: [requestedProvider], allowFallback: false };
+	}
+
+	if (preferredProvider !== "auto") {
+		return { providers: [preferredProvider], allowFallback: false };
+	}
 
-	// Default to Anthropic
-	return "anthropic";
+	const providers = await getAvailableProviders();
+	return { providers, allowFallback: true };
 }
 
 /** Truncate text for tool output */
@@ -198,48 +260,71 @@ async function executeWebSearch(
 	_toolCallId: string,
 	params: WebSearchParams,
 ): Promise<{ content: Array<{ type: "text"; text: string }>; details: WebSearchRenderDetails }> {
-	try {
-		const provider = params.provider && params.provider !== "auto" ? params.provider : await detectProvider();
-
-		let response: WebSearchResponse;
-		if (provider === "exa") {
-			response = await searchExa({
-				query: params.query,
-				num_results: params.num_results,
-			});
-		} else if (provider === "anthropic") {
-			response = await searchAnthropic({
-				query: params.query,
-				system_prompt: params.system_prompt,
-				max_tokens: params.max_tokens,
-				num_results: params.num_results,
-			});
-		} else {
-			response = await searchPerplexity({
-				query: params.query,
-				model: params.model,
-				system_prompt: params.system_prompt,
-				search_recency_filter: params.search_recency_filter,
-				search_domain_filter: params.search_domain_filter,
-				search_context_size: params.search_context_size,
-				return_related_questions: params.return_related_questions,
-				num_results: params.num_results,
-			});
-		}
+	const { providers, allowFallback } = await resolveProviderChain(params.provider);
 
-		const text = formatForLLM(response);
-
-		return {
-			content: [{ type: "text" as const, text }],
-			details: { response },
-		};
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
+	if (providers.length === 0) {
+		const message = buildNoProviderError();
+		const fallbackProvider = preferredProvider === "auto" ? "anthropic" : preferredProvider;
 		return {
 			content: [{ type: "text" as const, text: `Error: ${message}` }],
-			details: { response: { provider: "anthropic", sources: [] }, error: message },
+			details: { response: { provider: fallbackProvider, sources: [] }, error: message },
 		};
 	}
+
+	let lastError: unknown;
+	let lastProvider = providers[0];
+
+	for (const provider of providers) {
+		lastProvider = provider;
+		try {
+			let response: WebSearchResponse;
+			if (provider === "exa") {
+				response = await searchExa({
+					query: params.query,
+					num_results: params.num_results,
+				});
+			} else if (provider === "anthropic") {
+				response = await searchAnthropic({
+					query: params.query,
+					system_prompt: params.system_prompt,
+					max_tokens: params.max_tokens,
+					num_results: params.num_results,
+				});
+			} else {
+				response = await searchPerplexity({
+					query: params.query,
+					model: params.model,
+					system_prompt: params.system_prompt,
+					search_recency_filter: params.search_recency_filter,
+					search_domain_filter: params.search_domain_filter,
+					search_context_size: params.search_context_size,
+					return_related_questions: params.return_related_questions,
+					num_results: params.num_results,
+				});
+			}
+
+			const text = formatForLLM(response);
+
+			return {
+				content: [{ type: "text" as const, text }],
+				details: { response },
+			};
+		} catch (error) {
+			lastError = error;
+			if (!allowFallback) break;
+		}
+	}
+
+	const baseMessage = formatProviderError(lastError, lastProvider);
+	const message =
+		allowFallback && providers.length > 1
+			? `All web search providers failed (${formatProviderList(providers)}). Last error: ${baseMessage}`
+			: baseMessage;
+
+	return {
+		content: [{ type: "text" as const, text: `Error: ${message}` }],
+		details: { response: { provider: lastProvider, sources: [] }, error: message },
+	};
 }
 
 /** Web search tool as AgentTool (for allTools export) */

package/src/core/tools/web-search/providers/anthropic.ts

@@ -14,8 +14,9 @@ import type {
 	WebSearchResponse,
 	WebSearchSource,
 } from "../types";
+import { WebSearchProviderError } from "../types";
 
-const DEFAULT_MODEL = "claude-sonnet-4-5-20250514";
+const DEFAULT_MODEL = "claude-haiku-4-5";
 const DEFAULT_MAX_TOKENS = 4096;
 
 export interface AnthropicSearchParams {
@@ -80,7 +81,11 @@ async function callWebSearch(
 
 	if (!response.ok) {
 		const errorText = await response.text();
-		throw new Error(`Anthropic API error (${response.status}): ${errorText}`);
+		throw new WebSearchProviderError(
+			"anthropic",
+			`Anthropic API error (${response.status}): ${errorText}`,
+			response.status,
+		);
 	}
 
 	return response.json() as Promise<AnthropicApiResponse>;

package/src/core/tools/web-search/providers/exa.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import type { WebSearchResponse, WebSearchSource } from "../types";
+import { WebSearchProviderError } from "../types";
 
 const EXA_API_URL = "https://api.exa.ai/search";
 
@@ -142,7 +143,7 @@ async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<E
 
 	if (!response.ok) {
 		const errorText = await response.text();
-		throw new Error(`Exa API error (${response.status}): ${errorText}`);
+		throw new WebSearchProviderError("exa", `Exa API error (${response.status}): ${errorText}`, response.status);
 	}
 
 	return response.json() as Promise<ExaSearchResponse>;

package/src/core/tools/web-search/providers/perplexity.ts

@@ -13,6 +13,7 @@ import type {
 	WebSearchResponse,
 	WebSearchSource,
 } from "../types";
+import { WebSearchProviderError } from "../types";
 
 const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
 
@@ -92,7 +93,11 @@ async function callPerplexity(apiKey: string, request: PerplexityRequest): Promi
 
 	if (!response.ok) {
 		const errorText = await response.text();
-		throw new Error(`Perplexity API error (${response.status}): ${errorText}`);
+		throw new WebSearchProviderError(
+			"perplexity",
+			`Perplexity API error (${response.status}): ${errorText}`,
+			response.status,
+		);
 	}
 
 	return response.json() as Promise<PerplexityResponse>;

package/src/core/tools/web-search/render.ts

@@ -325,3 +325,8 @@ export function renderWebSearchCall(
 	const text = `${theme.fg("toolTitle", "Web Search")} ${theme.fg("dim", `(${provider})`)} ${theme.fg("muted", query)}`;
 	return new Text(text, 0, 0);
 }
+
+export const webSearchToolRenderer = {
+	renderCall: renderWebSearchCall,
+	renderResult: renderWebSearchResult,
+};

package/src/core/tools/web-search/types.ts

@@ -57,6 +57,19 @@ export interface WebSearchResponse {
 	requestId?: string;
 }
 
+/** Provider-specific error with optional HTTP status */
+export class WebSearchProviderError extends Error {
+	provider: WebSearchProvider;
+	status?: number;
+
+	constructor(provider: WebSearchProvider, message: string, status?: number) {
+		super(message);
+		this.name = "WebSearchProviderError";
+		this.provider = provider;
+		this.status = status;
+	}
+}
+
 /** Auth configuration for Anthropic */
 export interface AnthropicAuthConfig {
 	apiKey: string;