@oh-my-pi/pi-coding-agent 1.337.0

package/src/core/tools/exa/company.ts

@@ -0,0 +1,59 @@
+/**
+ * Exa Company Tool
+ *
+ * Research companies using Exa's comprehensive data sources.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { CustomTool } from "../../custom-tools/types.js";
+import type { ExaRenderDetails } from "./types.js";
+
+/** exa_company - Company research */
+export const companyTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_company",
+	label: "Exa Company",
+	description: `Research companies using Exa's comprehensive data sources.
+
+Returns detailed company information including overview, news, financials, and key people.
+
+Parameters:
+- company_name: Name of the company to research (e.g., "OpenAI", "Google", "Y Combinator")`,
+
+	parameters: Type.Object({
+		company_name: Type.String({ description: "Name of the company to research" }),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const { findApiKey, callExaTool, formatSearchResults, isSearchResponse } = await import("./mcp-client.js");
+
+			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_company" },
+				};
+			}
+			const response = await callExaTool("company_research_exa", params, apiKey);
+
+			if (isSearchResponse(response)) {
+				const formatted = formatSearchResults(response);
+				return {
+					content: [{ type: "text" as const, text: formatted }],
+					details: { response, toolName: "exa_company" },
+				};
+			}
+
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+				details: { raw: response, toolName: "exa_company" },
+			};
+		} 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_company" },
+			};
+		}
+	},
+};

package/src/core/tools/exa/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Exa MCP Tools
+ *
+ * 22 tools for Exa's MCP servers:
+ * - 4 search tools (search, deep, code, crawl)
+ * - 1 LinkedIn search tool
+ * - 1 company research tool
+ * - 2 researcher tools (start, poll)
+ * - 14 websets tools (CRUD, items, search, enrichment, monitor)
+ */
+
+import type { CustomTool } from "../../custom-tools/types.js";
+import type { ExaSettings } from "../../settings-manager.js";
+import { companyTool } from "./company.js";
+import { linkedinTool } from "./linkedin.js";
+import { researcherTools } from "./researcher.js";
+import { searchTools } from "./search.js";
+import type { ExaRenderDetails } from "./types.js";
+import { websetsTools } from "./websets.js";
+
+/** All Exa tools (22 total) - static export for backward compatibility */
+export const exaTools: CustomTool<any, ExaRenderDetails>[] = [
+	...searchTools,
+	linkedinTool,
+	companyTool,
+	...researcherTools,
+	...websetsTools,
+];
+
+/** Get Exa tools filtered by settings */
+export function getExaTools(settings: Required<ExaSettings>): CustomTool<any, ExaRenderDetails>[] {
+	if (!settings.enabled) return [];
+
+	const tools: CustomTool<any, ExaRenderDetails>[] = [];
+
+	if (settings.enableSearch) tools.push(...searchTools);
+	if (settings.enableLinkedin) tools.push(linkedinTool);
+	if (settings.enableCompany) tools.push(companyTool);
+	if (settings.enableResearcher) tools.push(...researcherTools);
+	if (settings.enableWebsets) tools.push(...websetsTools);
+
+	return tools;
+}
+
+export { companyTool } from "./company.js";
+export { linkedinTool } from "./linkedin.js";
+export { logExaError, logViewError } from "./logger.js";
+export {
+	callExaTool,
+	callWebsetsTool,
+	createMCPToolFromServer,
+	createMCPWrappedTool,
+	fetchMCPToolSchema,
+	findApiKey,
+	formatSearchResults,
+	isSearchResponse,
+} from "./mcp-client.js";
+export { renderExaCall, renderExaResult } from "./render.js";
+export { researcherTools } from "./researcher.js";
+// Re-export individual modules for selective importing
+export { searchTools } from "./search.js";
+// Re-export types and utilities
+export type { ExaRenderDetails, ExaSearchResponse, ExaSearchResult, MCPToolWrapperConfig } from "./types.js";
+export { websetsTools } from "./websets.js";

package/src/core/tools/exa/linkedin.ts

@@ -0,0 +1,59 @@
+/**
+ * Exa LinkedIn Tool
+ *
+ * Search LinkedIn for people, companies, and professional content.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { CustomTool } from "../../custom-tools/types.js";
+import type { ExaRenderDetails } from "./types.js";
+
+/** exa_linkedin - LinkedIn search */
+export const linkedinTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_linkedin",
+	label: "Exa LinkedIn",
+	description: `Search LinkedIn for people, companies, and professional content using Exa.
+
+Returns LinkedIn search results with profiles, posts, and company information.
+
+Parameters:
+- query: LinkedIn search query (e.g., "Software Engineer at OpenAI", "Y Combinator companies")`,
+
+	parameters: Type.Object({
+		query: Type.String({ description: "LinkedIn search query" }),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const { findApiKey, callExaTool, formatSearchResults, isSearchResponse } = await import("./mcp-client.js");
+
+			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_linkedin" },
+				};
+			}
+			const response = await callExaTool("linkedin_search_exa", params, apiKey);
+
+			if (isSearchResponse(response)) {
+				const formatted = formatSearchResults(response);
+				return {
+					content: [{ type: "text" as const, text: formatted }],
+					details: { response, toolName: "exa_linkedin" },
+				};
+			}
+
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+				details: { raw: response, toolName: "exa_linkedin" },
+			};
+		} 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_linkedin" },
+			};
+		}
+	},
+};

package/src/core/tools/exa/logger.ts

@@ -0,0 +1,56 @@
+/**
+ * Exa Error Logger
+ *
+ * Append-only logging to ~/.pi/ for debugging production issues.
+ */
+
+import { appendFileSync, existsSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { CONFIG_DIR_NAME } from "../../../config.js";
+
+/** Get the base config directory (e.g., ~/.pi/) */
+function getConfigDir(): string {
+	return join(homedir(), CONFIG_DIR_NAME);
+}
+
+/** Log file paths */
+const LOG_FILES = {
+	exa: "exa_errors.log",
+	view: "view_errors.log",
+} as const;
+
+type LogType = keyof typeof LOG_FILES;
+
+/** Format a log entry with timestamp */
+function formatEntry(message: string, context?: Record<string, unknown>): string {
+	const timestamp = new Date().toISOString();
+	const contextStr = context ? ` ${JSON.stringify(context)}` : "";
+	return `[${timestamp}] ${message}${contextStr}\n`;
+}
+
+/** Append to log file (creates directory if needed) */
+export function logError(type: LogType, message: string, context?: Record<string, unknown>): void {
+	try {
+		const configDir = getConfigDir();
+		if (!existsSync(configDir)) {
+			mkdirSync(configDir, { recursive: true });
+		}
+
+		const logPath = join(configDir, LOG_FILES[type]);
+		const entry = formatEntry(message, context);
+		appendFileSync(logPath, entry);
+	} catch {
+		// Silently ignore logging failures - we don't want to break tool execution
+	}
+}
+
+/** Log MCP fetch/call errors */
+export function logExaError(message: string, context?: Record<string, unknown>): void {
+	logError("exa", message, context);
+}
+
+/** Log render/view errors */
+export function logViewError(message: string, context?: Record<string, unknown>): void {
+	logError("view", message, context);
+}

package/src/core/tools/exa/mcp-client.ts

@@ -0,0 +1,368 @@
+/**
+ * Exa MCP Client
+ *
+ * Client for interacting with Exa MCP servers via JSON-RPC 2.0 over HTTPS.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type { CustomTool } from "../../custom-tools/types.js";
+import { logExaError } from "./logger.js";
+import type {
+	ExaRenderDetails,
+	ExaSearchResponse,
+	ExaSearchResult,
+	MCPCallResponse,
+	MCPTool,
+	MCPToolsResponse,
+	MCPToolWrapperConfig,
+} from "./types.js";
+
+/** Find EXA_API_KEY from process.env or .env files */
+export async function findApiKey(): Promise<string | null> {
+	// Check process.env first
+	if (process.env.EXA_API_KEY) {
+		return process.env.EXA_API_KEY;
+	}
+
+	// Try loading from .env files in cwd and home
+	const cwd = process.cwd();
+	const home = process.env.HOME ?? process.env.USERPROFILE ?? "~";
+
+	for (const dir of [cwd, home]) {
+		const envPath = `${dir}/.env`;
+		try {
+			const file = Bun.file(envPath);
+			if (await file.exists()) {
+				const content = await file.text();
+				const match = content.match(/^EXA_API_KEY=(.+)$/m);
+				if (match?.[1]) {
+					return match[1].trim().replace(/^["']|["']$/g, "");
+				}
+			}
+		} catch {
+			// Ignore read errors
+		}
+	}
+
+	return null;
+}
+
+/** Parse SSE response format (lines starting with "data: ") */
+function parseSSE(text: string): unknown {
+	const lines = text.split("\n");
+	for (const line of lines) {
+		if (line.startsWith("data: ")) {
+			const data = line.slice(6).trim();
+			if (data === "[DONE]") continue;
+			try {
+				return JSON.parse(data);
+			} catch {
+				// Try next line
+			}
+		}
+	}
+	// Fallback: try parsing entire response as JSON
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+/** Call MCP server with JSON-RPC 2.0 */
+export async function callMCP(url: string, method: string, params?: Record<string, unknown>): Promise<unknown> {
+	const body = {
+		jsonrpc: "2.0",
+		id: Math.random().toString(36).slice(2),
+		method,
+		params: params ?? {},
+	};
+
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify(body),
+	});
+
+	if (!response.ok) {
+		const errorMsg = `MCP request failed: ${response.status} ${response.statusText}`;
+		logExaError(errorMsg, { url, method, params });
+		throw new Error(errorMsg);
+	}
+
+	const text = await response.text();
+	const result = parseSSE(text);
+
+	if (!result) {
+		logExaError("Failed to parse MCP response", { url, method, responseText: text.slice(0, 500) });
+		throw new Error("Failed to parse MCP response");
+	}
+
+	return result;
+}
+
+/** 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) {
+		logExaError("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) {
+		logExaError("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) {
+		logExaError("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) {
+		logExaError("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 {
+		// Fall through to return null
+	}
+	return null;
+}
+
+/**
+ * Create a CustomTool dynamically 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 function createMCPWrappedTool(
+	config: MCPToolWrapperConfig,
+	schema: TSchema,
+	description: string,
+): CustomTool<TSchema, ExaRenderDetails> {
+	return {
+		name: config.name,
+		label: config.label,
+		description,
+		parameters: schema,
+		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: config.name },
+					};
+				}
+
+				const response = config.isWebsetsTool
+					? await callWebsetsTool(apiKey, config.mcpToolName, params as Record<string, unknown>)
+					: await callExaTool(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: config.name },
+					};
+				}
+
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+					details: { raw: response, toolName: 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: 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<CustomTool<TSchema, ExaRenderDetails>> {
+	const mcpTool = await fetchMCPToolSchema(apiKey, config.mcpToolName, config.isWebsetsTool);
+	const schema = mcpTool?.inputSchema ?? fallbackSchema;
+	const description = mcpTool?.description ?? fallbackDescription;
+	return createMCPWrappedTool(config, schema, description);
+}