@gajae-code/coding-agent 0.1.1

package/src/exa/mcp-client.ts

@@ -0,0 +1,364 @@
+import type { TSchema } from "@gajae-code/ai";
+import { $env, logger } from "@gajae-code/utils";
+import type { CustomTool, CustomToolResult } from "../extensibility/custom-tools/types";
+import { callMCP } from "../runtime-mcp/json-rpc";
+import type {
+	ExaRenderDetails,
+	ExaSearchResponse,
+	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;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	if (typeof value !== "object" || value === null) return null;
+	return value as Record<string, unknown>;
+}
+
+function parseJsonContent(text: string): unknown | null {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Normalize tools/call payloads across MCP servers.
+ *
+ * Exa currently returns different shapes depending on deployment/environment:
+ * - direct payload in result
+ * - structured payload under result.structuredContent / result.data / result.result
+ * - JSON payload embedded as text in result.content[]
+ */
+function normalizeMcpToolPayload(payload: unknown): unknown {
+	const candidates: unknown[] = [];
+	const root = asRecord(payload);
+
+	if (root) {
+		if (root.structuredContent !== undefined) candidates.push(root.structuredContent);
+		if (root.data !== undefined) candidates.push(root.data);
+		if (root.result !== undefined) candidates.push(root.result);
+		candidates.push(root);
+
+		const content = root.content;
+		if (Array.isArray(content)) {
+			for (const item of content) {
+				const part = asRecord(item);
+				if (!part) continue;
+				const text = part.text;
+				if (typeof text !== "string" || text.trim().length === 0) continue;
+				const parsed = parseJsonContent(text);
+				if (parsed !== null) candidates.push(parsed);
+			}
+		}
+	} else {
+		candidates.push(payload);
+	}
+
+	for (const candidate of candidates) {
+		if (isSearchResponse(candidate)) {
+			return candidate;
+		}
+	}
+
+	return payload;
+}
+
+/** Fetch available tools from Exa MCP */
+export async function fetchExaTools(apiKey: string | null, toolNames: string[]): Promise<MCPTool[]> {
+	const params = new URLSearchParams();
+	if (apiKey) params.set("exaApiKey", apiKey);
+	params.set("toolNames", toolNames.join(","));
+	const url = `https://mcp.exa.ai/mcp?${params.toString()}`;
+	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 | null,
+): Promise<unknown> {
+	const params = new URLSearchParams();
+	if (apiKey) params.set("exaApiKey", apiKey);
+	params.set("tools", toolName);
+	const url = `https://mcp.exa.ai/mcp?${params.toString()}`;
+	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 normalizeMcpToolPayload(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 normalizeMcpToolPayload(response.result);
+}
+
+/** 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();
+}
+/**
+ * Format a non-search MCP response as human-readable text.
+ * Handles objects, arrays, primitives, and common MCP response shapes.
+ */
+export function formatGenericResponse(data: unknown): string {
+	if (data === null || data === undefined) return "No result.";
+	if (typeof data === "string") return data;
+	if (typeof data === "number" || typeof data === "boolean") return String(data);
+
+	if (Array.isArray(data)) {
+		if (data.length === 0) return "(empty)";
+		const parts: string[] = [];
+		for (let i = 0; i < data.length; i++) {
+			const item = data[i];
+			if (typeof item === "object" && item !== null) {
+				const record = item as Record<string, unknown>;
+				const title = (record.title ?? record.name ?? record.id ?? `Item ${i + 1}`) as string;
+				parts.push(`\n### ${title}`);
+				for (const [k, v] of Object.entries(record)) {
+					if (["title", "name", "id"].includes(k)) continue;
+					parts.push(`- **${k}:** ${formatValue(v)}`);
+				}
+			} else {
+				parts.push(`- ${formatValue(item)}`);
+			}
+		}
+		return parts.join("\n");
+	}
+
+	if (typeof data === "object") {
+		const record = data as Record<string, unknown>;
+		if (record.content && Array.isArray(record.content)) {
+			// MCP-style content array — extract text blocks
+			const texts = record.content
+				.filter(
+					(c: unknown): c is { type: string; text?: string } =>
+						typeof c === "object" && c !== null && (c as Record<string, unknown>)?.type === "text",
+				)
+				.map(c => c.text ?? "")
+				.filter(Boolean);
+			if (texts.length > 0) return texts.join("\n");
+		}
+
+		const lines: string[] = [];
+		for (const [k, v] of Object.entries(record)) {
+			if (k === "content") continue; // handled above
+			if (v === null || v === undefined) continue;
+			if (typeof v === "object") {
+				const formatted = formatGenericResponse(v);
+				if (formatted) lines.push(`- **${k}:**\n${indent(formatted, 2)}`);
+			} else {
+				lines.push(`- **${k}:** ${formatValue(v)}`);
+			}
+		}
+		return lines.join("\n") || "(empty)";
+	}
+
+	return String(data);
+}
+
+function formatValue(v: unknown): string {
+	if (v === null || v === undefined) return "—";
+	if (typeof v === "object") return JSON.stringify(v);
+	return String(v);
+}
+
+function indent(text: string, spaces: number): string {
+	const pad = " ".repeat(spaces);
+	return text
+		.split("\n")
+		.map(line => pad + line)
+		.join("\n");
+}
+
+/** 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 = findApiKey();
+			// Websets tools require an API key; basic Exa MCP tools work without one
+			if (!apiKey && this.config.isWebsetsTool) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY required for Websets tools" }],
+					details: { error: "EXA_API_KEY required for Websets tools", 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: formatGenericResponse(response) }],
+				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 "@gajae-code/tui";
+import { Text } from "@gajae-code/tui";
+import { logger } from "@gajae-code/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,36 @@
+/**
+ * Exa Researcher Tools
+ *
+ * Async research tasks with polling for completion.
+ */
+import type { TSchema } from "@gajae-code/ai";
+import * as z from "zod/v4";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { createExaTool } from "./factory";
+import type { ExaRenderDetails } from "./types";
+
+const researcherStartTool = createExaTool(
+	"exa_researcher_start",
+	"Start Deep Research",
+	"Start an asynchronous deep research task using Exa's researcher. Returns a task_id for polling completion.",
+	z.object({
+		query: z.string().describe("research query"),
+		depth: z.number().int().min(1).max(5).describe("research depth (1-5)").optional(),
+		breadth: z.number().int().min(1).max(5).describe("research breadth (1-5)").optional(),
+	}),
+	"deep_researcher_start",
+	{ formatResponse: false },
+);
+
+const researcherPollTool = createExaTool(
+	"exa_researcher_poll",
+	"Poll Research Status",
+	"Poll the status of an asynchronous research task. Returns status (pending|running|completed|failed) and result if completed.",
+	z.object({
+		task_id: z.string().describe("task id"),
+	}),
+	"deep_researcher_check",
+	{ formatResponse: false },
+);
+
+export const researcherTools: CustomTool<TSchema, ExaRenderDetails>[] = [researcherStartTool, researcherPollTool];

package/src/exa/search.ts

@@ -0,0 +1,47 @@
+/**
+ * Exa Search Tools
+ *
+ * Basic neural/keyword search, deep research, code search, and URL crawling.
+ */
+import type { TSchema } from "@gajae-code/ai";
+import * as z from "zod/v4";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { createExaTool } from "./factory";
+import type { ExaRenderDetails } from "./types";
+
+/** exa_search - Basic neural/keyword search */
+const exaSearchTool = createExaTool(
+	"exa_search",
+	"Exa Search",
+	`Search the web using Exa's neural or keyword search.
+
+Returns structured search results with optional text content and highlights.
+
+Parameters:
+- query: Search query (required)
+- type: Search type - "neural" (semantic), "keyword" (exact), or "auto" (default: auto)
+- include_domains: Array of domains to include in results
+- exclude_domains: Array of domains to exclude from results
+- start_published_date: Filter results published after this date (ISO 8601)
+- end_published_date: Filter results published before this date (ISO 8601)
+- use_autoprompt: Let Exa optimize your query automatically (default: true)
+- text: Include page text content in results (default: false, costs more)
+- highlights: Include highlighted relevant snippets (default: false)
+- num_results: Maximum number of results to return (default: 10, max: 100)`,
+
+	z.object({
+		query: z.string().describe("search query"),
+		type: z.enum(["keyword", "neural", "auto"]).describe("search type").optional(),
+		include_domains: z.array(z.string()).describe("include domains").optional(),
+		exclude_domains: z.array(z.string()).describe("exclude domains").optional(),
+		start_published_date: z.string().describe("published after (iso 8601)").optional(),
+		end_published_date: z.string().describe("published before (iso 8601)").optional(),
+		use_autoprompt: z.boolean().describe("autoprompt").optional(),
+		text: z.boolean().describe("include page text").optional(),
+		highlights: z.boolean().describe("include highlights").optional(),
+		num_results: z.number().int().min(1).max(100).describe("max results (1-100)").optional(),
+	}),
+	"web_search_exa",
+);
+
+export const searchTools: CustomTool<TSchema, ExaRenderDetails>[] = [exaSearchTool];