@@ -0,0 +1,340 @@
1+import { mkdtemp, writeFile } from "node:fs/promises";
2+import { tmpdir } from "node:os";
3+import path from "node:path";
4+import { StringEnum } from "@earendil-works/pi-ai";
5+import {
6+ DEFAULT_MAX_BYTES,
7+ DEFAULT_MAX_LINES,
8+ formatSize,
9+ truncateHead,
10+ type ExtensionAPI,
11+ withFileMutationQueue,
12+} from "@earendil-works/pi-coding-agent";
13+import { Type } from "typebox";
14+
15+const EXA_SEARCH_URL = "https://api.exa.ai/search";
16+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
17+const MCP_PROTOCOL_VERSION = "2025-06-18";
18+const SEARCH_TYPES = [
19+ "auto",
20+ "fast",
21+ "instant",
22+ "deep-lite",
23+ "deep",
24+ "deep-reasoning",
25+] as const;
26+
27+const SearchParams = Type.Object({
28+ query: Type.String({ description: "Natural-language web search query" }),
29+ type: Type.Optional(
30+ StringEnum(SEARCH_TYPES, {
31+ description:
32+ "Search depth and latency tradeoff (default: auto). Deep types require EXA_API_KEY.",
33+ }),
34+ ),
35+ numResults: Type.Optional(
36+ Type.Integer({
37+ minimum: 1,
38+ maximum: 10,
39+ description: "Number of results to return (default: 10)",
40+ }),
41+ ),
42+});
43+
44+interface ExaResponse {
45+ requestId?: string;
46+ resolvedSearchType?: string;
47+ results?: unknown[];
48+ costDollars?: unknown;
49+}
50+
51+interface JsonRpcResponse {
52+ jsonrpc: "2.0";
53+ id?: number;
54+ result?: unknown;
55+ error?: { code: number; message: string };
56+}
57+
58+interface McpToolResult {
59+ content?: Array<{ type: string; text?: string }>;
60+ isError?: boolean;
61+}
62+
63+function apiError(body: string): string {
64+ try {
65+ const parsed = JSON.parse(body) as { error?: unknown };
66+ if (typeof parsed.error === "string") return parsed.error;
67+ if (
68+ isRecord(parsed.error) &&
69+ typeof parsed.error.message === "string"
70+ ) {
71+ return parsed.error.message;
72+ }
73+ } catch {
74+ // Fall back to the response body below.
75+ }
76+ return body.trim() || "Empty response";
77+}
78+
79+function isRecord(value: unknown): value is Record<string, unknown> {
80+ return typeof value === "object" && value !== null && !Array.isArray(value);
81+}
82+
83+function parseMcpResponse(
84+ body: string,
85+ contentType: string,
86+ requestId: number,
87+): JsonRpcResponse {
88+ const candidates = contentType.includes("text/event-stream")
89+ ? body
90+ .split("\n")
91+ .filter((line) => line.startsWith("data:"))
92+ .map((line) => line.slice(5).trim())
93+ : [body];
94+
95+ for (const candidate of candidates.reverse()) {
96+ if (!candidate || candidate === "[DONE]") continue;
97+ try {
98+ const parsed = JSON.parse(candidate) as JsonRpcResponse;
99+ if (parsed.jsonrpc === "2.0" && parsed.id === requestId) return parsed;
100+ } catch {
101+ // Ignore non-JSON SSE data and continue looking for our response.
102+ }
103+ }
104+ throw new Error("Exa MCP returned no matching JSON-RPC response");
105+}
106+
107+async function mcpRequest(
108+ endpoint: string,
109+ requestId: number,
110+ method: string,
111+ params: Record<string, unknown>,
112+ sessionId: string | undefined,
113+ signal: AbortSignal | undefined,
114+): Promise<{ response: JsonRpcResponse; sessionId?: string }> {
115+ const headers: Record<string, string> = {
116+ "Content-Type": "application/json",
117+ Accept: "application/json, text/event-stream",
118+ };
119+ if (sessionId) headers["Mcp-Session-Id"] = sessionId;
120+
121+ const httpResponse = await fetch(endpoint, {
122+ method: "POST",
123+ headers,
124+ body: JSON.stringify({
125+ jsonrpc: "2.0",
126+ id: requestId,
127+ method,
128+ params,
129+ }),
130+ signal,
131+ });
132+ const body = await httpResponse.text();
133+ if (!httpResponse.ok) {
134+ throw new Error(
135+ `Exa MCP failed (${httpResponse.status} ${httpResponse.statusText}): ${apiError(body)}`,
136+ );
137+ }
138+
139+ const response = parseMcpResponse(
140+ body,
141+ httpResponse.headers.get("Content-Type") ?? "",
142+ requestId,
143+ );
144+ if (response.error) {
145+ throw new Error(
146+ `Exa MCP error ${response.error.code}: ${response.error.message}`,
147+ );
148+ }
149+ return {
150+ response,
151+ sessionId:
152+ httpResponse.headers.get("Mcp-Session-Id") ?? sessionId ?? undefined,
153+ };
154+}
155+
156+async function notifyMcpInitialized(
157+ endpoint: string,
158+ sessionId: string,
159+ signal: AbortSignal | undefined,
160+): Promise<void> {
161+ const response = await fetch(endpoint, {
162+ method: "POST",
163+ headers: {
164+ "Content-Type": "application/json",
165+ Accept: "application/json, text/event-stream",
166+ "Mcp-Session-Id": sessionId,
167+ },
168+ body: JSON.stringify({
169+ jsonrpc: "2.0",
170+ method: "notifications/initialized",
171+ params: {},
172+ }),
173+ signal,
174+ });
175+ if (!response.ok) {
176+ throw new Error(
177+ `Exa MCP initialization failed (${response.status} ${response.statusText}): ${await response.text()}`,
178+ );
179+ }
180+ await response.text();
181+}
182+
183+async function searchAnonymously(
184+ query: string,
185+ numResults: number,
186+ searchType: (typeof SEARCH_TYPES)[number],
187+ signal: AbortSignal | undefined,
188+): Promise<string> {
189+ if (
190+ searchType !== "auto" &&
191+ searchType !== "fast" &&
192+ searchType !== "instant"
193+ ) {
194+ throw new Error(
195+ `Anonymous Exa search does not support type "${searchType}"; set EXA_API_KEY to use deep search types`,
196+ );
197+ }
198+
199+ const endpoint = new URL(EXA_MCP_URL);
200+ endpoint.searchParams.set("tools", "web_search_exa");
201+ endpoint.searchParams.set("defaultSearchType", searchType);
202+
203+ const initialized = await mcpRequest(
204+ endpoint.toString(),
205+ 1,
206+ "initialize",
207+ {
208+ protocolVersion: MCP_PROTOCOL_VERSION,
209+ capabilities: {},
210+ clientInfo: { name: "pi-exa-extension", version: "1.0.0" },
211+ },
212+ undefined,
213+ signal,
214+ );
215+ if (!initialized.sessionId) {
216+ throw new Error("Exa MCP did not return a session ID");
217+ }
218+ await notifyMcpInitialized(endpoint.toString(), initialized.sessionId, signal);
219+
220+ const called = await mcpRequest(
221+ endpoint.toString(),
222+ 2,
223+ "tools/call",
224+ {
225+ name: "web_search_exa",
226+ arguments: { query, numResults },
227+ },
228+ initialized.sessionId,
229+ signal,
230+ );
231+ if (!isRecord(called.response.result)) {
232+ throw new Error("Exa MCP returned an invalid tool result");
233+ }
234+ const result = called.response.result as McpToolResult;
235+ const text = (result.content ?? [])
236+ .filter(
237+ (block): block is { type: string; text: string } =>
238+ block.type === "text" && typeof block.text === "string",
239+ )
240+ .map((block) => block.text)
241+ .join("\n")
242+ .trim();
243+ if (result.isError) throw new Error(text || "Exa MCP search failed");
244+ return text || "No results found.";
245+}
246+
247+export default function exaExtension(pi: ExtensionAPI): void {
248+ pi.registerTool({
249+ name: "exa_search",
250+ label: "Exa Search",
251+ description: `Search the web with Exa and return URLs plus relevant highlights. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}. Uses the Exa API with EXA_API_KEY, or Exa's free hosted MCP service anonymously.`,
252+ promptSnippet: "Search the web with Exa and return relevant excerpts and source URLs",
253+ promptGuidelines: [
254+ "Use exa_search for current information and web research, and cite the returned source URLs in the answer.",
255+ ],
256+ parameters: SearchParams,
257+ async execute(_toolCallId, params, signal) {
258+ const apiKey = process.env.EXA_API_KEY?.trim();
259+ const searchType = params.type ?? "auto";
260+ const numResults = params.numResults ?? 10;
261+ let output: string;
262+ let details: Record<string, unknown>;
263+
264+ if (apiKey) {
265+ const response = await fetch(EXA_SEARCH_URL, {
266+ method: "POST",
267+ headers: {
268+ "Content-Type": "application/json",
269+ Authorization: `Bearer ${apiKey}`,
270+ },
271+ body: JSON.stringify({
272+ query: params.query,
273+ type: searchType,
274+ numResults,
275+ contents: { highlights: true },
276+ }),
277+ signal,
278+ });
279+ const body = await response.text();
280+ if (!response.ok) {
281+ throw new Error(
282+ `Exa search failed (${response.status} ${response.statusText}): ${apiError(body)}`,
283+ );
284+ }
285+
286+ let data: ExaResponse;
287+ try {
288+ data = JSON.parse(body) as ExaResponse;
289+ } catch {
290+ throw new Error("Exa returned an invalid JSON response");
291+ }
292+ if (!Array.isArray(data.results)) {
293+ throw new Error("Exa response did not include a results array");
294+ }
295+ output = JSON.stringify(data, null, 2);
296+ details = {
297+ backend: "api",
298+ requestId: data.requestId,
299+ requestedSearchType: searchType,
300+ resolvedSearchType: data.resolvedSearchType,
301+ resultCount: data.results.length,
302+ costDollars: data.costDollars,
303+ };
304+ } else {
305+ output = await searchAnonymously(
306+ params.query,
307+ numResults,
308+ searchType,
309+ signal,
310+ );
311+ details = {
312+ backend: "mcp-free",
313+ requestedSearchType: searchType,
314+ };
315+ }
316+
317+ const truncation = truncateHead(output, {
318+ maxLines: DEFAULT_MAX_LINES,
319+ maxBytes: DEFAULT_MAX_BYTES,
320+ });
321+ let text = truncation.content;
322+ let fullOutputPath: string | undefined;
323+
324+ if (truncation.truncated) {
325+ const directory = await mkdtemp(path.join(tmpdir(), "pi-exa-"));
326+ const tempFile = path.join(directory, "results.txt");
327+ fullOutputPath = tempFile;
328+ await withFileMutationQueue(tempFile, () =>
329+ writeFile(tempFile, output, "utf8"),
330+ );
331+ text += `\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full output saved to: ${fullOutputPath}]`;
332+ }
333+
334+ return {
335+ content: [{ type: "text", text }],
336+ details: { ...details, fullOutputPath },
337+ };
338+ },
339+ });
340+}