@gajae-code/coding-agent 0.5.0 → 0.5.2

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;
 }

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

@@ -1,5 +1,5 @@
 import type { AuthStorage } from "@gajae-code/ai";
-import type { SearchProviderId, SearchResponse } from "../types";
+import type { ActiveSearchModelContext, SearchProviderId, SearchResponse } from "../types";
 
 /**
  * Shared web search parameters passed to providers.
@@ -50,6 +50,7 @@ export interface SearchParams {
 	 * caller's agent session when available; otherwise omit.
 	 */
 	sessionId?: string;
+	activeModelContext?: ActiveSearchModelContext;
 }
 
 /** Base class for web search providers. */

package/src/web/search/providers/openai-compatible.ts

@@ -0,0 +1,151 @@
+import type { SearchCitation, SearchResponse, SearchSource } from "../types";
+import { SearchProviderError } from "../types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+import { classifyProviderHttpError, withHardTimeout } from "./utils";
+
+function endpoint(baseUrl: string, api: string): string {
+	const base = baseUrl.replace(/\/+$/, "");
+	return api === "openai-completions" ? `${base}/chat/completions` : `${base}/responses`;
+}
+
+function textFromResponse(json: any): string | undefined {
+	if (typeof json.output_text === "string") return json.output_text;
+	const chunks: string[] = [];
+	for (const item of json.output ?? []) {
+		for (const content of item.content ?? []) {
+			if (typeof content.text === "string") chunks.push(content.text);
+		}
+	}
+	const chat = json.choices?.[0]?.message?.content;
+	if (typeof chat === "string") chunks.push(chat);
+	return chunks.join("\n") || undefined;
+}
+
+function pushCitation(out: SearchCitation[], rawUrl: unknown, rawTitle: unknown, rawText: unknown): void {
+	if (typeof rawUrl !== "string" || !rawUrl) return;
+	out.push({
+		url: rawUrl,
+		title: typeof rawTitle === "string" && rawTitle ? rawTitle : rawUrl,
+		citedText: typeof rawText === "string" ? rawText : undefined,
+	});
+}
+
+// Only recognized grounding annotations count as citations. An OpenAI-compatible
+// endpoint that ignores the web_search request returns a normal answer with no
+// `url_citation` annotations; treating arbitrary URL/`type:"source"` metadata as a
+// citation would mask that non-search answer as a real search result. Restrict
+// extraction to the documented annotation shapes (Responses
+// `output[].content[].annotations[]` and Chat `choices[].message.annotations[]`),
+// accepting only `type: "url_citation"` entries.
+function collectCitationAnnotations(annotations: unknown, out: SearchCitation[]): void {
+	if (!Array.isArray(annotations)) return;
+	for (const annotation of annotations) {
+		if (!annotation || typeof annotation !== "object") continue;
+		const ann = annotation as Record<string, any>;
+		if (ann.type !== "url_citation") continue;
+		const cite =
+			ann.url_citation && typeof ann.url_citation === "object" ? (ann.url_citation as Record<string, any>) : ann;
+		pushCitation(out, cite.url ?? cite.uri, cite.title, cite.text ?? cite.quote ?? ann.text);
+	}
+}
+
+function parseCitations(json: any): SearchCitation[] {
+	const citations: SearchCitation[] = [];
+	for (const item of json?.output ?? []) {
+		for (const content of item?.content ?? []) {
+			collectCitationAnnotations(content?.annotations, citations);
+		}
+	}
+	for (const choice of json?.choices ?? []) {
+		collectCitationAnnotations(choice?.message?.annotations, citations);
+	}
+	const seen = new Set<string>();
+	return citations.filter(c => {
+		if (seen.has(c.url)) return false;
+		seen.add(c.url);
+		return true;
+	});
+}
+
+function toSources(citations: SearchCitation[], limit: number): SearchSource[] {
+	return citations.slice(0, limit).map(c => ({ title: c.title || c.url, url: c.url, snippet: c.citedText }));
+}
+
+export class OpenAICompatibleSearchProvider extends SearchProvider {
+	readonly id = "openai-compatible" as const;
+	readonly label = "OpenAI-compatible";
+
+	isAvailable(): boolean {
+		return true;
+	}
+
+	async search(params: SearchParams): Promise<SearchResponse> {
+		const ctx = params.activeModelContext;
+		if (!ctx)
+			throw new SearchProviderError(this.id, "OpenAI-compatible web search requires active model context", 400);
+		if (ctx.api !== "openai-responses" && ctx.api !== "openai-completions") {
+			throw new SearchProviderError(this.id, `OpenAI-compatible web search does not support ${ctx.api}`, 400);
+		}
+		const apiKey = await params.authStorage.getApiKey(ctx.provider, params.sessionId, {
+			baseUrl: ctx.baseUrl,
+			modelId: ctx.modelId,
+			signal: params.signal,
+		});
+		if (!apiKey) throw new SearchProviderError(this.id, `No credentials for ${ctx.provider}`, 401);
+		const model = ctx.wireModelId ?? ctx.modelId;
+		const headers = { ...(ctx.headers ?? {}), Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" };
+		const body =
+			ctx.api === "openai-completions"
+				? {
+						model,
+						messages: [
+							{ role: "system", content: params.systemPrompt },
+							{ role: "user", content: params.query },
+						],
+						web_search_options: {},
+						temperature: params.temperature,
+						max_tokens: params.maxOutputTokens,
+					}
+				: {
+						model,
+						input: [
+							{ role: "system", content: params.systemPrompt },
+							{ role: "user", content: params.query },
+						],
+						tools: [{ type: "web_search" }],
+						temperature: params.temperature,
+						max_output_tokens: params.maxOutputTokens,
+					};
+		const response = await fetch(endpoint(ctx.baseUrl ?? "", ctx.api), {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+			signal: withHardTimeout(params.signal),
+		});
+		const text = await response.text();
+		if (!response.ok) {
+			const classified = classifyProviderHttpError(this.id, response.status, text);
+			if (classified) throw classified;
+			throw new SearchProviderError(
+				this.id,
+				`OpenAI-compatible web search error (${response.status}): ${text}`,
+				response.status,
+			);
+		}
+		const json = text ? JSON.parse(text) : {};
+		const citations = parseCitations(json);
+		if (citations.length === 0) {
+			throw new SearchProviderError(this.id, "OpenAI-compatible web search returned no citations", 424);
+		}
+		return {
+			provider: this.id,
+			answer: textFromResponse(json),
+			sources: toSources(citations, params.limit ?? params.numSearchResults ?? 10),
+			citations,
+			model,
+			requestId: json.id,
+			authMode: "api-key",
+		};
+	}
+}

package/src/web/search/types.ts

@@ -20,30 +20,55 @@ export type SearchProviderId =
 	| "parallel"
 	| "kagi"
 	| "synthetic"
-	| "searxng";
+	| "searxng"
+	| "openai-compatible";
+
+export type WebSearchMode = "on" | "off" | "auto";
+
+export interface ActiveSearchModelContext {
+	provider: string;
+	modelId: string;
+	wireModelId?: string;
+	api: string;
+	baseUrl?: string;
+	headers?: Record<string, string>;
+	webSearch?: WebSearchMode;
+}
+
+export const CONFIGURABLE_SEARCH_PROVIDER_IDS = [
+	"duckduckgo",
+	"exa",
+	"brave",
+	"jina",
+	"kimi",
+	"zai",
+	"anthropic",
+	"perplexity",
+	"gemini",
+	"codex",
+	"tavily",
+	"parallel",
+	"kagi",
+	"synthetic",
+	"searxng",
+] as const satisfies readonly SearchProviderId[];
+
+const SEARCH_PROVIDER_IDS = [...CONFIGURABLE_SEARCH_PROVIDER_IDS, "openai-compatible"] as const;
 
 export function isSearchProviderId(value: string): value is SearchProviderId {
-	return [
-		"duckduckgo",
-		"exa",
-		"brave",
-		"jina",
-		"kimi",
-		"zai",
-		"anthropic",
-		"perplexity",
-		"gemini",
-		"codex",
-		"tavily",
-		"parallel",
-		"kagi",
-		"synthetic",
-		"searxng",
-	].includes(value);
-}
-
-export function isSearchProviderPreference(value: string): value is SearchProviderId | "auto" {
-	return value === "auto" || isSearchProviderId(value);
+	return (SEARCH_PROVIDER_IDS as readonly string[]).includes(value);
+}
+
+export function isConfigurableSearchProviderId(
+	value: string,
+): value is (typeof CONFIGURABLE_SEARCH_PROVIDER_IDS)[number] {
+	return (CONFIGURABLE_SEARCH_PROVIDER_IDS as readonly string[]).includes(value);
+}
+
+export function isSearchProviderPreference(
+	value: string,
+): value is (typeof CONFIGURABLE_SEARCH_PROVIDER_IDS)[number] | "auto" {
+	return value === "auto" || isConfigurableSearchProviderId(value);
 }
 
 /** Source returned by search (all providers) */