@gajae-code/coding-agent 0.5.1 → 0.5.3

package/src/tools/subagent.ts

@@ -4,7 +4,7 @@ import { prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { type AsyncJob, AsyncJobManager, jobElapsedMs, type SubagentRecord } from "../async";
 import subagentDescription from "../prompts/tools/subagent.md" with { type: "text" };
-import type { AgentProgress, AgentSource } from "../task/types";
+import type { AgentProgress, AgentSource, TaskToolDetails } from "../task/types";
 import { Ellipsis, truncateToWidth } from "../tui";
 import type { ToolSession } from "./index";
 import { replaceTabs } from "./render-utils";
@@ -330,12 +330,21 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		);
 		const watchedJobIds = runningJobs.map(job => job.id);
 		manager.watchJobs(watchedJobIds);
-		const progressTimer = onUpdate
-			? setInterval(() => {
-					onUpdate(this.#progressResult(manager, records, true));
-				}, 500)
-			: undefined;
-		onUpdate?.(this.#progressResult(manager, records, true));
+		let lastEmittedSignature: string | undefined;
+		const emitIfChanged = (force: boolean): void => {
+			if (!onUpdate) return;
+			const result = this.#progressResult(manager, records, true);
+			const signature = subagentAwaitRenderedStateSignature(result.details?.subagents ?? []);
+			if (!force && signature === lastEmittedSignature) return;
+			lastEmittedSignature = signature;
+			onUpdate(result);
+		};
+		const progressTimer = onUpdate ? setInterval(() => emitIfChanged(false), 500) : undefined;
+		// Initial emission so the panel appears immediately; later idle ticks are
+		// gated on a value-based rendered-state signature so unchanged progress no
+		// longer rebuilds the renderer component or mutates transcript lines above
+		// the viewport (the source of the await-panel repaint storms).
+		emitIfChanged(true);
 
 		let timedOut = false;
 		try {
@@ -720,3 +729,134 @@ function previewJobOutput(
 	const preview = truncateToWidth(normalized, width, Ellipsis.Unicode);
 	return { type: source.type, preview, truncated: preview !== normalized };
 }
+
+/**
+ * Canonical, value-based rendered-state signature for the `subagent` await panel.
+ *
+ * Producer-side await gating compares this signature against the last emitted one
+ * and only fires `onUpdate` when the *rendered* state actually changed. Unchanged
+ * idle ticks therefore stop rebuilding the renderer component and stop mutating
+ * transcript lines above the viewport, which is what triggers TUI full-redraw
+ * storms (`tui.ts` `firstChanged < viewportTop`).
+ *
+ * It is deliberately value-based, never object identity: `AsyncJobManager.record-
+ * SubagentProgress` stores a `structuredClone` but `getSubagentProgress` returns
+ * the retained object by reference, so identity comparison would be both noisy and
+ * unsafe.
+ *
+ * Time-derived fields are intentionally excluded so the panel does not churn while
+ * idle: raw durations (`durationMs`), current-tool elapsed (`currentToolStartMs`),
+ * and retry countdowns (`retryState.startedAtMs`) are omitted. Idle duration and
+ * countdown ticking is sacrificed by design; every real transition still changes
+ * the signature.
+ */
+export function subagentAwaitRenderedStateSignature(subagents: readonly SubagentSnapshot[]): string {
+	return JSON.stringify(subagents.map(canonicalizeSnapshotForSignature));
+}
+
+function canonicalizeSnapshotForSignature(snapshot: SubagentSnapshot): unknown {
+	return {
+		id: snapshot.id,
+		jobId: snapshot.jobId,
+		status: snapshot.status,
+		label: snapshot.label,
+		agent: snapshot.agent,
+		agentSource: snapshot.agentSource,
+		description: snapshot.description ?? null,
+		assignment: snapshot.assignment ?? null,
+		resultText: snapshot.resultText ?? null,
+		errorText: snapshot.errorText ?? null,
+		resultPreview: snapshot.resultPreview ?? null,
+		outputRef: snapshot.outputRef ?? null,
+		truncated: snapshot.truncated ?? false,
+		guidance: snapshot.guidance ?? null,
+		liveProgressAvailable: snapshot.liveProgressAvailable ?? null,
+		effectiveModel: snapshot.effectiveModel ?? null,
+		requestedModel: snapshot.requestedModel ?? null,
+		modelFellBack: snapshot.modelFellBack ?? false,
+		// durationMs intentionally excluded (time-derived; would defeat idle gating).
+		progress: snapshot.progress ? canonicalizeProgressForSignature(snapshot.progress) : null,
+	};
+}
+
+function canonicalizeProgressForSignature(progress: AgentProgress): unknown {
+	return {
+		id: progress.id,
+		agent: progress.agent,
+		agentSource: progress.agentSource,
+		status: progress.status,
+		task: progress.task,
+		assignment: progress.assignment ?? null,
+		description: progress.description ?? null,
+		lastIntent: progress.lastIntent ?? null,
+		currentTool: progress.currentTool ?? null,
+		currentToolArgs: progress.currentToolArgs ?? null,
+		// currentToolStartMs intentionally excluded (only drives elapsed rendering).
+		recentTools: progress.recentTools.map(tool => ({ tool: tool.tool, args: tool.args })),
+		recentOutput: progress.recentOutput,
+		toolCount: progress.toolCount,
+		tokens: progress.tokens,
+		contextTokens: progress.contextTokens ?? null,
+		contextWindow: progress.contextWindow ?? null,
+		cost: progress.cost,
+		modelOverride: progress.modelOverride ?? null,
+		modelSubstitutionWarning: progress.modelSubstitutionWarning ?? null,
+		// durationMs intentionally excluded (time-derived).
+		extractedToolData: progress.extractedToolData
+			? canonicalizeExtractedToolDataForSignature(progress.extractedToolData)
+			: null,
+		retryState: progress.retryState
+			? {
+					attempt: progress.retryState.attempt,
+					maxAttempts: progress.retryState.maxAttempts,
+					unbounded: progress.retryState.unbounded ?? false,
+					delayMs: progress.retryState.delayMs,
+					errorMessage: progress.retryState.errorMessage,
+					// startedAtMs intentionally excluded (drives countdown only).
+				}
+			: null,
+		retryFailure: progress.retryFailure ?? null,
+		inflightTaskDetails: progress.inflightTaskDetails
+			? canonicalizeTaskDetailsForSignature(progress.inflightTaskDetails)
+			: null,
+	};
+}
+
+/**
+ * Nested `task` data (`extractedToolData.task` and `inflightTaskDetails`) is the
+ * one place the await signature reaches into a live, ticking structure: nested
+ * `AgentProgress` carries the same time-derived fields excluded above, and
+ * `TaskToolDetails` adds `totalDurationMs` / per-result `durationMs`. Signing it
+ * wholesale would defeat idle gating whenever an awaited subagent is itself inside
+ * a live `task` call, so these helpers canonicalize the rendered, non-time subset
+ * recursively (mutually recursive with `canonicalizeProgressForSignature`).
+ */
+function canonicalizeExtractedToolDataForSignature(data: Record<string, unknown[]>): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const key of Object.keys(data)) {
+		// Only the `task` key holds time-ticking `TaskToolDetails`; other handler
+		// data (yield/report_finding/generic) is stable and passes through as-is.
+		out[key] = key === "task" ? (data[key] as TaskToolDetails[]).map(canonicalizeTaskDetailsForSignature) : data[key];
+	}
+	return out;
+}
+
+function canonicalizeTaskDetailsForSignature(details: TaskToolDetails): unknown {
+	// `extractedToolData` is an untyped boundary (`Record<string, unknown[]>`), so
+	// guard each field instead of trusting the `TaskToolDetails` cast.
+	return {
+		// totalDurationMs intentionally excluded (time-derived).
+		results: Array.isArray(details.results) ? details.results.map(canonicalizeTaskResultForSignature) : null,
+		progress: Array.isArray(details.progress) ? details.progress.map(canonicalizeProgressForSignature) : null,
+		async: details.async
+			? { state: details.async.state, jobId: details.async.jobId, type: details.async.type }
+			: null,
+	};
+}
+
+function canonicalizeTaskResultForSignature(result: TaskToolDetails["results"][number]): unknown {
+	// Completed results do not tick, but drop `durationMs` so the only time-derived
+	// field in the receipt can never reintroduce idle churn.
+	const { durationMs: _durationMs, ...rest } = result;
+	return rest;
+}

package/src/tools/ultragoal-ask-guard.ts

@@ -0,0 +1,39 @@
+import type { AgentTool } from "@gajae-code/agent-core";
+import { isUltragoalAskBlocked, type UltragoalAskBlockDiagnostic } from "../gjc-runtime/ultragoal-guard";
+import { ToolError } from "./tool-errors";
+
+const ULTRAGOAL_ASK_GUARD = Symbol.for("gajae-code.ultragoalAskGuard");
+
+type GuardedTool = AgentTool & { [ULTRAGOAL_ASK_GUARD]?: true };
+
+export function formatUltragoalAskBlockMessage(diagnostic: UltragoalAskBlockDiagnostic): string {
+	return [
+		diagnostic.message,
+		`Ultragoal ask guard blocked ask (source: ${diagnostic.source}; reason: ${diagnostic.reason}).`,
+		"Use `gjc ultragoal record-review-blockers` to record the blocker instead of asking the user.",
+	].join("\n");
+}
+
+export async function assertUltragoalAskAllowed(cwd: string): Promise<void> {
+	const diagnostic = await isUltragoalAskBlocked(cwd);
+	if (!diagnostic.active) return;
+	throw new ToolError(formatUltragoalAskBlockMessage(diagnostic));
+}
+
+export function guardToolForUltragoalAsk<T extends AgentTool>(tool: T, getCwd: () => string): T {
+	if (tool.name !== "ask") return tool;
+	const candidate = tool as GuardedTool;
+	if (candidate[ULTRAGOAL_ASK_GUARD]) return tool;
+	const wrapped = new Proxy(tool, {
+		get(target, prop, receiver) {
+			if (prop === ULTRAGOAL_ASK_GUARD) return true;
+			if (prop !== "execute") return Reflect.get(target, prop, receiver);
+			return async (...args: unknown[]): Promise<unknown> => {
+				await assertUltragoalAskAllowed(getCwd());
+				return Reflect.apply(target.execute, target, args);
+			};
+		},
+	}) as T & GuardedTool;
+	wrapped[ULTRAGOAL_ASK_GUARD] = true;
+	return wrapped as T;
+}

package/src/web/search/index.ts

@@ -8,7 +8,6 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { AuthStorage } from "@gajae-code/ai";
 import { prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { parseModelString } from "../../config/model-resolver";
 import type { CustomTool, CustomToolContext, RenderResultOptions } from "../../extensibility/custom-tools/types";
 import type { Theme } from "../../modes/theme/theme";
 import webSearchSystemPrompt from "../../prompts/system/web-search.md" with { type: "text" };
@@ -19,7 +18,7 @@ import { formatAge } from "../../tools/render-utils";
 import { throwIfAborted } from "../../tools/tool-errors";
 import { getSearchProviderLabel, resolveProviderChain, type SearchProvider } from "./provider";
 import { renderSearchCall, renderSearchResult, type SearchRenderDetails } from "./render";
-import type { SearchProviderId, SearchResponse } from "./types";
+import type { ActiveSearchModelContext, SearchProviderId, SearchResponse } from "./types";
 import { SearchProviderError } from "./types";
 
 /** Web search tool parameters schema */
@@ -116,21 +115,11 @@ function formatForLLM(response: SearchResponse): string {
 	return parts.join("\n");
 }
 
-/** Best-effort active model provider: prefer the resolved Model, fall back to parsing the model string. */
-function resolveActiveModelProvider(
-	modelProvider: string | undefined,
-	modelString: string | undefined,
-): string | undefined {
-	if (modelProvider) return modelProvider;
-	if (modelString) return parseModelString(modelString)?.provider;
-	return undefined;
-}
-
 interface ExecuteSearchOptions {
 	authStorage: AuthStorage;
 	sessionId?: string;
 	signal?: AbortSignal;
-	activeModelProvider?: string;
+	activeModelContext?: ActiveSearchModelContext;
 }
 
 /** Execute web search */
@@ -139,11 +128,17 @@ async function executeSearch(
 	params: SearchQueryParams,
 	options: ExecuteSearchOptions,
 ): Promise<{ content: Array<{ type: "text"; text: string }>; details: SearchRenderDetails }> {
-	const { authStorage, sessionId, signal, activeModelProvider } = options;
+	const { authStorage, sessionId, signal, activeModelContext } = options;
 	// Pass `params.provider` straight through: when omitted (the normal model-facing
 	// path) it is `undefined`, so `resolveProviderChain` applies the settings-configured
 	// preferred provider. Coalescing to "auto" here would silently bypass that preference.
-	const providers = await resolveProviderChain(authStorage, params.provider, activeModelProvider);
+	const providers = await resolveProviderChain({
+		authStorage,
+		sessionId,
+		signal,
+		preferredProvider: params.provider,
+		activeModelContext,
+	});
 
 	const failures: Array<{ provider: SearchProvider; error: unknown }> = [];
 	let lastProvider = providers[0];
@@ -161,6 +156,7 @@ async function executeSearch(
 				signal,
 				authStorage,
 				sessionId,
+				activeModelContext,
 			});
 
 			const text = formatForLLM(response);
@@ -210,14 +206,19 @@ async function executeSearch(
  */
 export async function runSearchQuery(
 	params: SearchQueryParams,
-	options: { authStorage?: AuthStorage; sessionId?: string; signal?: AbortSignal; activeModelProvider?: string } = {},
+	options: {
+		authStorage?: AuthStorage;
+		sessionId?: string;
+		signal?: AbortSignal;
+		activeModelContext?: ActiveSearchModelContext;
+	} = {},
 ): Promise<{ content: Array<{ type: "text"; text: string }>; details: SearchRenderDetails }> {
 	const authStorage = options.authStorage ?? (await discoverAuthStorage());
 	return executeSearch("cli-web-search", params, {
 		authStorage,
 		sessionId: options.sessionId,
 		signal: options.signal,
-		activeModelProvider: options.activeModelProvider,
+		activeModelContext: options.activeModelContext,
 	});
 }
 
@@ -251,11 +252,10 @@ export class WebSearchTool implements AgentTool<typeof webSearchSchema, SearchRe
 	): Promise<AgentToolResult<SearchRenderDetails>> {
 		const authStorage = this.#session.authStorage ?? (await discoverAuthStorage());
 		const sessionId = this.#session.getSessionId?.() ?? undefined;
-		const activeModelProvider = resolveActiveModelProvider(
-			this.#session.model?.provider,
-			this.#session.getActiveModelString?.(),
-		);
-		return executeSearch(_toolCallId, params, { authStorage, sessionId, signal, activeModelProvider });
+		const activeModelContext = this.#session.model
+			? this.#session.modelRegistry?.getActiveSearchModelContext(this.#session.model)
+			: undefined;
+		return executeSearch(_toolCallId, params, { authStorage, sessionId, signal, activeModelContext });
 	}
 }
 
@@ -279,7 +279,7 @@ export const webSearchCustomTool: CustomTool<typeof webSearchSchema, SearchRende
 			authStorage,
 			sessionId,
 			signal,
-			activeModelProvider: ctx.model?.provider,
+			activeModelContext: ctx.model ? ctx.modelRegistry?.getActiveSearchModelContext(ctx.model) : undefined,
 		});
 	},
 
@@ -296,6 +296,6 @@ export function getSearchTools(): CustomTool<any, any>[] {
 	return [webSearchCustomTool];
 }
 
-export { getSearchProvider, setPreferredSearchProvider } from "./provider";
+export { getSearchProvider, setPreferredSearchProvider, setSearchFallbackProviders } from "./provider";
 export type { SearchProviderId as SearchProvider, SearchResponse } from "./types";
-export { isSearchProviderPreference } from "./types";
+export { isConfigurableSearchProviderId, isSearchProviderPreference } from "./types";

package/src/web/search/provider.ts

@@ -10,7 +10,8 @@
 
 import type { AuthStorage } from "@gajae-code/ai";
 import type { SearchProvider } from "./providers/base";
-import type { SearchProviderId } from "./types";
+import type { ActiveSearchModelContext, SearchProviderId } from "./types";
+import { isConfigurableSearchProviderId } from "./types";
 
 export type { SearchParams } from "./providers/base";
 export { SearchProvider } from "./providers/base";
@@ -23,36 +24,16 @@ interface ProviderMeta {
 
 /** Lazy factories. Each `load()` dynamic-imports its provider module on first call. */
 const PROVIDER_META: Record<SearchProviderId, ProviderMeta> = {
-	exa: {
-		id: "exa",
-		label: "Exa",
-		load: async () => new (await import("./providers/exa")).ExaProvider(),
-	},
-	brave: {
-		id: "brave",
-		label: "Brave",
-		load: async () => new (await import("./providers/brave")).BraveProvider(),
-	},
-	jina: {
-		id: "jina",
-		label: "Jina",
-		load: async () => new (await import("./providers/jina")).JinaProvider(),
-	},
+	exa: { id: "exa", label: "Exa", load: async () => new (await import("./providers/exa")).ExaProvider() },
+	brave: { id: "brave", label: "Brave", load: async () => new (await import("./providers/brave")).BraveProvider() },
+	jina: { id: "jina", label: "Jina", load: async () => new (await import("./providers/jina")).JinaProvider() },
 	perplexity: {
 		id: "perplexity",
 		label: "Perplexity",
 		load: async () => new (await import("./providers/perplexity")).PerplexityProvider(),
 	},
-	kimi: {
-		id: "kimi",
-		label: "Kimi",
-		load: async () => new (await import("./providers/kimi")).KimiProvider(),
-	},
-	zai: {
-		id: "zai",
-		label: "Z.AI",
-		load: async () => new (await import("./providers/zai")).ZaiProvider(),
-	},
+	kimi: { id: "kimi", label: "Kimi", load: async () => new (await import("./providers/kimi")).KimiProvider() },
+	zai: { id: "zai", label: "Z.AI", load: async () => new (await import("./providers/zai")).ZaiProvider() },
 	anthropic: {
 		id: "anthropic",
 		label: "Anthropic",
@@ -63,11 +44,7 @@ const PROVIDER_META: Record<SearchProviderId, ProviderMeta> = {
 		label: "Gemini",
 		load: async () => new (await import("./providers/gemini")).GeminiProvider(),
 	},
-	codex: {
-		id: "codex",
-		label: "OpenAI",
-		load: async () => new (await import("./providers/codex")).CodexProvider(),
-	},
+	codex: { id: "codex", label: "OpenAI", load: async () => new (await import("./providers/codex")).CodexProvider() },
 	tavily: {
 		id: "tavily",
 		label: "Tavily",
@@ -78,11 +55,7 @@ const PROVIDER_META: Record<SearchProviderId, ProviderMeta> = {
 		label: "Parallel",
 		load: async () => new (await import("./providers/parallel")).ParallelProvider(),
 	},
-	kagi: {
-		id: "kagi",
-		label: "Kagi",
-		load: async () => new (await import("./providers/kagi")).KagiProvider(),
-	},
+	kagi: { id: "kagi", label: "Kagi", load: async () => new (await import("./providers/kagi")).KagiProvider() },
 	synthetic: {
 		id: "synthetic",
 		label: "Synthetic",
@@ -98,26 +71,24 @@ const PROVIDER_META: Record<SearchProviderId, ProviderMeta> = {
 		label: "DuckDuckGo",
 		load: async () => new (await import("./providers/duckduckgo")).DuckDuckGoProvider(),
 	},
+	"openai-compatible": {
+		id: "openai-compatible",
+		label: "OpenAI-compatible",
+		load: async () => new (await import("./providers/openai-compatible")).OpenAICompatibleSearchProvider(),
+	},
 };
 
 const instanceCache = new Map<SearchProviderId, SearchProvider>();
 
-/** Cheap, sync metadata accessor — never triggers a provider load. */
 export function getSearchProviderLabel(id: SearchProviderId): string {
 	return PROVIDER_META[id]?.label ?? id;
 }
 
-/**
- * Resolve and cache a provider instance. First call for a given id loads the
- * underlying module; subsequent calls return the cached singleton.
- */
 export async function getSearchProvider(id: SearchProviderId): Promise<SearchProvider> {
 	const cached = instanceCache.get(id);
 	if (cached) return cached;
 	const meta = PROVIDER_META[id];
-	if (!meta) {
-		throw new Error(`Unknown search provider: ${id}`);
-	}
+	if (!meta) throw new Error(`Unknown search provider: ${id}`);
 	const provider = await meta.load();
 	instanceCache.set(id, provider);
 	return provider;
@@ -141,13 +112,6 @@ export const SEARCH_PROVIDER_ORDER: SearchProviderId[] = [
 	"searxng",
 ];
 
-/**
- * Map an active model's provider string to its own native web-search provider.
- * Keys are real model provider ids (see packages/ai/src/types.ts KnownProvider);
- * a few aliases (gemini/kimi) and API strings (openai-responses) are tolerated
- * defensively. Providers absent from this map (custom/unknown) fall through to
- * DuckDuckGo.
- */
 const MODEL_PROVIDER_TO_SEARCH: Record<string, SearchProviderId> = {
 	openai: "codex",
 	"openai-codex": "codex",
@@ -165,54 +129,181 @@ const MODEL_PROVIDER_TO_SEARCH: Record<string, SearchProviderId> = {
 	synthetic: "synthetic",
 };
 
-/** Preferred provider set via settings (default: auto) */
 let preferredProvId: SearchProviderId | "auto" = "auto";
+let fallbackProvIds: SearchProviderId[] = [];
 
-/** Set the preferred web search provider from settings */
 export function setPreferredSearchProvider(provider: SearchProviderId | "auto"): void {
 	preferredProvId = provider;
 }
 
-/**
- * Resolve the ordered provider chain for a search request.
- *
- * Resolution is active-model-gated, never credential-scanning:
- *   1. An explicitly preferred provider (settings) that is available is primary.
- *   2. Otherwise the active model's own native search is primary, but only when
- *      that provider's own credentials are present (its `isAvailable()`).
- *   3. DuckDuckGo (keyless) is always appended as the terminal fallback, so a
- *      missing primary — or a primary runtime failure — still returns results
- *      with zero configuration. Keyed standalone providers are never
- *      auto-selected; they are reachable only via explicit selection (step 1).
- */
-export async function resolveProviderChain(
+export function setSearchFallbackProviders(ids: readonly string[]): void {
+	fallbackProvIds = ids.filter(isConfigurableSearchProviderId);
+}
+
+export interface ResolveProviderChainOptions {
+	authStorage: AuthStorage;
+	sessionId?: string;
+	signal?: AbortSignal;
+	preferredProvider?: SearchProviderId | "auto";
+	activeModelContext?: ActiveSearchModelContext;
+	fallbackProviders?: readonly SearchProviderId[];
+}
+
+async function appendAvailable(
+	chain: SearchProviderId[],
+	id: SearchProviderId,
+	authStorage: AuthStorage,
+): Promise<void> {
+	if (chain.includes(id)) return;
+	const provider = await getSearchProvider(id);
+	if (await provider.isAvailable(authStorage)) chain.push(id);
+}
+
+function appendDeduped(chain: SearchProviderId[], id: SearchProviderId): void {
+	if (!chain.includes(id)) chain.push(id);
+}
+
+function isAnthropicWire(api: string): boolean {
+	return api === "anthropic-messages";
+}
+
+function isGoogleWire(api: string): boolean {
+	return api === "google-generative-ai" || api === "google-vertex" || api === "google-gemini-cli";
+}
+
+function isOpenAICompatWire(api: string): boolean {
+	return api === "openai-responses" || api === "openai-completions" || api === "azure-openai-responses";
+}
+
+export function looksHostedModelId(modelId: string | undefined): boolean {
+	if (!modelId) return false;
+	const id = modelId.toLowerCase();
+	return /^(gpt-|o\d|o-|chatgpt-|text-|davinci|babbage|curie)/.test(id);
+}
+
+function looksOpenAIFamilyModelId(ctx: ActiveSearchModelContext): boolean {
+	return looksHostedModelId(ctx.wireModelId) || looksHostedModelId(ctx.modelId);
+}
+
+export function isLocalBaseUrl(baseUrl: string | undefined): boolean {
+	if (!baseUrl) return false;
+	let url: URL;
+	try {
+		url = new URL(baseUrl);
+	} catch {
+		return true;
+	}
+	const host = url.hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "").replace(/\.$/, "");
+	if (
+		host === "localhost" ||
+		host.endsWith(".localhost") ||
+		host === "host.docker.internal" ||
+		host.endsWith(".local")
+	)
+		return true;
+	const v4 = host.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+	if (v4) {
+		const [a, b] = v4.slice(1, 3).map(Number);
+		if (
+			a === 127 ||
+			a === 0 ||
+			a === 10 ||
+			(a === 172 && b >= 16 && b <= 31) ||
+			(a === 192 && b === 168) ||
+			(a === 169 && b === 254)
+		)
+			return true;
+	}
+	if (host === "::1" || host === "::") return true;
+	if (host.startsWith("fc") || host.startsWith("fd")) return true;
+	if (host.startsWith("fe8") || host.startsWith("fe9") || host.startsWith("fea") || host.startsWith("feb"))
+		return true;
+	return false;
+}
+
+export function inferNativeProviderFromModel(ctx: ActiveSearchModelContext | undefined): SearchProviderId | undefined {
+	if (!ctx || ctx.webSearch === "off") return undefined;
+	const modelId = (ctx.wireModelId ?? ctx.modelId).toLowerCase();
+	if (modelId.startsWith("claude-") && isAnthropicWire(ctx.api)) return "anthropic";
+	if (modelId.startsWith("gemini-") && isGoogleWire(ctx.api)) return "gemini";
+	if (looksOpenAIFamilyModelId(ctx) && isOpenAICompatWire(ctx.api)) {
+		if (ctx.webSearch === "on" || !isLocalBaseUrl(ctx.baseUrl)) return "codex";
+	}
+	return undefined;
+}
+
+function canUseDirectProviderMapping(ctx: ActiveSearchModelContext, id: SearchProviderId): boolean {
+	if (ctx.webSearch === "off") return false;
+	if (id !== "codex") return true;
+	if (!isOpenAICompatWire(ctx.api)) return true;
+	return ctx.webSearch === "on" || !isLocalBaseUrl(ctx.baseUrl);
+}
+
+export async function canUseGenericCredentials(
 	authStorage: AuthStorage,
-	preferredProvider: SearchProviderId | "auto" = preferredProvId,
-	activeModelProvider?: string,
-): Promise<SearchProvider[]> {
+	ctx: ActiveSearchModelContext | undefined,
+	sessionId?: string,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	if (!ctx) return false;
+	const key = await authStorage.getApiKey(ctx.provider, sessionId, {
+		baseUrl: ctx.baseUrl,
+		modelId: ctx.modelId,
+		signal,
+	});
+	return Boolean(key);
+}
+
+export async function shouldTryGenericOpenAICompat(
+	authStorage: AuthStorage,
+	ctx: ActiveSearchModelContext | undefined,
+	sessionId?: string,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	if (!ctx || ctx.webSearch === "off" || !isOpenAICompatWire(ctx.api)) return false;
+	const autoAllowed =
+		ctx.webSearch === "on" ||
+		((ctx.api === "openai-responses" || looksOpenAIFamilyModelId(ctx)) && !isLocalBaseUrl(ctx.baseUrl));
+	return autoAllowed && (await canUseGenericCredentials(authStorage, ctx, sessionId, signal));
+}
+
+export async function resolveProviderChain(options: ResolveProviderChainOptions): Promise<SearchProvider[]> {
+	const {
+		authStorage,
+		sessionId,
+		signal,
+		preferredProvider = preferredProvId,
+		activeModelContext,
+		fallbackProviders = fallbackProvIds,
+	} = options;
 	const chain: SearchProviderId[] = [];
 
-	if (preferredProvider !== "auto") {
-		const provider = await getSearchProvider(preferredProvider);
-		if (await provider.isAvailable(authStorage)) {
-			chain.push(preferredProvider);
-		}
-	} else if (activeModelProvider) {
-		const nativeId = MODEL_PROVIDER_TO_SEARCH[activeModelProvider.toLowerCase()];
-		if (nativeId) {
-			const provider = await getSearchProvider(nativeId);
-			if (await provider.isAvailable(authStorage)) {
-				chain.push(nativeId);
-			}
-		}
+	// A forced primary is honored only when it is a user-configurable provider.
+	// The internal `openai-compatible` adapter (and any non-configurable value) is
+	// never selectable as a forced primary; such inputs fall through to auto
+	// native resolution instead of being injected into the chain.
+	if (preferredProvider !== "auto" && isConfigurableSearchProviderId(preferredProvider)) {
+		await appendAvailable(chain, preferredProvider, authStorage);
+	} else if (activeModelContext) {
+		const directId = MODEL_PROVIDER_TO_SEARCH[activeModelContext.provider.toLowerCase()];
+		if (directId && canUseDirectProviderMapping(activeModelContext, directId))
+			await appendAvailable(chain, directId, authStorage);
+		const inferred = inferNativeProviderFromModel(activeModelContext);
+		if (inferred) await appendAvailable(chain, inferred, authStorage);
+		if (await shouldTryGenericOpenAICompat(authStorage, activeModelContext, sessionId, signal))
+			appendDeduped(chain, "openai-compatible");
 	}
 
-	// DuckDuckGo is the permissionless terminal fallback (deduped).
-	if (!chain.includes("duckduckgo")) chain.push("duckduckgo");
+	// Configured fallbacks are user-facing only: the internal `openai-compatible`
+	// adapter (and any non-configurable id) can never enter the chain through the
+	// fallback list, regardless of how `fallbackProviders` was supplied.
+	for (const id of fallbackProviders) {
+		if (!isConfigurableSearchProviderId(id)) continue;
+		await appendAvailable(chain, id, authStorage);
+	}
+	appendDeduped(chain, "duckduckgo");
 
 	const providers: SearchProvider[] = [];
-	for (const id of chain) {
-		providers.push(await getSearchProvider(id));
-	}
+	for (const id of chain) providers.push(await getSearchProvider(id));
 	return providers;
 }