@oh-my-pi/pi-coding-agent 15.8.3 → 15.9.1

package/src/tools/{todo-write.ts → todo.ts}

@@ -6,7 +6,7 @@ import chalk from "chalk";
 import * as z from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
-import todoWriteDescription from "../prompts/tools/todo-write.md" with { type: "text" };
+import todoDescription from "../prompts/tools/todo.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
 import type { SessionEntry } from "../session/session-manager";
 import { renderStatusLine, renderTreeList } from "../tui";
@@ -40,7 +40,7 @@ export interface TodoCompletionTransition {
 	content: string;
 }
 
-export interface TodoWriteToolDetails {
+export interface TodoToolDetails {
 	phases: TodoPhase[];
 	storage: "session" | "memory";
 	completedTasks?: TodoCompletionTransition[];
@@ -68,14 +68,14 @@ const TodoOpEntry = z.object({
 	text: z.string().optional().describe("note text"),
 });
 
-const todoWriteSchema = z
+const todoSchema = z
 	.object({
 		ops: z.array(TodoOpEntry).min(1).describe("ordered todo operations"),
 	})
 	.describe("apply ordered todo operations");
 
-type TodoWriteParams = z.infer<typeof todoWriteSchema>;
-type TodoOpEntryValue = TodoWriteParams["ops"][number];
+type TodoParams = z.infer<typeof todoSchema>;
+type TodoOpEntryValue = TodoParams["ops"][number];
 
 // =============================================================================
 // State helpers
@@ -159,7 +159,7 @@ export function getLatestTodoPhasesFromEntries(entries: SessionEntry[]): TodoPha
 		}
 		if (entry.type !== "message") continue;
 		const message = entry.message as { role?: string; toolName?: string; details?: unknown; isError?: boolean };
-		if (message.role !== "toolResult" || message.toolName !== "todo_write" || message.isError) continue;
+		if (message.role !== "toolResult" || message.toolName !== "todo" || message.isError) continue;
 
 		const details = message.details as { phases?: unknown } | undefined;
 		if (!details || !Array.isArray(details.phases)) continue;
@@ -178,7 +178,7 @@ export function getLatestTodoPhasesFromEntries(entries: SessionEntry[]): TodoPha
  * the caller can render a `+N more` hint. When every task in `tasks` is
  * closed (completed or abandoned), returns the trailing `maxVisible` tasks
  * with `hiddenOpenCount = 0`, so the panel keeps useful context until the
- * active-phase pointer advances on the next `todo_write`.
+ * active-phase pointer advances on the next `todo`.
  *
  * Task identity and order are preserved — this is a slice, never a sort.
  */
@@ -383,7 +383,7 @@ function applyEntry(phases: TodoPhase[], entry: TodoOpEntryValue, errors: string
 	}
 }
 
-function applyParams(phases: TodoPhase[], params: TodoWriteParams): { phases: TodoPhase[]; errors: string[] } {
+function applyParams(phases: TodoPhase[], params: TodoParams): { phases: TodoPhase[]; errors: string[] } {
 	const errors: string[] = [];
 	let next = phases;
 	for (const entry of params.ops) {
@@ -393,10 +393,10 @@ function applyParams(phases: TodoPhase[], params: TodoWriteParams): { phases: To
 	return { phases: next, errors };
 }
 
-/** Apply an array of `todo_write`-style ops to existing phases. Used by /todo slash command. */
+/** Apply an array of `todo`-style ops to existing phases. Used by /todo slash command. */
 export function applyOpsToPhases(
 	currentPhases: TodoPhase[],
-	ops: TodoWriteParams["ops"],
+	ops: TodoParams["ops"],
 ): { phases: TodoPhase[]; errors: string[] } {
 	return applyParams(clonePhases(currentPhases), { ops });
 }
@@ -586,33 +586,33 @@ function formatSummary(phases: TodoPhase[], errors: string[]): string {
 // Tool Class
 // =============================================================================
 
-export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWriteToolDetails> {
-	readonly name = "todo_write";
+export class TodoTool implements AgentTool<typeof todoSchema, TodoToolDetails> {
+	readonly name = "todo";
 	readonly approval = "read" as const;
-	readonly label = "Todo Write";
+	readonly label = "Todo";
 	readonly summary = "Write a structured todo list to track progress within a session";
 	readonly description: string;
-	readonly parameters = todoWriteSchema;
+	readonly parameters = todoSchema;
 	readonly concurrency = "exclusive";
 	readonly strict = true;
 	readonly loadMode = "discoverable";
 	constructor(private readonly session: ToolSession) {
-		this.description = prompt.render(todoWriteDescription);
+		this.description = prompt.render(todoDescription);
 	}
 
 	async execute(
 		_toolCallId: string,
-		params: TodoWriteParams,
+		params: TodoParams,
 		_signal?: AbortSignal,
-		_onUpdate?: AgentToolUpdateCallback<TodoWriteToolDetails>,
+		_onUpdate?: AgentToolUpdateCallback<TodoToolDetails>,
 		_context?: AgentToolContext,
-	): Promise<AgentToolResult<TodoWriteToolDetails>> {
+	): Promise<AgentToolResult<TodoToolDetails>> {
 		const previousPhases = clonePhases(this.session.getTodoPhases?.() ?? []);
 		const { phases: updated, errors } = applyParams(clonePhases(previousPhases), params);
 		const completedTasks = getCompletionTransitions(previousPhases, updated);
 		this.session.setTodoPhases?.(updated);
 		const storage = this.session.getSessionFile() ? "session" : "memory";
-		const details: TodoWriteToolDetails = { phases: updated, storage };
+		const details: TodoToolDetails = { phases: updated, storage };
 		if (completedTasks.length > 0) details.completedTasks = completedTasks;
 
 		return {
@@ -627,7 +627,7 @@ export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWrit
 // TUI Renderer
 // =============================================================================
 
-type TodoWriteRenderArgs = {
+type TodoRenderArgs = {
 	ops?: Array<{
 		op?: string;
 		task?: string;
@@ -701,9 +701,9 @@ function noteMarker(count: number, uiTheme: Theme): string {
 	return uiTheme.fg("dim", chalk.italic(` \u207a${toSuperscript(count)}`));
 }
 
-export const TODO_WRITE_STRIKE_HOLD_FRAMES = 2;
-export const TODO_WRITE_STRIKE_REVEAL_FRAMES = 12;
-export const TODO_WRITE_STRIKE_TOTAL_FRAMES = TODO_WRITE_STRIKE_HOLD_FRAMES + TODO_WRITE_STRIKE_REVEAL_FRAMES;
+export const TODO_STRIKE_HOLD_FRAMES = 2;
+export const TODO_STRIKE_REVEAL_FRAMES = 12;
+export const TODO_STRIKE_TOTAL_FRAMES = TODO_STRIKE_HOLD_FRAMES + TODO_STRIKE_REVEAL_FRAMES;
 const EMPTY_COMPLETION_KEYS = new Set<string>();
 const STRIKE_START = "\x1b[9m";
 const STRIKE_END = "\x1b[29m";
@@ -721,11 +721,11 @@ function partialStrikethrough(text: string, visibleChars: number): string {
 
 function strikeRevealCount(text: string, frame: number | undefined): number | undefined {
 	if (frame === undefined) return undefined;
-	if (frame <= TODO_WRITE_STRIKE_HOLD_FRAMES) return 0;
+	if (frame <= TODO_STRIKE_HOLD_FRAMES) return 0;
 	const chars = [...text];
 	if (chars.length === 0) return undefined;
-	const revealFrame = Math.min(frame - TODO_WRITE_STRIKE_HOLD_FRAMES, TODO_WRITE_STRIKE_REVEAL_FRAMES);
-	return Math.ceil((chars.length * revealFrame) / TODO_WRITE_STRIKE_REVEAL_FRAMES);
+	const revealFrame = Math.min(frame - TODO_STRIKE_HOLD_FRAMES, TODO_STRIKE_REVEAL_FRAMES);
+	return Math.ceil((chars.length * revealFrame) / TODO_STRIKE_REVEAL_FRAMES);
 }
 
 function formatTodoLine(
@@ -775,8 +775,8 @@ function renderNoteAttachments(phases: TodoPhase[], uiTheme: Theme): string[] {
 	return lines;
 }
 
-export const todoWriteToolRenderer = {
-	renderCall(args: TodoWriteRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+export const todoToolRenderer = {
+	renderCall(args: TodoRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const ops = args?.ops?.map(entry => {
 			const parts = [entry.op ?? "update"];
 			if (entry.task) parts.push(entry.task);
@@ -784,15 +784,15 @@ export const todoWriteToolRenderer = {
 			if (entry.items?.length) parts.push(`${entry.items.length} item${entry.items.length === 1 ? "" : "s"}`);
 			return parts.join(" ");
 		}) ?? ["update"];
-		const text = renderStatusLine({ icon: "pending", title: "Todo Write", meta: ops }, uiTheme);
+		const text = renderStatusLine({ icon: "pending", title: "Todo", meta: ops }, uiTheme);
 		return new Text(text, 0, 0);
 	},
 
 	renderResult(
-		result: { content: Array<{ type: string; text?: string }>; details?: TodoWriteToolDetails },
+		result: { content: Array<{ type: string; text?: string }>; details?: TodoToolDetails },
 		options: RenderResultOptions,
 		uiTheme: Theme,
-		_args?: TodoWriteRenderArgs,
+		_args?: TodoRenderArgs,
 	): Component {
 		const phases = (result.details?.phases ?? []).filter(phase => phase.tasks.length > 0);
 		const completedTasks = result.details?.completedTasks ?? [];
@@ -806,10 +806,7 @@ export const todoWriteToolRenderer = {
 			keys.add(task.content);
 		}
 		const allTasks = phases.flatMap(phase => phase.tasks);
-		const header = renderStatusLine(
-			{ icon: "success", title: "Todo Write", meta: [`${allTasks.length} tasks`] },
-			uiTheme,
-		);
+		const header = renderStatusLine({ icon: "success", title: "Todo", meta: [`${allTasks.length} tasks`] }, uiTheme);
 		if (allTasks.length === 0) {
 			const fallback = result.content?.find(content => content.type === "text")?.text ?? "No todos";
 			return new Text(`${header}\n${uiTheme.fg("dim", fallback)}`, 0, 0);

package/src/tools/write.ts

@@ -135,6 +135,15 @@ function maybeWriteSnapshotHeader(session: ToolSession, absolutePath: string, co
 	return formatHashlineHeader(formatPathRelativeToCwd(absolutePath, session.cwd), tag);
 }
 
+function shouldRouteWriteThroughBridge(session: ToolSession, requestedPath: string, absolutePath: string): boolean {
+	if (isInternalUrlPath(requestedPath)) return false;
+
+	const state = session.getPlanModeState?.();
+	if (!state?.enabled || !isInternalUrlPath(state.planFilePath)) return true;
+
+	return absolutePath !== resolvePlanPath(session, state.planFilePath);
+}
+
 /**
  * Append a trailing note line to the first text block of a tool result.
  * Mutates `result` in place (the result object is owned by this call).
@@ -845,8 +854,11 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				await assertEditableFile(absolutePath, path);
 			}
 
-			// Try ACP bridge first — no disk write when client handles it
-			const bridgePromise = this.#routeWriteThroughBridge(absolutePath, cleanContent);
+			// Try ACP bridge first for editor-visible filesystem paths. Internal
+			// artifacts such as local:// plans are owned by OMP, not the editor.
+			const bridgePromise = shouldRouteWriteThroughBridge(this.session, path, absolutePath)
+				? this.#routeWriteThroughBridge(absolutePath, cleanContent)
+				: undefined;
 			if (bridgePromise !== undefined) {
 				try {
 					await bridgePromise;

package/src/tui/status-line.ts

@@ -15,22 +15,33 @@ export interface StatusLineOptions {
 	meta?: string[];
 }
 
+/**
+ * Flatten CR/LF runs in caller-supplied header fragments so a single newline
+ * embedded in `description` or `meta` cannot expand the status line into
+ * multiple rows — which would otherwise break the bordered output block the
+ * header sits on. Tab characters are left alone; tool renderers that need
+ * tab-safe text run `replaceTabs()` themselves.
+ */
+function flattenForHeader(text: string): string {
+	return text.replace(/\r\n?|\n/g, " ");
+}
+
 export function renderStatusLine(options: StatusLineOptions, theme: Theme): string {
 	const icon = options.icon ? formatStatusIcon(options.icon, theme, options.spinnerFrame) : "";
 	const titleColor = options.titleColor ?? "accent";
-	const title = theme.fg(titleColor, options.title);
+	const title = theme.fg(titleColor, flattenForHeader(options.title));
 	let line = icon ? `${icon} ${title}` : title;
 
 	if (options.description) {
-		line += `: ${theme.fg("muted", options.description)}`;
+		line += `: ${theme.fg("muted", flattenForHeader(options.description))}`;
 	}
 
 	if (options.badge) {
 		const { label, color } = options.badge;
-		line += ` ${theme.fg(color, `${theme.format.bracketLeft}${label}${theme.format.bracketRight}`)}`;
+		line += ` ${theme.fg(color, `${theme.format.bracketLeft}${flattenForHeader(label)}${theme.format.bracketRight}`)}`;
 	}
 
-	const meta = options.meta?.filter(value => value.trim().length > 0) ?? [];
+	const meta = options.meta?.map(flattenForHeader).filter(value => value.trim().length > 0) ?? [];
 	if (meta.length > 0) {
 		line += ` ${theme.fg("dim", meta.join(theme.sep.dot))}`;
 	}

package/src/utils/session-color.ts

@@ -1,3 +1,5 @@
+import { hslToHex, relativeLuminance } from "@oh-my-pi/pi-utils";
+
 /**
  * Derive a stable hue (0-359) from a string using djb2 hash.
  */
@@ -10,27 +12,50 @@ function nameToHue(name: string): number {
 	return hash % 360;
 }
 
+const ACCENT_SATURATION = 0.9;
+const ACCENT_DARK_LIGHTNESS = 0.72;
+/** Minimum contrast ratio (WCAG AA large text) between a light-theme accent and its surface. */
+const ACCENT_MIN_CONTRAST = 3;
+
 /**
- * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
+ * Largest relative luminance an accent may have while still meeting
+ * {@link ACCENT_MIN_CONTRAST} against a surface of the given luminance.
  */
-function hslToHex(h: number, s: number, l: number): string {
-	const a = s * Math.min(l, 1 - l);
-	const f = (n: number) => {
-		const k = (n + h / 30) % 12;
-		const color = l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
-		return Math.round(255 * color)
-			.toString(16)
-			.padStart(2, "0");
-	};
-	return `#${f(0)}${f(8)}${f(4)}`;
+function accentLuminanceCap(surfaceLuminance: number): number {
+	return Math.max(0, (surfaceLuminance + 0.05) / ACCENT_MIN_CONTRAST - 0.05);
 }
 
 /**
  * Derive a stable CSS hex accent color from a session name.
- * High saturation, vivid — suitable for both status bar text and border coloring.
+ *
+ * On dark themes (`surfaceLuminance` undefined) the accent is vivid (high
+ * saturation, high lightness). On light themes the lightness is reduced until the
+ * accent's perceived luminance clears {@link ACCENT_MIN_CONTRAST} against the
+ * actual surface it renders on — so it stays legible on near-white *and* mid-light
+ * backgrounds — while keeping the same per-session hue.
  */
-export function getSessionAccentHex(name: string): string {
-	return hslToHex(nameToHue(name), 0.9, 0.72);
+export function getSessionAccentHex(name: string, surfaceLuminance?: number): string {
+	const hue = nameToHue(name);
+	if (surfaceLuminance === undefined) {
+		return hslToHex(hue, ACCENT_SATURATION, ACCENT_DARK_LIGHTNESS);
+	}
+
+	const cap = accentLuminanceCap(surfaceLuminance);
+	const top = hslToHex(hue, ACCENT_SATURATION, ACCENT_DARK_LIGHTNESS);
+	if ((relativeLuminance(top) ?? 0) <= cap) return top;
+
+	// Bisect lightness: `lo` always yields luminance <= cap, `hi` always above it.
+	let lo = 0;
+	let hi = ACCENT_DARK_LIGHTNESS;
+	for (let i = 0; i < 20; i++) {
+		const mid = (lo + hi) / 2;
+		if ((relativeLuminance(hslToHex(hue, ACCENT_SATURATION, mid)) ?? 0) > cap) {
+			hi = mid;
+		} else {
+			lo = mid;
+		}
+	}
+	return hslToHex(hue, ACCENT_SATURATION, lo);
 }
 
 /**

package/src/utils/title-generator.ts

@@ -10,7 +10,7 @@ import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
 import titleSystemPrompt from "../prompts/system/title-system.md" with { type: "text" };
 import { ONLINE_TINY_TITLE_MODEL_KEY } from "../tiny/models";
-import { formatTitleUserMessage, normalizeGeneratedTitle } from "../tiny/text";
+import { formatTitleUserMessage, isLowSignalTitleInput, normalizeGeneratedTitle } from "../tiny/text";
 import { tinyTitleClient } from "../tiny/title-client";
 
 const TITLE_SYSTEM_PROMPT = prompt.render(titleSystemPrompt);
@@ -31,7 +31,8 @@ const setTitleTool: Tool = {
 		properties: {
 			title: {
 				type: "string",
-				description: "A concise 3-6 word title for the session.",
+				description:
+					'A concise 3-6 word title for the session, or exactly "none" when the message carries no concrete task yet (greeting, small talk, vague).',
 			},
 		},
 		required: ["title"],
@@ -144,6 +145,12 @@ export async function generateSessionTitle(
 	currentModel?: Model<Api>,
 	metadataResolver?: (provider: string) => Record<string, unknown> | undefined,
 ): Promise<string | null> {
+	// Defer titling for greetings / acknowledgements / empty input. The default
+	// tiny title model can't reliably decline trivial input, so this happens
+	// deterministically before any model is invoked; the caller retries on the
+	// next user message while the session stays unnamed.
+	if (isLowSignalTitleInput(firstMessage)) return null;
+
 	const tinyModel = settings.get("providers.tinyModel");
 	if (tinyModel === ONLINE_TINY_TITLE_MODEL_KEY) {
 		return generateTitleOnline(firstMessage, registry, settings, sessionId, currentModel, metadataResolver);

package/src/web/search/index.ts

@@ -131,7 +131,9 @@ async function executeSearch(
 	const providers =
 		params.provider && params.provider !== "auto"
 			? await getSearchProvider(params.provider).then(async provider =>
-					(await provider.isAvailable(authStorage)) ? [provider] : resolveProviderChain(authStorage, "auto"),
+					(await provider.isExplicitlyAvailable(authStorage))
+						? [provider]
+						: resolveProviderChain(authStorage, "auto"),
 				)
 			: await resolveProviderChain(authStorage);
 	if (providers.length === 0) {
@@ -220,7 +222,7 @@ export async function runSearchQuery(
 /**
  * Web search tool implementation.
  *
- * Supports Anthropic, Perplexity, Exa, Brave, Jina, Kimi, Gemini, Codex, Z.AI, SearXNG, and Synthetic providers with automatic fallback.
+ * Supports the configured web-search provider chain with automatic fallback.
  */
 export class WebSearchTool implements AgentTool<typeof webSearchSchema, SearchRenderDetails> {
 	readonly name = "web_search";

package/src/web/search/provider.ts

@@ -5,15 +5,16 @@
 // fetch/parse/format helpers) and only one — at most — is needed per session,
 // so eager construction was wasted work at startup.
 //
-// The `label`/`id` metadata is kept inline so callers needing a display name
-// (error formatting, UI listings) do not force a load.
+// Provider modules are loaded lazily; display metadata lives in types.ts so UI
+// listings can share it without importing provider implementations.
 
 import type { AuthStorage } from "@oh-my-pi/pi-ai";
 import type { SearchProvider } from "./providers/base";
-import type { SearchProviderId } from "./types";
+import { SEARCH_PROVIDER_LABELS, SEARCH_PROVIDER_ORDER, type SearchProviderId } from "./types";
 
 export type { SearchParams } from "./providers/base";
 export { SearchProvider } from "./providers/base";
+export { SEARCH_PROVIDER_ORDER } from "./types";
 
 interface ProviderMeta {
 	id: SearchProviderId;
@@ -25,72 +26,72 @@ interface ProviderMeta {
 const PROVIDER_META: Record<SearchProviderId, ProviderMeta> = {
 	exa: {
 		id: "exa",
-		label: "Exa",
+		label: SEARCH_PROVIDER_LABELS.exa,
 		load: async () => new (await import("./providers/exa")).ExaProvider(),
 	},
 	brave: {
 		id: "brave",
-		label: "Brave",
+		label: SEARCH_PROVIDER_LABELS.brave,
 		load: async () => new (await import("./providers/brave")).BraveProvider(),
 	},
 	jina: {
 		id: "jina",
-		label: "Jina",
+		label: SEARCH_PROVIDER_LABELS.jina,
 		load: async () => new (await import("./providers/jina")).JinaProvider(),
 	},
 	perplexity: {
 		id: "perplexity",
-		label: "Perplexity",
+		label: SEARCH_PROVIDER_LABELS.perplexity,
 		load: async () => new (await import("./providers/perplexity")).PerplexityProvider(),
 	},
 	kimi: {
 		id: "kimi",
-		label: "Kimi",
+		label: SEARCH_PROVIDER_LABELS.kimi,
 		load: async () => new (await import("./providers/kimi")).KimiProvider(),
 	},
 	zai: {
 		id: "zai",
-		label: "Z.AI",
+		label: SEARCH_PROVIDER_LABELS.zai,
 		load: async () => new (await import("./providers/zai")).ZaiProvider(),
 	},
 	anthropic: {
 		id: "anthropic",
-		label: "Anthropic",
+		label: SEARCH_PROVIDER_LABELS.anthropic,
 		load: async () => new (await import("./providers/anthropic")).AnthropicProvider(),
 	},
 	gemini: {
 		id: "gemini",
-		label: "Gemini",
+		label: SEARCH_PROVIDER_LABELS.gemini,
 		load: async () => new (await import("./providers/gemini")).GeminiProvider(),
 	},
 	codex: {
 		id: "codex",
-		label: "OpenAI",
+		label: SEARCH_PROVIDER_LABELS.codex,
 		load: async () => new (await import("./providers/codex")).CodexProvider(),
 	},
 	tavily: {
 		id: "tavily",
-		label: "Tavily",
+		label: SEARCH_PROVIDER_LABELS.tavily,
 		load: async () => new (await import("./providers/tavily")).TavilyProvider(),
 	},
 	parallel: {
 		id: "parallel",
-		label: "Parallel",
+		label: SEARCH_PROVIDER_LABELS.parallel,
 		load: async () => new (await import("./providers/parallel")).ParallelProvider(),
 	},
 	kagi: {
 		id: "kagi",
-		label: "Kagi",
+		label: SEARCH_PROVIDER_LABELS.kagi,
 		load: async () => new (await import("./providers/kagi")).KagiProvider(),
 	},
 	synthetic: {
 		id: "synthetic",
-		label: "Synthetic",
+		label: SEARCH_PROVIDER_LABELS.synthetic,
 		load: async () => new (await import("./providers/synthetic")).SyntheticProvider(),
 	},
 	searxng: {
 		id: "searxng",
-		label: "SearXNG",
+		label: SEARCH_PROVIDER_LABELS.searxng,
 		load: async () => new (await import("./providers/searxng")).SearXNGProvider(),
 	},
 };
@@ -118,23 +119,6 @@ export async function getSearchProvider(id: SearchProviderId): Promise<SearchPro
 	return provider;
 }
 
-export const SEARCH_PROVIDER_ORDER: SearchProviderId[] = [
-	"tavily",
-	"perplexity",
-	"brave",
-	"jina",
-	"kimi",
-	"anthropic",
-	"gemini",
-	"codex",
-	"zai",
-	"exa",
-	"parallel",
-	"kagi",
-	"synthetic",
-	"searxng",
-];
-
 /** Preferred provider set via settings (default: auto) */
 let preferredProvId: SearchProviderId | "auto" = "auto";
 
@@ -156,7 +140,7 @@ export async function resolveProviderChain(
 
 	if (preferredProvider !== "auto") {
 		const provider = await getSearchProvider(preferredProvider);
-		if (await provider.isAvailable(authStorage)) {
+		if (await provider.isExplicitlyAvailable(authStorage)) {
 			providers.push(provider);
 		}
 	}

package/src/web/search/providers/base.ts

@@ -61,9 +61,26 @@ export abstract class SearchProvider {
 	 * Indicates whether this provider has the credentials/config it needs to
 	 * service a request right now. Implementations consult the passed
 	 * {@link AuthStorage} — never a sibling store.
+	 *
+	 * Drives auto-chain admission: providers that return `false` are skipped
+	 * when {@link resolveProviderChain} walks the order. Explicit selection
+	 * uses {@link isExplicitlyAvailable} instead.
 	 */
 	abstract isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean;
 
+	/**
+	 * Returns `true` when this provider should run when the user explicitly
+	 * selects it, even if {@link isAvailable} would reject it for the auto
+	 * chain. Providers that ship an unauthenticated fallback (e.g. Exa's
+	 * public MCP) override this so explicit selection still routes through
+	 * the fallback rather than silently falling back to another provider.
+	 *
+	 * Defaults to mirroring {@link isAvailable}.
+	 */
+	isExplicitlyAvailable(authStorage: AuthStorage): Promise<boolean> | boolean {
+		return this.isAvailable(authStorage);
+	}
+
 	/**
 	 * Execute a search. Credentials MUST be resolved through `params.authStorage`.
 	 */