@nghyane/arcane 0.1.15 → 0.1.17

package/src/web/search/provider.ts

@@ -5,6 +5,7 @@ import { CodexProvider } from "./providers/codex";
 import { ExaProvider } from "./providers/exa";
 import { GeminiProvider } from "./providers/gemini";
 import { JinaProvider } from "./providers/jina";
+import { KagiProvider } from "./providers/kagi";
 import { KimiProvider } from "./providers/kimi";
 import { PerplexityProvider } from "./providers/perplexity";
 import { SyntheticProvider } from "./providers/synthetic";
@@ -18,6 +19,7 @@ const SEARCH_PROVIDERS: Record<SearchProviderId, SearchProvider> = {
 	exa: new ExaProvider(),
 	brave: new BraveProvider(),
 	jina: new JinaProvider(),
+	kagi: new KagiProvider(),
 	perplexity: new PerplexityProvider(),
 	kimi: new KimiProvider(),
 	zai: new ZaiProvider(),
@@ -32,6 +34,7 @@ export const SEARCH_PROVIDER_ORDER: SearchProviderId[] = [
 	"exa",
 	"brave",
 	"jina",
+	"kagi",
 	"kimi",
 	"anthropic",
 	"gemini",

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

@@ -65,6 +65,7 @@ function buildSystemBlocks(
 	return buildAnthropicSystemBlocks(systemPrompt, {
 		includeClaudeCodeInstruction: includeClaudeCode,
 		extraInstructions,
+		cacheControl: { type: "ephemeral" },
 	});
 }
 

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

@@ -5,7 +5,13 @@
  * Requires OAuth credentials stored in agent.db for provider "google-gemini-cli" or "google-antigravity".
  * Returns synthesized answers with citations and source metadata from grounding chunks.
  */
-import { getAntigravityHeaders, getGeminiCliHeaders, refreshGoogleCloudToken } from "@nghyane/arcane-ai";
+import {
+	ANTIGRAVITY_SYSTEM_INSTRUCTION,
+	extractRetryDelay,
+	getAntigravityHeaders,
+	getGeminiCliHeaders,
+	refreshGoogleCloudToken,
+} from "@nghyane/arcane-ai";
 import { getAgentDbPath } from "@nghyane/arcane-utils/dirs";
 import { AgentStorage } from "../../../session/agent-storage";
 import type { SearchCitation, SearchResponse, SearchSource } from "../../../web/search/types";
@@ -14,10 +20,32 @@ import type { SearchParams } from "./base";
 import { SearchProvider } from "./base";
 
 const DEFAULT_ENDPOINT = "https://cloudcode-pa.googleapis.com";
-const ANTIGRAVITY_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
+const ANTIGRAVITY_DAILY_ENDPOINT = "https://daily-cloudcode-pa.googleapis.com";
+const ANTIGRAVITY_SANDBOX_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
+const ANTIGRAVITY_ENDPOINT_FALLBACKS = [ANTIGRAVITY_DAILY_ENDPOINT, ANTIGRAVITY_SANDBOX_ENDPOINT] as const;
 const DEFAULT_MODEL = "gemini-2.5-flash";
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+const RATE_LIMIT_BUDGET_MS = 5 * 60 * 1000;
+
+interface GeminiToolParams {
+	google_search?: Record<string, unknown>;
+	code_execution?: Record<string, unknown>;
+	url_context?: Record<string, unknown>;
+}
 
-export interface GeminiSearchParams {
+export function buildGeminiRequestTools(params: GeminiToolParams): Array<Record<string, Record<string, unknown>>> {
+	const tools: Array<Record<string, Record<string, unknown>>> = [{ googleSearch: params.google_search ?? {} }];
+	if (params.code_execution !== undefined) {
+		tools.push({ codeExecution: params.code_execution });
+	}
+	if (params.url_context !== undefined) {
+		tools.push({ urlContext: params.url_context });
+	}
+	return tools;
+}
+
+export interface GeminiSearchParams extends GeminiToolParams {
 	query: string;
 	system_prompt?: string;
 	num_results?: number;
@@ -55,8 +83,8 @@ export async function findGeminiAuth(): Promise<GeminiAuth | null> {
 	const expiryBuffer = 5 * 60 * 1000; // 5 minutes
 	const now = Date.now();
 
-	// Try providers in order: antigravity first (more quota), then gemini-cli
-	const providers = ["google-antigravity", "google-gemini-cli"] as const;
+	// Try providers in order: gemini-cli first (deterministic), then antigravity
+	const providers = ["google-gemini-cli", "google-antigravity"] as const;
 
 	try {
 		const storage = await AgentStorage.open(getAgentDbPath());
@@ -180,6 +208,7 @@ async function callGeminiSearch(
 	systemPrompt?: string,
 	maxOutputTokens?: number,
 	temperature?: number,
+	toolParams: GeminiToolParams = {},
 ): Promise<{
 	answer: string;
 	sources: SearchSource[];
@@ -188,10 +217,20 @@ async function callGeminiSearch(
 	model: string;
 	usage?: { inputTokens: number; outputTokens: number; totalTokens: number };
 }> {
-	const endpoint = auth.isAntigravity ? ANTIGRAVITY_ENDPOINT : DEFAULT_ENDPOINT;
-	const url = `${endpoint}/v1internal:streamGenerateContent?alt=sse`;
+	const endpoints = auth.isAntigravity ? ANTIGRAVITY_ENDPOINT_FALLBACKS : [DEFAULT_ENDPOINT];
 	const headers = auth.isAntigravity ? getAntigravityHeaders() : getGeminiCliHeaders();
 
+	const normalizedSystemPrompt = systemPrompt?.toWellFormed();
+	const systemInstructionParts: Array<{ text: string }> = [
+		...(auth.isAntigravity
+			? [
+					{ text: ANTIGRAVITY_SYSTEM_INSTRUCTION },
+					{ text: `Please ignore following [ignore]${ANTIGRAVITY_SYSTEM_INSTRUCTION}[/ignore]` },
+				]
+			: []),
+		...(normalizedSystemPrompt ? [{ text: normalizedSystemPrompt }] : []),
+	];
+
 	const requestBody: Record<string, unknown> = {
 		project: auth.projectId,
 		model: DEFAULT_MODEL,
@@ -202,11 +241,11 @@ async function callGeminiSearch(
 					parts: [{ text: query }],
 				},
 			],
-			// Add googleSearch tool for grounding
-			tools: [{ googleSearch: {} }],
-			...(systemPrompt && {
+			tools: buildGeminiRequestTools(toolParams),
+			...(systemInstructionParts.length > 0 && {
 				systemInstruction: {
-					parts: [{ text: systemPrompt }],
+					...(auth.isAntigravity ? { role: "user" } : {}),
+					parts: systemInstructionParts,
 				},
 			}),
 		},
@@ -225,31 +264,83 @@ async function callGeminiSearch(
 		(requestBody.request as Record<string, unknown>).generationConfig = generationConfig;
 	}
 
-	const response = await fetch(url, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${auth.accessToken}`,
-			"Content-Type": "application/json",
-			Accept: "text/event-stream",
-			...headers,
-		},
-		body: JSON.stringify(requestBody),
-	});
-
-	if (!response.ok) {
-		const errorText = await response.text();
-		throw new SearchProviderError(
-			"gemini",
-			`Gemini Cloud Code API error (${response.status}): ${errorText}`,
-			response.status,
-		);
+	// Retry loop with endpoint fallback and rate limit budgeting
+	let lastError: Error | undefined;
+	let totalDelayMs = 0;
+
+	for (const endpoint of endpoints) {
+		const url = `${endpoint}/v1internal:streamGenerateContent?alt=sse`;
+
+		for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+			try {
+				const response = await fetch(url, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${auth.accessToken}`,
+						"Content-Type": "application/json",
+						Accept: "text/event-stream",
+						...headers,
+					},
+					body: JSON.stringify(requestBody),
+				});
+
+				if (response.ok) {
+					return await parseGeminiSSEResponse(response);
+				}
+
+				const errorText = await response.text();
+
+				// Non-retryable status codes
+				if (response.status >= 400 && response.status < 429) {
+					throw new SearchProviderError(
+						"gemini",
+						`Gemini Cloud Code API error (${response.status}): ${errorText}`,
+						response.status,
+					);
+				}
+
+				// Rate limit or server error — retry with backoff
+				const serverDelay = extractRetryDelay(errorText, response);
+				const delay = serverDelay ?? BASE_DELAY_MS * 2 ** attempt;
+				totalDelayMs += delay;
+
+				if (totalDelayMs > RATE_LIMIT_BUDGET_MS) {
+					throw new SearchProviderError(
+						"gemini",
+						`Rate limit budget exhausted after ${Math.round(totalDelayMs / 1000)}s of delays`,
+						429,
+					);
+				}
+
+				lastError = new SearchProviderError(
+					"gemini",
+					`Gemini Cloud Code API error (${response.status}): ${errorText}`,
+					response.status,
+				);
+				await Bun.sleep(delay);
+			} catch (err) {
+				if (err instanceof SearchProviderError) throw err;
+				lastError = err as Error;
+				break; // Network error — try next endpoint
+			}
+		}
 	}
 
+	throw lastError ?? new SearchProviderError("gemini", "All Gemini endpoints failed", 500);
+}
+
+async function parseGeminiSSEResponse(response: Response): Promise<{
+	answer: string;
+	sources: SearchSource[];
+	citations: SearchCitation[];
+	searchQueries: string[];
+	model: string;
+	usage?: { inputTokens: number; outputTokens: number; totalTokens: number };
+}> {
 	if (!response.body) {
 		throw new SearchProviderError("gemini", "Gemini API returned no response body", 500);
 	}
 
-	// Parse SSE stream
 	const answerParts: string[] = [];
 	const sources: SearchSource[] = [];
 	const citations: SearchCitation[] = [];
@@ -289,7 +380,6 @@ async function callGeminiSearch(
 
 				const candidate = responseData.candidates?.[0];
 
-				// Extract text content
 				if (candidate?.content?.parts) {
 					for (const part of candidate.content.parts) {
 						if (part.text) {
@@ -298,10 +388,8 @@ async function callGeminiSearch(
 					}
 				}
 
-				// Extract grounding metadata
 				const groundingMetadata = candidate?.groundingMetadata;
 				if (groundingMetadata) {
-					// Extract sources from grounding chunks
 					if (groundingMetadata.groundingChunks) {
 						for (const grChunk of groundingMetadata.groundingChunks) {
 							if (grChunk.web?.uri) {
@@ -317,7 +405,6 @@ async function callGeminiSearch(
 						}
 					}
 
-					// Extract citations from grounding supports
 					if (groundingMetadata.groundingSupports && groundingMetadata.groundingChunks) {
 						for (const support of groundingMetadata.groundingSupports) {
 							const citedText = support.segment?.text;
@@ -336,7 +423,6 @@ async function callGeminiSearch(
 						}
 					}
 
-					// Extract search queries
 					if (groundingMetadata.webSearchQueries) {
 						for (const q of groundingMetadata.webSearchQueries) {
 							if (!searchQueries.includes(q)) {
@@ -346,7 +432,6 @@ async function callGeminiSearch(
 					}
 				}
 
-				// Extract usage metadata
 				if (responseData.usageMetadata) {
 					usage = {
 						inputTokens: responseData.usageMetadata.promptTokenCount ?? 0,
@@ -355,7 +440,6 @@ async function callGeminiSearch(
 					};
 				}
 
-				// Extract model version
 				if (responseData.modelVersion) {
 					model = responseData.modelVersion;
 				}
@@ -396,6 +480,7 @@ export async function searchGemini(params: GeminiSearchParams): Promise<SearchRe
 		params.system_prompt,
 		params.max_output_tokens,
 		params.temperature,
+		params,
 	);
 
 	let sources = result.sources;

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

@@ -0,0 +1,163 @@
+/**
+ * Kagi Web Search Provider
+ *
+ * Calls Kagi's Search API (v0) and maps results into the unified
+ * SearchResponse shape used by the web search tool.
+ */
+import { getEnvApiKey } from "@nghyane/arcane-ai";
+import type { SearchResponse, SearchSource } from "../types";
+import { SearchProviderError } from "../types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+
+const KAGI_SEARCH_URL = "https://kagi.com/api/v0/search";
+const DEFAULT_NUM_RESULTS = 10;
+const MAX_NUM_RESULTS = 40;
+
+interface KagiSearchResult {
+	t: 0;
+	url: string;
+	title: string;
+	snippet?: string;
+	published?: string;
+	thumbnail?: {
+		url: string;
+		width?: number | null;
+		height?: number | null;
+	};
+}
+
+interface KagiRelatedSearches {
+	t: 1;
+	list: string[];
+}
+
+type KagiSearchObject = KagiSearchResult | KagiRelatedSearches;
+
+interface KagiMeta {
+	id: string;
+	node: string;
+	ms: number;
+	api_balance?: number;
+}
+
+interface KagiSearchResponse {
+	meta: KagiMeta;
+	data: KagiSearchObject[];
+	error?: Array<{ code: number; msg: string; ref?: unknown }>;
+}
+
+function clampNumResults(value: number | undefined): number {
+	if (!value || Number.isNaN(value)) return DEFAULT_NUM_RESULTS;
+	return Math.min(MAX_NUM_RESULTS, Math.max(1, value));
+}
+
+function dateToAgeSeconds(dateStr: string | null | undefined): number | undefined {
+	if (!dateStr) return undefined;
+	try {
+		const date = new Date(dateStr);
+		if (Number.isNaN(date.getTime())) return undefined;
+		return Math.floor((Date.now() - date.getTime()) / 1000);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Find KAGI_API_KEY from environment or .env files. */
+export function findApiKey(): string | null {
+	return getEnvApiKey("kagi") ?? null;
+}
+
+async function callKagiSearch(
+	apiKey: string,
+	query: string,
+	limit: number,
+	signal?: AbortSignal,
+): Promise<KagiSearchResponse> {
+	const url = new URL(KAGI_SEARCH_URL);
+	url.searchParams.set("q", query);
+	url.searchParams.set("limit", String(limit));
+
+	const response = await fetch(url, {
+		headers: {
+			Authorization: `Bot ${apiKey}`,
+			Accept: "application/json",
+		},
+		signal,
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new SearchProviderError("kagi", `Kagi API error (${response.status}): ${errorText}`, response.status);
+	}
+
+	const data = (await response.json()) as KagiSearchResponse;
+
+	if (data.error && data.error.length > 0) {
+		const firstError = data.error[0];
+		throw new SearchProviderError("kagi", `Kagi API error: ${firstError.msg}`, firstError.code);
+	}
+
+	return data;
+}
+
+/** Execute Kagi web search. */
+export async function searchKagi(params: {
+	query: string;
+	num_results?: number;
+	signal?: AbortSignal;
+}): Promise<SearchResponse> {
+	const numResults = clampNumResults(params.num_results);
+	const apiKey = findApiKey();
+	if (!apiKey) {
+		throw new Error("KAGI_API_KEY not found. Set it in environment or .env file.");
+	}
+
+	const data = await callKagiSearch(apiKey, params.query, numResults, params.signal);
+
+	const sources: SearchSource[] = [];
+	const relatedQuestions: string[] = [];
+
+	for (const item of data.data) {
+		if (item.t === 0) {
+			sources.push({
+				title: item.title,
+				url: item.url,
+				snippet: item.snippet,
+				publishedDate: item.published ?? undefined,
+				ageSeconds: dateToAgeSeconds(item.published),
+			});
+		} else if (item.t === 1) {
+			relatedQuestions.push(...item.list);
+		}
+	}
+
+	return {
+		provider: "kagi",
+		sources: sources.slice(0, numResults),
+		relatedQuestions: relatedQuestions.length > 0 ? relatedQuestions : undefined,
+		requestId: data.meta.id,
+	};
+}
+
+/** Search provider for Kagi web search. */
+export class KagiProvider extends SearchProvider {
+	readonly id = "kagi";
+	readonly label = "Kagi";
+
+	isAvailable() {
+		try {
+			return !!findApiKey();
+		} catch {
+			return false;
+		}
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchKagi({
+			query: params.query,
+			num_results: params.numSearchResults ?? params.limit,
+			signal: params.signal,
+		});
+	}
+}

package/src/web/search/types.ts

@@ -15,6 +15,7 @@ export type SearchProviderId =
 	| "perplexity"
 	| "gemini"
 	| "codex"
+	| "kagi"
 	| "synthetic";
 
 /** Source returned by search (all providers) */

package/src/internal-urls/memory-protocol.ts

@@ -1,133 +0,0 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { isEnoent } from "@nghyane/arcane-utils";
-import { validateRelativePath } from "./skill-protocol";
-import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
-
-const DEFAULT_MEMORY_FILE = "memory_summary.md";
-const MEMORY_NAMESPACE = "root";
-
-/**
- * Options for the memory:// URL protocol.
- */
-export interface MemoryProtocolOptions {
-	/**
-	 * Returns the absolute path to the current project's memory root.
-	 */
-	getMemoryRoot: () => string;
-}
-
-function ensureWithinRoot(targetPath: string, rootPath: string): void {
-	if (targetPath !== rootPath && !targetPath.startsWith(`${rootPath}${path.sep}`)) {
-		throw new Error("memory:// URL escapes memory root");
-	}
-}
-
-function toMemoryValidationError(error: unknown): Error {
-	const message = error instanceof Error ? error.message : String(error);
-	return new Error(message.replace("skill://", "memory://"));
-}
-
-/**
- * Resolve a memory:// URL to an absolute filesystem path under memory root.
- */
-export function resolveMemoryUrlToPath(url: InternalUrl, memoryRoot: string): string {
-	const namespace = url.rawHost || url.hostname;
-	if (!namespace) {
-		throw new Error("memory:// URL requires a namespace: memory://root");
-	}
-	if (namespace !== MEMORY_NAMESPACE) {
-		throw new Error(`Unknown memory namespace: ${namespace}. Supported: ${MEMORY_NAMESPACE}`);
-	}
-
-	const rawPathname = url.rawPathname ?? url.pathname;
-	const hasPath = rawPathname && rawPathname !== "/" && rawPathname !== "";
-	if (!hasPath) {
-		return path.resolve(memoryRoot, DEFAULT_MEMORY_FILE);
-	}
-	let relativePath: string;
-	try {
-		relativePath = decodeURIComponent(rawPathname.slice(1));
-	} catch {
-		throw new Error(`Invalid URL encoding in memory:// path: ${url.href}`);
-	}
-
-	try {
-		validateRelativePath(relativePath);
-	} catch (error) {
-		throw toMemoryValidationError(error);
-	}
-
-	return path.resolve(memoryRoot, relativePath);
-}
-
-/**
- * Protocol handler for memory:// URLs.
- *
- * URL forms:
- * - memory://root - Reads memory_summary.md
- * - memory://root/<path> - Reads a relative file under memory root
- */
-export class MemoryProtocolHandler implements ProtocolHandler {
-	readonly scheme = "memory";
-
-	constructor(private readonly options: MemoryProtocolOptions) {}
-
-	async resolve(url: InternalUrl): Promise<InternalResource> {
-		const memoryRoot = path.resolve(this.options.getMemoryRoot());
-		let resolvedRoot: string;
-		try {
-			resolvedRoot = await fs.realpath(memoryRoot);
-		} catch (error) {
-			if (isEnoent(error)) {
-				throw new Error(
-					"Memory artifacts are not available for this project yet. Run a session with memories enabled first.",
-				);
-			}
-			throw error;
-		}
-
-		const targetPath = resolveMemoryUrlToPath(url, resolvedRoot);
-		ensureWithinRoot(targetPath, resolvedRoot);
-
-		const parentDir = path.dirname(targetPath);
-		try {
-			const realParent = await fs.realpath(parentDir);
-			ensureWithinRoot(realParent, resolvedRoot);
-		} catch (error) {
-			if (!isEnoent(error)) {
-				throw error;
-			}
-		}
-
-		let realTargetPath: string;
-		try {
-			realTargetPath = await fs.realpath(targetPath);
-		} catch (error) {
-			if (isEnoent(error)) {
-				throw new Error(`Memory file not found: ${url.href}`);
-			}
-			throw error;
-		}
-
-		ensureWithinRoot(realTargetPath, resolvedRoot);
-
-		const stat = await fs.stat(realTargetPath);
-		if (!stat.isFile()) {
-			throw new Error(`memory:// URL must resolve to a file: ${url.href}`);
-		}
-
-		const content = await Bun.file(realTargetPath).text();
-		const ext = path.extname(realTargetPath).toLowerCase();
-		const contentType: InternalResource["contentType"] = ext === ".md" ? "text/markdown" : "text/plain";
-
-		return {
-			url: url.href,
-			content,
-			contentType,
-			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: realTargetPath,
-			notes: [],
-		};
-	}
-}