@nghyane/arcane 0.1.16 → 0.1.17

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: [],
-		};
-	}
-}