@nghyane/arcane 0.1.0

package/src/exa/mcp-client.ts

@@ -0,0 +1,289 @@
+import { $env, logger } from "@nghyane/arcane-utils";
+import type { TSchema } from "@sinclair/typebox";
+import type { CustomTool, CustomToolResult } from "../extensibility/custom-tools/types";
+import { callMCP } from "../mcp/json-rpc";
+import type {
+	ExaRenderDetails,
+	ExaSearchResponse,
+	ExaSearchResult,
+	MCPCallResponse,
+	MCPTool,
+	MCPToolsResponse,
+	MCPToolWrapperConfig,
+} from "./types";
+
+/** Find EXA_API_KEY from Bun.env or .env files */
+export function findApiKey(): string | null {
+	return $env.EXA_API_KEY;
+}
+
+/** Fetch available tools from Exa MCP */
+export async function fetchExaTools(apiKey: string, toolNames: string[]): Promise<MCPTool[]> {
+	const url = `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(apiKey)}&toolNames=${encodeURIComponent(toolNames.join(","))}`;
+	const response = (await callMCP(url, "tools/list")) as MCPToolsResponse;
+
+	if (response.error) {
+		logger.error("MCP tools/list error", { toolNames, error: response.error });
+		throw new Error(`MCP error: ${response.error.message}`);
+	}
+
+	return response.result?.tools ?? [];
+}
+
+/** Fetch available tools from Websets MCP */
+export async function fetchWebsetsTools(apiKey: string): Promise<MCPTool[]> {
+	const url = `https://websetsmcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(apiKey)}`;
+	const response = (await callMCP(url, "tools/list")) as MCPToolsResponse;
+
+	if (response.error) {
+		logger.error("Websets MCP tools/list error", { error: response.error });
+		throw new Error(`MCP error: ${response.error.message}`);
+	}
+
+	return response.result?.tools ?? [];
+}
+
+/** Call a tool on Exa MCP (simplified: toolName as first arg for easier use) */
+export async function callExaTool(toolName: string, args: Record<string, unknown>, apiKey: string): Promise<unknown> {
+	const url = `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(apiKey)}&tools=${encodeURIComponent(toolName)}`;
+	const response = (await callMCP(url, "tools/call", {
+		name: toolName,
+		arguments: args,
+	})) as MCPCallResponse;
+
+	if (response.error) {
+		logger.error("MCP tools/call error", { toolName, args, error: response.error });
+		throw new Error(`MCP error: ${response.error.message}`);
+	}
+
+	return response.result;
+}
+
+/** Call a tool on Websets MCP */
+export async function callWebsetsTool(
+	apiKey: string,
+	toolName: string,
+	args: Record<string, unknown>,
+): Promise<unknown> {
+	const url = `https://websetsmcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(apiKey)}`;
+	const response = (await callMCP(url, "tools/call", {
+		name: toolName,
+		arguments: args,
+	})) as MCPCallResponse;
+
+	if (response.error) {
+		logger.error("Websets MCP tools/call error", { toolName, args, error: response.error });
+		throw new Error(`MCP error: ${response.error.message}`);
+	}
+
+	return response.result;
+}
+
+/** Parse Exa markdown format into SearchResponse */
+export function parseExaMarkdown(text: string): ExaSearchResponse | null {
+	const results: ExaSearchResult[] = [];
+	const lines = text.split("\n");
+	let currentResult: Partial<ExaSearchResult> | null = null;
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].trim();
+
+		// Match result header: ## Title
+		if (line.startsWith("## ")) {
+			if (currentResult?.title) {
+				results.push(currentResult as ExaSearchResult);
+			}
+			currentResult = { title: line.slice(3).trim() };
+			continue;
+		}
+
+		if (!currentResult) continue;
+
+		// Match URL: **URL:** ...
+		if (line.startsWith("**URL:**")) {
+			currentResult.url = line.slice(8).trim();
+			continue;
+		}
+
+		// Match Author: **Author:** ...
+		if (line.startsWith("**Author:**")) {
+			currentResult.author = line.slice(11).trim();
+			continue;
+		}
+
+		// Match Published Date: **Published Date:** ...
+		if (line.startsWith("**Published Date:**")) {
+			currentResult.publishedDate = line.slice(19).trim();
+			continue;
+		}
+
+		// Match Text: **Text:** ...
+		if (line.startsWith("**Text:**")) {
+			currentResult.text = line.slice(9).trim();
+			continue;
+		}
+
+		// Accumulate text content
+		if (currentResult.text && line && !line.startsWith("**")) {
+			currentResult.text += ` ${line}`;
+		}
+	}
+
+	// Add last result
+	if (currentResult?.title) {
+		results.push(currentResult as ExaSearchResult);
+	}
+
+	if (results.length === 0) return null;
+
+	return {
+		results,
+		statuses: results.map((r, i) => ({ id: r.id ?? `result-${i}`, status: "success" })),
+	};
+}
+
+/** Format search results for LLM */
+export function formatSearchResults(data: ExaSearchResponse): string {
+	const results = data.results ?? [];
+	if (results.length === 0) return "No results found.";
+
+	let output = "";
+	for (let i = 0; i < results.length; i++) {
+		const r = results[i];
+		output += `\n## ${r.title ?? "Untitled"}`;
+		if (r.url) output += `\n**URL:** ${r.url}`;
+		if (r.author) output += `\n**Author:** ${r.author}`;
+		if (r.publishedDate) output += `\n**Published Date:** ${r.publishedDate}`;
+		if (r.text) output += `\n**Text:** ${r.text}`;
+		if (r.highlights?.length) {
+			output += `\n**Highlights:**`;
+			for (const h of r.highlights) {
+				output += `\n- ${h}`;
+			}
+		}
+		output += "\n";
+	}
+
+	if (data.costDollars) {
+		output += `\n**Cost:** $${data.costDollars.total.toFixed(4)}`;
+	}
+	if (data.searchTime) {
+		output += `\n**Search Time:** ${data.searchTime.toFixed(2)}s`;
+	}
+
+	return output.trim();
+}
+
+/** Check if result is a search response */
+export function isSearchResponse(data: unknown): data is ExaSearchResponse {
+	return (
+		typeof data === "object" &&
+		data !== null &&
+		("results" in data || "statuses" in data || "costDollars" in data || "searchTime" in data)
+	);
+}
+
+/** Cache for MCP tool schemas (keyed by MCP tool name) */
+const mcpSchemaCache = new Map<string, MCPTool>();
+
+/** Fetch and cache MCP tool schema */
+export async function fetchMCPToolSchema(
+	apiKey: string,
+	mcpToolName: string,
+	isWebsetsTool = false,
+): Promise<MCPTool | null> {
+	const cacheKey = `${isWebsetsTool ? "websets" : "exa"}:${mcpToolName}`;
+	if (mcpSchemaCache.has(cacheKey)) {
+		return mcpSchemaCache.get(cacheKey)!;
+	}
+
+	try {
+		const tools = isWebsetsTool ? await fetchWebsetsTools(apiKey) : await fetchExaTools(apiKey, [mcpToolName]);
+		const tool = tools.find(t => t.name === mcpToolName);
+		if (tool) {
+			mcpSchemaCache.set(cacheKey, tool);
+			return tool;
+		}
+	} catch (error) {
+		logger.warn("Failed to fetch MCP tool schema", { mcpToolName, isWebsetsTool, error: String(error) });
+	}
+	return null;
+}
+
+/**
+ * CustomTool dynamically created from MCP tool metadata.
+ *
+ * This allows tools to be generated from MCP server schemas without hardcoding,
+ * reducing drift when MCP servers add new parameters.
+ */
+export class MCPWrappedTool implements CustomTool<TSchema, ExaRenderDetails> {
+	readonly name: string;
+	readonly label: string;
+
+	constructor(
+		private readonly config: MCPToolWrapperConfig,
+		public readonly parameters: TSchema,
+		public readonly description: string,
+	) {
+		this.name = config.name;
+		this.label = config.label;
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: unknown,
+		_onUpdate?: unknown,
+		_ctx?: unknown,
+		_signal?: AbortSignal,
+	): Promise<CustomToolResult<ExaRenderDetails>> {
+		try {
+			const apiKey = await findApiKey();
+			if (!apiKey) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+					details: { error: "EXA_API_KEY not found", toolName: this.config.name },
+				};
+			}
+
+			const response = this.config.isWebsetsTool
+				? await callWebsetsTool(apiKey, this.config.mcpToolName, params as Record<string, unknown>)
+				: await callExaTool(this.config.mcpToolName, params as Record<string, unknown>, apiKey);
+
+			if (isSearchResponse(response)) {
+				const formatted = formatSearchResults(response);
+				return {
+					content: [{ type: "text" as const, text: formatted }],
+					details: { response, toolName: this.config.name },
+				};
+			}
+
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+				details: { raw: response, toolName: this.config.name },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text" as const, text: `Error: ${message}` }],
+				details: { error: message, toolName: this.config.name },
+			};
+		}
+	}
+}
+
+/**
+ * Create a CustomTool by fetching schema from MCP server.
+ *
+ * Falls back to provided fallback schema if MCP fetch fails.
+ */
+export async function createMCPToolFromServer(
+	apiKey: string,
+	config: MCPToolWrapperConfig,
+	fallbackSchema: TSchema,
+	fallbackDescription: string,
+): Promise<MCPWrappedTool> {
+	const mcpTool = await fetchMCPToolSchema(apiKey, config.mcpToolName, config.isWebsetsTool);
+	const schema = mcpTool?.inputSchema ?? fallbackSchema;
+	const description = mcpTool?.description ?? fallbackDescription;
+	return new MCPWrappedTool(config, schema, description);
+}

package/src/exa/render.ts

@@ -0,0 +1,244 @@
+/**
+ * Exa TUI Rendering
+ *
+ * Tree-based rendering with collapsed/expanded states for Exa search results.
+ */
+import type { Component } from "@nghyane/arcane-tui";
+import { Text } from "@nghyane/arcane-tui";
+import { logger } from "@nghyane/arcane-utils";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import {
+	formatCount,
+	formatExpandHint,
+	formatMoreItems,
+	formatStatusIcon,
+	getDomain,
+	getPreviewLines,
+	PREVIEW_LIMITS,
+	TRUNCATE_LENGTHS,
+	truncateToWidth,
+} from "../tools/render-utils";
+import type { ExaRenderDetails } from "./types";
+
+const COLLAPSED_PREVIEW_LINES = PREVIEW_LIMITS.COLLAPSED_LINES;
+const COLLAPSED_PREVIEW_LINE_LEN = TRUNCATE_LENGTHS.LONG;
+const EXPANDED_TEXT_LINES = 5;
+const EXPANDED_TEXT_LINE_LEN = 90;
+const MAX_TITLE_LEN = TRUNCATE_LENGTHS.TITLE;
+const MAX_HIGHLIGHT_LEN = TRUNCATE_LENGTHS.CONTENT;
+
+function renderErrorMessage(message: string, theme: Theme): Text {
+	const clean = message.replace(/^Error:\s*/, "").trim();
+	return new Text(
+		`${formatStatusIcon("error", theme)} ${theme.fg("error", `Error: ${clean || "Unknown error"}`)}`,
+		0,
+		0,
+	);
+}
+
+function renderEmptyMessage(message: string, theme: Theme): Text {
+	return new Text(`${formatStatusIcon("warning", theme)} ${theme.fg("muted", message)}`, 0, 0);
+}
+
+/** Render Exa result with tree-based layout */
+export function renderExaResult(
+	result: { content: Array<{ type: string; text?: string }>; details?: ExaRenderDetails },
+	options: RenderResultOptions,
+	uiTheme: Theme,
+): Component {
+	const { expanded } = options;
+	const details = result.details;
+
+	if (details?.error) {
+		logger.error("Exa render error", { error: details.error, toolName: details.toolName });
+		return renderErrorMessage(details.error, uiTheme);
+	}
+
+	const response = details?.response;
+	if (!response) {
+		if (details?.raw) {
+			const rawText = typeof details.raw === "string" ? details.raw : JSON.stringify(details.raw, null, 2);
+			const rawLines = rawText.split("\n").filter(l => l.trim());
+			const maxLines = expanded ? rawLines.length : Math.min(rawLines.length, COLLAPSED_PREVIEW_LINES);
+			const displayLines = rawLines.slice(0, maxLines);
+			const remaining = rawLines.length - maxLines;
+			const expandHint = formatExpandHint(uiTheme, expanded, remaining > 0);
+
+			let text = `${formatStatusIcon("info", uiTheme)} ${uiTheme.fg("dim", "Raw response")}${expandHint}`;
+
+			for (let i = 0; i < displayLines.length; i++) {
+				const isLast = i === displayLines.length - 1 && remaining === 0;
+				const branch = isLast ? uiTheme.tree.last : uiTheme.tree.branch;
+				text += `\n ${uiTheme.fg("dim", branch)} ${uiTheme.fg(
+					"toolOutput",
+					truncateToWidth(displayLines[i], COLLAPSED_PREVIEW_LINE_LEN),
+				)}`;
+			}
+
+			if (remaining > 0) {
+				text += `\n ${uiTheme.fg("dim", uiTheme.tree.last)} ${uiTheme.fg(
+					"muted",
+					formatMoreItems(remaining, "line"),
+				)}`;
+			}
+
+			return new Text(text, 0, 0);
+		}
+		return renderEmptyMessage("No response data", uiTheme);
+	}
+
+	const results = response.results ?? [];
+	const resultCount = results.length;
+	const cost = response.costDollars?.total;
+	const time = response.searchTime;
+
+	const icon = formatStatusIcon(resultCount > 0 ? "success" : "warning", uiTheme);
+
+	const metaParts = [formatCount("result", resultCount)];
+	if (cost !== undefined) metaParts.push(`cost:$${cost.toFixed(4)}`);
+	if (time !== undefined) metaParts.push(`time:${time.toFixed(2)}s`);
+	const summaryText = metaParts.join(uiTheme.sep.dot);
+
+	let hasMorePreview = false;
+	if (!expanded && resultCount > 0) {
+		const previewText = results[0].text ?? results[0].title ?? "";
+		const totalLines = previewText.split("\n").filter(l => l.trim()).length;
+		hasMorePreview = totalLines > COLLAPSED_PREVIEW_LINES || resultCount > 1;
+	}
+	const expandHint = formatExpandHint(uiTheme, expanded, hasMorePreview);
+
+	let text = `${icon} ${uiTheme.fg("dim", summaryText)}${expandHint}`;
+
+	if (!expanded) {
+		if (resultCount === 0) {
+			text += `\n ${uiTheme.fg("dim", uiTheme.tree.last)} ${uiTheme.fg("muted", "No results")}`;
+			return new Text(text, 0, 0);
+		}
+
+		const first = results[0];
+		const previewText = first.text ?? first.title ?? "";
+		const previewLines = previewText
+			? getPreviewLines(previewText, COLLAPSED_PREVIEW_LINES, COLLAPSED_PREVIEW_LINE_LEN)
+			: [];
+		const safePreviewLines = previewLines.length > 0 ? previewLines : ["No preview text"];
+		const totalLines = previewText.split("\n").filter(l => l.trim()).length;
+		const remainingLines = Math.max(0, totalLines - previewLines.length);
+		const extraItems: string[] = [];
+		if (remainingLines > 0) {
+			extraItems.push(formatMoreItems(remainingLines, "line"));
+		}
+		if (resultCount > 1) {
+			extraItems.push(formatMoreItems(resultCount - 1, "result"));
+		}
+
+		for (let i = 0; i < safePreviewLines.length; i++) {
+			const isLast = i === safePreviewLines.length - 1 && extraItems.length === 0;
+			const branch = isLast ? uiTheme.tree.last : uiTheme.tree.branch;
+			const line = safePreviewLines[i];
+			const color = line === "No preview text" ? "muted" : "toolOutput";
+			text += `\n ${uiTheme.fg("dim", branch)} ${uiTheme.fg(color, line)}`;
+		}
+
+		for (let i = 0; i < extraItems.length; i++) {
+			const isLast = i === extraItems.length - 1;
+			const branch = isLast ? uiTheme.tree.last : uiTheme.tree.branch;
+			text += `\n ${uiTheme.fg("dim", branch)} ${uiTheme.fg("muted", extraItems[i])}`;
+		}
+
+		return new Text(text, 0, 0);
+	}
+
+	if (resultCount === 0) {
+		text += `\n ${uiTheme.fg("dim", uiTheme.tree.last)} ${uiTheme.fg("muted", "No results")}`;
+		return new Text(text, 0, 0);
+	}
+
+	for (let i = 0; i < results.length; i++) {
+		const res = results[i];
+		const isLast = i === results.length - 1;
+		const branch = isLast ? uiTheme.tree.last : uiTheme.tree.branch;
+		const cont = isLast ? " " : uiTheme.tree.vertical;
+
+		const title = truncateToWidth(res.title ?? "Untitled", MAX_TITLE_LEN);
+		const domain = res.url ? getDomain(res.url) : "";
+		const domainPart = domain ? uiTheme.fg("dim", ` (${domain})`) : "";
+
+		text += `\n ${uiTheme.fg("dim", branch)} ${uiTheme.fg("accent", title)}${domainPart}`;
+
+		if (res.url) {
+			text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+				"mdLinkUrl",
+				res.url,
+			)}`;
+		}
+
+		if (res.author) {
+			text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+				"muted",
+				`Author: ${res.author}`,
+			)}`;
+		}
+
+		if (res.publishedDate) {
+			text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+				"muted",
+				`Published: ${res.publishedDate}`,
+			)}`;
+		}
+
+		if (res.text) {
+			const textLines = res.text.split("\n").filter(l => l.trim());
+			const displayLines = textLines.slice(0, EXPANDED_TEXT_LINES);
+			for (const line of displayLines) {
+				text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+					"toolOutput",
+					truncateToWidth(line.trim(), EXPANDED_TEXT_LINE_LEN),
+				)}`;
+			}
+			if (textLines.length > EXPANDED_TEXT_LINES) {
+				text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+					"muted",
+					formatMoreItems(textLines.length - EXPANDED_TEXT_LINES, "line"),
+				)}`;
+			}
+		}
+
+		if (res.highlights?.length) {
+			text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+				"accent",
+				"Highlights",
+			)}`;
+			const maxHighlights = Math.min(res.highlights.length, 3);
+			for (let j = 0; j < maxHighlights; j++) {
+				const h = res.highlights[j];
+				text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+					"muted",
+					`${uiTheme.format.dash} ${truncateToWidth(h, MAX_HIGHLIGHT_LEN)}`,
+				)}`;
+			}
+			if (res.highlights.length > maxHighlights) {
+				text += `\n ${uiTheme.fg("dim", cont)} ${uiTheme.fg("dim", uiTheme.tree.hook)} ${uiTheme.fg(
+					"muted",
+					formatMoreItems(res.highlights.length - maxHighlights, "highlight"),
+				)}`;
+			}
+		}
+	}
+
+	return new Text(text, 0, 0);
+}
+
+/** Render Exa call (query/args preview) */
+export function renderExaCall(args: Record<string, unknown>, toolName: string, uiTheme: Theme): Component {
+	const toolLabel = toolName || "Exa Search";
+	const query = typeof args.query === "string" ? truncateToWidth(args.query, 80) : "?";
+	const numResults = typeof args.num_results === "number" ? args.num_results : undefined;
+
+	let text = `${uiTheme.fg("toolTitle", toolLabel)} ${uiTheme.fg("accent", query)}`;
+	if (numResults !== undefined) {
+		text += ` ${uiTheme.fg("muted", `results:${numResults}`)}`;
+	}
+
+	return new Text(text, 0, 0);
+}

package/src/exa/researcher.ts

@@ -0,0 +1,89 @@
+/**
+ * Exa Researcher Tools
+ *
+ * Async research tasks with polling for completion.
+ */
+import { Type } from "@sinclair/typebox";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { callExaTool, findApiKey } from "./mcp-client";
+import type { ExaRenderDetails } from "./types";
+
+const researcherStartTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_researcher_start",
+	label: "Start Deep Research",
+	description:
+		"Start an asynchronous deep research task using Exa's researcher. Returns a task_id for polling completion.",
+	parameters: Type.Object({
+		query: Type.String({ description: "Research query to investigate" }),
+		depth: Type.Optional(
+			Type.Number({
+				description: "Research depth (1-5, default: 3)",
+				minimum: 1,
+				maximum: 5,
+			}),
+		),
+		breadth: Type.Optional(
+			Type.Number({
+				description: "Research breadth (1-5, default: 3)",
+				minimum: 1,
+				maximum: 5,
+			}),
+		),
+	}),
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const apiKey = await findApiKey();
+			if (!apiKey) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+					details: { error: "EXA_API_KEY not found", toolName: "exa_researcher_start" },
+				};
+			}
+			const result = await callExaTool("deep_researcher_start", params as Record<string, unknown>, apiKey);
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+				details: { raw: result, toolName: "exa_researcher_start" },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text" as const, text: `Error: ${message}` }],
+				details: { error: message, toolName: "exa_researcher_start" },
+			};
+		}
+	},
+};
+
+const researcherPollTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_researcher_poll",
+	label: "Poll Research Status",
+	description:
+		"Poll the status of an asynchronous research task. Returns status (pending|running|completed|failed) and result if completed.",
+	parameters: Type.Object({
+		task_id: Type.String({ description: "Task ID returned from exa_researcher_start" }),
+	}),
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const apiKey = await findApiKey();
+			if (!apiKey) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+					details: { error: "EXA_API_KEY not found", toolName: "exa_researcher_poll" },
+				};
+			}
+			const result = await callExaTool("deep_researcher_check", params as Record<string, unknown>, apiKey);
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+				details: { raw: result, toolName: "exa_researcher_poll" },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text" as const, text: `Error: ${message}` }],
+				details: { error: message, toolName: "exa_researcher_poll" },
+			};
+		}
+	},
+};
+
+export const researcherTools: CustomTool<any, ExaRenderDetails>[] = [researcherStartTool, researcherPollTool];