@nghyane/arcane 0.1.16 → 0.1.18

package/src/tools/render-mermaid.ts

@@ -0,0 +1,68 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import { type AsciiRenderOptions, renderMermaidAscii } from "@nghyane/arcane-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { renderPromptTemplate } from "../config/prompt-templates";
+import renderMermaidDescription from "../prompts/tools/render-mermaid.md" with { type: "text" };
+import type { ToolSession } from "./index";
+import { allocateOutputArtifact } from "./output-utils";
+
+const renderMermaidSchema = Type.Object({
+	mermaid: Type.String({ description: "Mermaid graph source text" }),
+	config: Type.Optional(
+		Type.Object({
+			useAscii: Type.Optional(Type.Boolean()),
+			paddingX: Type.Optional(Type.Number()),
+			paddingY: Type.Optional(Type.Number()),
+			boxBorderPadding: Type.Optional(Type.Number()),
+		}),
+	),
+});
+
+type RenderMermaidParams = Static<typeof renderMermaidSchema>;
+
+function sanitizeRenderConfig(config: AsciiRenderOptions | undefined): AsciiRenderOptions | undefined {
+	if (!config) return undefined;
+	return {
+		useAscii: config.useAscii,
+		boxBorderPadding:
+			config.boxBorderPadding === undefined ? undefined : Math.max(0, Math.floor(config.boxBorderPadding)),
+		paddingX: config.paddingX === undefined ? undefined : Math.max(0, Math.floor(config.paddingX)),
+		paddingY: config.paddingY === undefined ? undefined : Math.max(0, Math.floor(config.paddingY)),
+	};
+}
+
+export interface RenderMermaidToolDetails {
+	artifactId?: string;
+}
+
+export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema, RenderMermaidToolDetails> {
+	readonly name = "render_mermaid";
+	readonly label = "RenderMermaid";
+	readonly description: string;
+	readonly parameters = renderMermaidSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {
+		this.description = renderPromptTemplate(renderMermaidDescription);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: RenderMermaidParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<RenderMermaidToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<RenderMermaidToolDetails>> {
+		const ascii = renderMermaidAscii(params.mermaid, sanitizeRenderConfig(params.config));
+		const { artifactPath, artifactId } = await allocateOutputArtifact(this.session, "render_mermaid");
+		if (artifactPath) {
+			await Bun.write(artifactPath, ascii);
+		}
+
+		const artifactLine = artifactId ? `\n\nSaved artifact: artifact://${artifactId}` : "";
+		return {
+			content: [{ type: "text", text: `${ascii}${artifactLine}` }],
+			details: { artifactId },
+		};
+	}
+}

package/src/tools/save-memory.ts

@@ -0,0 +1,182 @@
+import * as path from "node:path";
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import type { Component } from "@nghyane/arcane-tui";
+import { Text } from "@nghyane/arcane-tui";
+import { isEnoent, logger } from "@nghyane/arcane-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../theme/theme";
+import { renderStatusLine } from "../tui";
+import { shortenPath, TRUNCATE_LENGTHS, truncateToWidth } from "../ui/render-utils";
+import type { ToolSession } from ".";
+
+const saveMemorySchema = Type.Object({
+	fact: Type.String({ description: "A clear, self-contained statement to remember across sessions" }),
+});
+
+type SaveMemoryParams = Static<typeof saveMemorySchema>;
+
+export interface SaveMemoryToolDetails {
+	fact: string;
+	filePath: string;
+	duplicate?: boolean;
+}
+
+interface SaveMemoryRenderArgs {
+	fact?: string;
+}
+
+const MEMORIES_HEADING = "## Memories";
+const MEMORIES_HEADING_RE = /^## Memories\s*$/;
+const NEXT_HEADING_RE = /^## /;
+
+async function findNearestAgentsMd(startDir: string): Promise<string | null> {
+	let dir = path.resolve(startDir);
+	const root = path.parse(dir).root;
+	while (true) {
+		const candidate = path.join(dir, "AGENTS.md");
+		try {
+			await Bun.file(candidate).text();
+			return candidate;
+		} catch (err) {
+			if (!isEnoent(err)) throw err;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir || dir === root) break;
+		dir = parent;
+	}
+	return null;
+}
+
+function insertMemory(content: string, fact: string): { content: string; duplicate: boolean } {
+	const lines = content.split("\n");
+	const bullet = `- ${fact}`;
+
+	// Find Memories section
+	let sectionStart = -1;
+	for (let i = 0; i < lines.length; i++) {
+		if (MEMORIES_HEADING_RE.test(lines[i])) {
+			sectionStart = i;
+			break;
+		}
+	}
+
+	if (sectionStart === -1) {
+		// Append section at end
+		const trimmed = content.trimEnd();
+		return { content: `${trimmed}\n\n${MEMORIES_HEADING}\n${bullet}\n`, duplicate: false };
+	}
+
+	// Find section end (next ## heading or EOF)
+	let sectionEnd = lines.length;
+	for (let i = sectionStart + 1; i < lines.length; i++) {
+		if (NEXT_HEADING_RE.test(lines[i])) {
+			sectionEnd = i;
+			break;
+		}
+	}
+
+	// Check duplicates among existing bullets
+	const factLower = fact.toLowerCase();
+	for (let i = sectionStart + 1; i < sectionEnd; i++) {
+		const line = lines[i].trim();
+		if (line.startsWith("- ")) {
+			const existing = line.slice(2).toLowerCase();
+			if (existing.includes(factLower) || factLower.includes(existing)) {
+				return { content, duplicate: true };
+			}
+		}
+	}
+
+	// Insert bullet before sectionEnd
+	lines.splice(sectionEnd, 0, bullet);
+	return { content: lines.join("\n"), duplicate: false };
+}
+
+export class SaveMemoryTool implements AgentTool<typeof saveMemorySchema, SaveMemoryToolDetails, Theme> {
+	readonly name = "save_memory";
+	readonly label = "Save Memory";
+	description =
+		'Save a fact or preference to long-term memory that persists across sessions. Use when the user explicitly asks to remember something or states a clear preference. Facts should be short, self-contained: "Prefers tabs over spaces", "Project uses pnpm". Do not save transient conversation context. If unsure, ask the user.';
+	readonly parameters = saveMemorySchema;
+	readonly concurrency = "exclusive";
+
+	constructor(private readonly session: ToolSession) {}
+
+	async execute(
+		_toolCallId: string,
+		params: SaveMemoryParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<SaveMemoryToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<SaveMemoryToolDetails>> {
+		const fact = params.fact.trim();
+		if (!fact) {
+			return {
+				content: [{ type: "text", text: "Fact cannot be empty." }],
+				details: { fact: "", filePath: "" },
+			};
+		}
+
+		let filePath = await findNearestAgentsMd(this.session.cwd);
+		let content: string;
+
+		if (filePath) {
+			content = await Bun.file(filePath).text();
+		} else {
+			filePath = path.join(this.session.cwd, "AGENTS.md");
+			content = "";
+		}
+
+		const result = insertMemory(content, fact);
+
+		if (result.duplicate) {
+			return {
+				content: [{ type: "text", text: "This fact is already saved." }],
+				details: { fact, filePath, duplicate: true },
+			};
+		}
+
+		try {
+			await Bun.write(filePath, result.content);
+		} catch (err) {
+			logger.error("Failed to write AGENTS.md", { path: filePath, error: String(err) });
+			return {
+				content: [{ type: "text", text: "Failed to save memory." }],
+				details: { fact, filePath },
+			};
+		}
+
+		return {
+			content: [{ type: "text", text: `Saved to ${filePath}` }],
+			details: { fact, filePath },
+		};
+	}
+
+	renderCall(args: SaveMemoryRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const preview = args.fact ? truncateToWidth(args.fact, TRUNCATE_LENGTHS.CONTENT) : "";
+		const meta = preview ? [preview] : [];
+		const text = renderStatusLine({ icon: "pending", title: "Save Memory", meta }, uiTheme);
+		return new Text(text, 0, 0);
+	}
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: SaveMemoryToolDetails },
+		_options: RenderResultOptions,
+		uiTheme: Theme,
+		_args?: SaveMemoryRenderArgs,
+	): Component {
+		const details = result.details;
+		const isDuplicate = details?.duplicate === true;
+		const icon = isDuplicate ? "info" : "success";
+		const filePath = details?.filePath ? shortenPath(details.filePath) : "";
+		const meta = filePath ? [filePath] : [];
+		const header = renderStatusLine({ icon, title: "Save Memory", meta }, uiTheme);
+
+		const message = isDuplicate
+			? uiTheme.fg("dim", "This fact is already saved.")
+			: uiTheme.fg("dim", details?.fact ?? "");
+
+		return new Text(`${header}\n${message}`, 0, 0);
+	}
+}

package/src/tools/write.ts

@@ -71,7 +71,7 @@ type WriteParams = WriteToolInput;
 export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails, Theme> {
 	readonly name = "write";
 	readonly label = "Write";
-	description = "Create a new file";
+	description = "Create a new file. For existing files, prefer edit instead — even for extensive changes.";
 	readonly parameters = writeSchema;
 	readonly nonAbortable = true;
 	readonly concurrency = "exclusive";

package/src/web/search/index.ts

@@ -35,6 +35,7 @@ export const webSearchSchema = Type.Object({
 			"exa",
 			"brave",
 			"jina",
+			"kagi",
 			"kimi",
 			"zai",
 			"anthropic",
@@ -55,6 +56,7 @@ export type SearchParams = {
 		| "exa"
 		| "brave"
 		| "jina"
+		| "kagi"
 		| "kimi"
 		| "zai"
 		| "anthropic"
@@ -263,7 +265,8 @@ export async function runSearchQuery(params: SearchParams): Promise<{
 export class SearchTool implements AgentTool<typeof webSearchSchema, SearchRenderDetails, Theme> {
 	readonly name = "web_search";
 	readonly label = "Web Search";
-	readonly description = "Search the web";
+	readonly description =
+		"Search the web for up-to-date information. Use fetch to read full content from a specific URL.";
 	readonly parameters = webSearchSchema;
 	readonly renderCall = renderSearchCall;
 	readonly renderResult = renderSearchResult;

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;