@jarcelao/pi-exa-api 0.2.2 → 0.3.1

package/README.md

@@ -11,7 +11,7 @@ pi install npm:@jarcelao/pi-exa-api
 ```
 
 > [!NOTE]
-> This extension is compatible with `pi-coding-agent` v0.69.0
+> This extension is tested up to `pi-coding-agent` v0.74.0
 
 ## Configuration
 

package/extensions/api-key.ts

@@ -0,0 +1,12 @@
+/**
+ * API Key Management
+ */
+
+/**
+ * Get the Exa API key from environment variables.
+ * @returns The API key if set and non-empty, undefined otherwise.
+ */
+export function getApiKey(): string | undefined {
+  const key = process.env.EXA_API_KEY;
+  return key && key.length > 0 ? key : undefined;
+}

package/extensions/content-types.ts

@@ -0,0 +1,43 @@
+/**
+ * Content type mapping utilities
+ */
+
+import type { SearchContentType, FetchContentType } from "./types.ts";
+
+/**
+ * Map search content type string to Exa API contents option.
+ */
+export function mapSearchContentType(
+  contentType?: SearchContentType,
+): { text?: true; highlights?: true; summary?: true } | undefined {
+  switch (contentType) {
+    case "text":
+      return { text: true };
+    case "highlights":
+      return { highlights: true };
+    case "summary":
+      return { summary: true };
+    case "none":
+      return undefined;
+    default:
+      return { highlights: true };
+  }
+}
+
+/**
+ * Map fetch content type string to Exa API contents option.
+ */
+export function mapFetchContentType(
+  contentType?: FetchContentType,
+): { text?: true; highlights?: true; summary?: true } | undefined {
+  switch (contentType) {
+    case "text":
+      return { text: true };
+    case "highlights":
+      return { highlights: true };
+    case "summary":
+      return { summary: true };
+    default:
+      return { text: true };
+  }
+}

package/extensions/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * Error creation utilities
+ */
+
+/**
+ * Create an error for missing API key configuration.
+ */
+export function createMissingApiKeyError(): Error {
+  return new Error(
+    "Exa API key not configured. Set EXA_API_KEY environment variable before starting pi.",
+  );
+}

package/extensions/formatters.ts

@@ -0,0 +1,167 @@
+/**
+ * Result formatting utilities
+ */
+
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type {
+  ExaSearchResult,
+  ExaSearchResponse,
+  CodeContextResponse,
+  FetchContentType,
+} from "./types.ts";
+
+/**
+ * Format search results into a readable string.
+ */
+export function formatSearchResults(response: ExaSearchResponse): string {
+  const { results, costDollars } = response;
+  const lines: string[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    lines.push(`--- Result ${i + 1} ---`);
+    lines.push(`Title: ${result.title}`);
+    lines.push(`URL: ${result.url}`);
+
+    if (result.publishedDate) {
+      lines.push(`Published: ${result.publishedDate}`);
+    }
+    if (result.author) {
+      lines.push(`Author: ${result.author}`);
+    }
+
+    if (result.highlights && result.highlights.length > 0) {
+      lines.push("Highlights:");
+      for (const highlight of result.highlights) {
+        lines.push(`  • ${highlight}`);
+      }
+    }
+
+    if (result.text) {
+      const preview = result.text.slice(0, 500);
+      lines.push(`Text: ${preview}${result.text.length > 500 ? "..." : ""}`);
+    }
+
+    if (result.summary) {
+      lines.push(`Summary: ${result.summary}`);
+    }
+
+    lines.push("");
+  }
+
+  if (costDollars) {
+    lines.push(`Cost: $${costDollars.total.toFixed(6)}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format a fetch result into a readable string.
+ */
+export function formatFetchResult(result: ExaSearchResult, contentType: FetchContentType): string {
+  const lines: string[] = [];
+
+  if (result.title) {
+    lines.push(`Title: ${result.title}`);
+  }
+  lines.push(`URL: ${result.url}`);
+  lines.push("");
+
+  switch (contentType) {
+    case "text":
+      if (result.text) {
+        lines.push(result.text);
+      }
+      break;
+    case "highlights":
+      if (result.highlights && result.highlights.length > 0) {
+        lines.push("Highlights:");
+        for (const h of result.highlights) {
+          lines.push(`  • ${h}`);
+        }
+      }
+      break;
+    case "summary":
+      if (result.summary) {
+        lines.push("Summary:");
+        lines.push(result.summary);
+      }
+      break;
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Parse cost dollars from either a JSON string or object.
+ */
+export function parseCostDollars(costDollars: string | { total: number }): { total: number } {
+  if (typeof costDollars === "string") {
+    return JSON.parse(costDollars);
+  }
+  return costDollars;
+}
+
+/**
+ * Format a preview of tool output for TUI display.
+ * Shows up to 10 lines when collapsed, full output when expanded.
+ */
+export function formatToolOutputPreview(
+  result: { content: Array<{ type: string; text?: string }> },
+  options: { expanded: boolean },
+  theme: Theme,
+): string {
+  const textBlocks = result.content
+    .filter((c): c is { type: "text"; text: string } => c.type === "text")
+    .map((c) => c.text || "");
+
+  if (textBlocks.length === 0) {
+    return "";
+  }
+
+  const output = textBlocks.join("\n");
+  const lines = output.split("\n");
+
+  // Trim trailing empty lines
+  let end = lines.length;
+  while (end > 0 && lines[end - 1] === "") {
+    end--;
+  }
+  const trimmedLines = lines.slice(0, end);
+
+  const maxLines = options.expanded ? trimmedLines.length : 10;
+  const displayLines = trimmedLines.slice(0, maxLines);
+  const remaining = trimmedLines.length - maxLines;
+
+  let text = displayLines.map((line) => theme.fg("toolOutput", line)).join("\n");
+
+  if (remaining > 0) {
+    text += `\n${theme.fg("muted", `... (${remaining} more lines, ${keyHint("app.tools.expand", "to expand")})`)}`;
+  }
+
+  return text;
+}
+
+/**
+ * Format code context response into a readable string.
+ */
+export function formatCodeContextResult(response: CodeContextResponse): string {
+  const lines: string[] = [];
+
+  lines.push(`Query: ${response.query}`);
+  lines.push(`Results: ${response.resultsCount} sources`);
+  lines.push(`Output tokens: ${response.outputTokens}`);
+  lines.push("");
+  lines.push("--- Code Context ---");
+  lines.push("");
+  lines.push(response.response);
+  lines.push("");
+
+  const cost = parseCostDollars(response.costDollars);
+  lines.push(`Cost: $${cost.total.toFixed(6)}`);
+
+  return lines.join("\n");
+}

package/extensions/index.ts

@@ -0,0 +1,46 @@
+/**
+ * exa-search Extension
+ *
+ * Registers three tools for web search, content fetching, and code context using the Exa API:
+ * - exa_search: Natural language web search
+ * - exa_fetch: Fetch and extract content from URLs
+ * - exa_code_context: Search for code snippets and examples from open source repos
+ *
+ * Also registers the /exa-status command to check API key configuration.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { getApiKey } from "./api-key.ts";
+
+import { createExaSearchTool } from "./tools/search.ts";
+import { createExaFetchTool } from "./tools/fetch.ts";
+import { createExaCodeContextTool } from "./tools/code-context.ts";
+
+export default function exaSearchExtension(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+    const hasKey = !!getApiKey();
+    if (!hasKey) {
+      ctx.ui.notify("Exa API key not configured. Set EXA_API_KEY to enable search.", "warning");
+    }
+  });
+
+  // Register tools
+  pi.registerTool(createExaSearchTool());
+  pi.registerTool(createExaFetchTool());
+  pi.registerTool(createExaCodeContextTool());
+
+  // Register /exa-status command
+  pi.registerCommand("exa-status", {
+    description: "Check Exa API key configuration status",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const configured = !!getApiKey();
+      ctx.ui.notify(
+        configured
+          ? "Exa API key: configured via EXA_API_KEY"
+          : "Exa API key: not configured. Set EXA_API_KEY environment variable.",
+        configured ? "info" : "warning",
+      );
+    },
+  });
+}

package/extensions/tools/code-context.ts

@@ -0,0 +1,122 @@
+/**
+ * Exa Code Context tool definition
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+
+import { formatCodeContextResult, parseCostDollars } from "../formatters.ts";
+import type { CodeContextDetails, CodeContextResponse } from "../types.ts";
+import {
+  requireApiKey,
+  truncateAndSave,
+  renderToolCall,
+  renderToolResult,
+  formatCost,
+  EXA_CONTEXT_API_URL,
+} from "./shared.ts";
+
+// Tool parameter schema
+export const ExaCodeContextParams = Type.Object({
+  query: Type.String({
+    description: "Search query to find relevant code snippets and examples",
+  }),
+  tokensNum: Type.Optional(
+    Type.Union([
+      Type.String({
+        description: 'Token limit: "dynamic" for automatic sizing',
+      }),
+      Type.Number({
+        description: "Token limit: 50-100000 (5000 is a good default)",
+      }),
+    ]),
+  ),
+});
+
+type CodeContextParams = Static<typeof ExaCodeContextParams>;
+
+/**
+ * Create the exa_code_context tool definition.
+ */
+export function createExaCodeContextTool() {
+  return defineTool({
+    name: "exa_code_context",
+    label: "Exa Code Context",
+    description:
+      "Search for code snippets and examples from open source libraries and repositories. Use this to find working code examples that help understand how libraries, frameworks, or concepts are implemented.",
+    parameters: ExaCodeContextParams,
+
+    async execute(
+      _toolCallId: string,
+      params: CodeContextParams,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown,
+    ) {
+      const apiKey = requireApiKey();
+
+      // Ensure tokensNum is the correct type: number or "dynamic"
+      let tokensNum: string | number = params.tokensNum ?? "dynamic";
+      if (typeof tokensNum === "string" && tokensNum !== "dynamic") {
+        tokensNum = Number(tokensNum);
+      }
+
+      let response: CodeContextResponse;
+      try {
+        const httpResponse = await fetch(EXA_CONTEXT_API_URL, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": apiKey,
+          },
+          body: JSON.stringify({
+            query: params.query,
+            tokensNum,
+          }),
+        });
+
+        if (!httpResponse.ok) {
+          const errorText = await httpResponse.text();
+          throw new Error(`HTTP ${httpResponse.status}: ${errorText}`);
+        }
+
+        response = (await httpResponse.json()) as CodeContextResponse;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Exa Context API error: ${message}`);
+      }
+
+      const output = formatCodeContextResult(response);
+      const result = await truncateAndSave(output);
+      const cost = parseCostDollars(response.costDollars);
+
+      return {
+        content: [{ type: "text", text: result }],
+        details: {
+          query: params.query,
+          resultsCount: response.resultsCount,
+          outputTokens: response.outputTokens,
+          cost,
+        } as CodeContextDetails,
+      };
+    },
+
+    renderCall(args: CodeContextParams, theme: Theme) {
+      const desc = `${args.tokensNum ?? "dynamic"} tokens`;
+      return renderToolCall("exa_code_context", args.query, desc, theme);
+    },
+
+    renderResult(result, options, theme, context) {
+      const details = result.details as CodeContextDetails | undefined;
+      const cost = details ? formatCost(details.cost) : "";
+      const header = details
+        ? theme.fg(
+            "success",
+            `✓ ${details.resultsCount} sources • ${details.outputTokens} tokens${cost}`,
+          )
+        : "";
+      return renderToolResult(header, result, options, theme, context);
+    },
+  });
+}

package/extensions/tools/fetch.ts

@@ -0,0 +1,119 @@
+/**
+ * Exa Fetch tool definition
+ */
+
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import Exa from "exa-js";
+
+import { mapFetchContentType } from "../content-types.ts";
+import { formatFetchResult } from "../formatters.ts";
+import type { FetchContentType, FetchDetails, ExaSearchResult } from "../types.ts";
+import {
+  requireApiKey,
+  truncateAndSave,
+  renderToolCall,
+  renderToolResult,
+  formatCost,
+} from "./shared.ts";
+
+// Tool parameter schema
+export const ExaFetchParams = Type.Object({
+  url: Type.String({
+    description: "URL to fetch content from",
+  }),
+  contentType: Type.Optional(
+    Type.Union([Type.Literal("text"), Type.Literal("highlights"), Type.Literal("summary")]),
+  ),
+  maxCharacters: Type.Optional(
+    Type.Number({
+      description: "Maximum characters to return",
+    }),
+  ),
+});
+
+type FetchParams = Static<typeof ExaFetchParams>;
+
+/**
+ * Create the exa_fetch tool definition.
+ */
+export function createExaFetchTool() {
+  return defineTool({
+    name: "exa_fetch",
+    label: "Exa Fetch",
+    description:
+      "Fetch and extract content from a specific URL using Exa. Can return full text, highlights, or AI-generated summary.",
+    parameters: ExaFetchParams,
+
+    async execute(
+      _toolCallId: string,
+      params: FetchParams,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: ExtensionContext,
+    ) {
+      const apiKey = requireApiKey();
+      const exa = new Exa(apiKey);
+
+      const contentsOptions: {
+        text?: true;
+        highlights?: true;
+        summary?: true;
+        maxCharacters?: number;
+      } = {};
+
+      const mappedContent = mapFetchContentType(params.contentType as FetchContentType | undefined);
+      if (mappedContent?.text) contentsOptions.text = true;
+      if (mappedContent?.highlights) contentsOptions.highlights = true;
+      if (mappedContent?.summary) contentsOptions.summary = true;
+      if (params.maxCharacters) {
+        contentsOptions.maxCharacters = Math.max(1000, Math.min(100000, params.maxCharacters));
+      }
+
+      let response;
+      try {
+        response = await exa.getContents(params.url, contentsOptions);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Exa API error: ${message}`);
+      }
+
+      if (!response.results || response.results.length === 0) {
+        return {
+          content: [{ type: "text", text: "No content found at this URL." }],
+          details: { url: params.url, cost: response.costDollars } as FetchDetails,
+        };
+      }
+
+      const result = response.results[0] as ExaSearchResult;
+      const output = formatFetchResult(result, (params.contentType ?? "text") as FetchContentType);
+      const content = await truncateAndSave(output);
+
+      return {
+        content: [{ type: "text", text: content }],
+        details: {
+          url: params.url,
+          title: result.title,
+          cost: response.costDollars,
+        } as FetchDetails,
+      };
+    },
+
+    renderCall(args: FetchParams, theme: Theme) {
+      const desc = args.contentType ?? "text";
+      return renderToolCall("exa_fetch", args.url, desc, theme);
+    },
+
+    renderResult(result, options, theme, context) {
+      const details = result.details as FetchDetails | undefined;
+      const cost = details ? formatCost(details.cost) : "";
+      const header = details
+        ? details.title
+          ? theme.fg("success", `✓ ${details.title}${cost}`)
+          : theme.fg("success", `✓ Fetched${cost}`)
+        : "";
+      return renderToolResult(header, result, options, theme, context);
+    },
+  });
+}

package/extensions/tools/search.ts

@@ -0,0 +1,112 @@
+/**
+ * Exa Search tool definition
+ */
+
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import Exa from "exa-js";
+
+import { mapSearchContentType } from "../content-types.ts";
+import { formatSearchResults } from "../formatters.ts";
+import type { SearchContentType, SearchDetails, ExaSearchResult } from "../types.ts";
+import {
+  requireApiKey,
+  truncateAndSave,
+  renderToolCall,
+  renderToolResult,
+  formatCost,
+} from "./shared.ts";
+
+// Tool parameter schema
+export const ExaSearchParams = Type.Object({
+  query: Type.String({
+    description: "Natural language search query",
+  }),
+  contentType: Type.Optional(
+    Type.Union([
+      Type.Literal("text"),
+      Type.Literal("highlights"),
+      Type.Literal("summary"),
+      Type.Literal("none"),
+    ]),
+  ),
+  numResults: Type.Optional(
+    Type.Number({
+      description: "Number of results (1-100)",
+    }),
+  ),
+});
+
+type SearchParams = Static<typeof ExaSearchParams>;
+
+/**
+ * Create the exa_search tool definition.
+ */
+export function createExaSearchTool() {
+  return defineTool({
+    name: "exa_search",
+    label: "Exa Search",
+    description:
+      "Search the web using Exa's neural search API. Best for factual queries, research, and finding relevant web content. Use highlights mode by default for token efficiency.",
+    parameters: ExaSearchParams,
+
+    async execute(
+      _toolCallId: string,
+      params: SearchParams,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: ExtensionContext,
+    ) {
+      const apiKey = requireApiKey();
+      const numResults = Math.max(1, Math.min(100, params.numResults ?? 10));
+      const exa = new Exa(apiKey);
+
+      const contents = mapSearchContentType(params.contentType as SearchContentType | undefined);
+      const searchOptions: {
+        numResults: number;
+        contents?: { text?: true; highlights?: true; summary?: true };
+      } = { numResults };
+
+      if (contents) {
+        searchOptions.contents = contents;
+      }
+
+      let response;
+      try {
+        response = await exa.search(params.query, searchOptions);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Exa API error: ${message}`);
+      }
+
+      const output = formatSearchResults({
+        results: response.results as ExaSearchResult[],
+        costDollars: response.costDollars as { total: number } | undefined,
+      });
+
+      const result = await truncateAndSave(output);
+
+      return {
+        content: [{ type: "text", text: result }],
+        details: {
+          query: params.query,
+          numResults: response.results.length,
+          cost: response.costDollars,
+        } as SearchDetails,
+      };
+    },
+
+    renderCall(args: SearchParams, theme: Theme) {
+      const desc = `${args.numResults ?? 10} results • ${args.contentType ?? "highlights"}`;
+      return renderToolCall("exa_search", args.query, desc, theme);
+    },
+
+    renderResult(result, options, theme, context) {
+      const details = result.details as SearchDetails | undefined;
+      const cost = details ? formatCost(details.cost) : "";
+      const header = details ? theme.fg("success", `✓ ${details.numResults} results${cost}`) : "";
+      return renderToolResult(header, result, options, theme, context);
+    },
+  });
+}