@jarcelao/pi-exa-api 0.2.1 → 0.3.0

package/README.md

@@ -10,6 +10,9 @@ Install as a pi package:
 pi install npm:@jarcelao/pi-exa-api
 ```
 
+> [!NOTE]
+> This extension is tested up to `pi-coding-agent` v0.70.6
+
 ## Configuration
 
 Set your Exa API key as an environment variable before starting pi:

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 "@mariozechner/pi-coding-agent";
+import type { Theme } from "@mariozechner/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,66 @@
+/**
+ * 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 "@mariozechner/pi-coding-agent";
+
+import { getApiKey } from "./api-key.ts";
+import { createMissingApiKeyError } from "./errors.ts";
+import { mapSearchContentType, mapFetchContentType } from "./content-types.ts";
+import {
+  formatSearchResults,
+  formatFetchResult,
+  formatCodeContextResult,
+  parseCostDollars,
+} from "./formatters.ts";
+
+import { createExaSearchTool } from "./tools/search.ts";
+import { createExaFetchTool } from "./tools/fetch.ts";
+import { createExaCodeContextTool } from "./tools/code-context.ts";
+
+// Re-export all utilities for testing
+export {
+  getApiKey,
+  createMissingApiKeyError,
+  mapSearchContentType,
+  mapFetchContentType,
+  formatSearchResults,
+  formatFetchResult,
+  formatCodeContextResult,
+  parseCostDollars,
+};
+
+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/temp-file.ts

@@ -0,0 +1,19 @@
+/**
+ * Temp file utilities
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Write content to a temporary file.
+ * @param content - The content to write
+ * @returns The path to the created temporary file
+ */
+export async function writeTempFile(content: string): Promise<string> {
+  const tempDir = await mkdtemp(join(tmpdir(), "pi-exa-"));
+  const tempFile = join(tempDir, "output.txt");
+  await writeFile(tempFile, content, "utf8");
+  return tempFile;
+}

package/extensions/tools/code-context.ts

@@ -0,0 +1,163 @@
+/**
+ * Exa Code Context tool definition
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  defineTool,
+  formatSize,
+  truncateHead,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type, type Static } from "typebox";
+
+import { getApiKey } from "../api-key.ts";
+import { createMissingApiKeyError } from "../errors.ts";
+import {
+  formatCodeContextResult,
+  formatToolOutputPreview,
+  parseCostDollars,
+} from "../formatters.ts";
+import type { CodeContextDetails, CodeContextResponse } from "../types.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 = getApiKey();
+      if (!apiKey) {
+        throw createMissingApiKeyError();
+      }
+
+      // Ensure tokensNum is the correct type: number or "dynamic"
+      // The schema accepts both string and number, but the Exa API requires:
+      // - A number (e.g., 5000)
+      // - The literal string "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("https://api.exa.ai/context", {
+          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}`);
+      }
+
+      let output = formatCodeContextResult(response);
+
+      const truncation = truncateHead(output, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+      });
+
+      let result = truncation.content;
+
+      if (truncation.truncated) {
+        const tempDir = await mkdtemp(join(tmpdir(), "pi-exa-"));
+        const tempFile = join(tempDir, "output.txt");
+        await writeFile(tempFile, output, "utf8");
+        result += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;
+        result += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
+        result += ` Full output saved to: ${tempFile}]`;
+      }
+
+      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 preview = args.query.length > 50 ? args.query.slice(0, 50) + "..." : args.query;
+      const desc = `${args.tokensNum ?? "dynamic"} tokens`;
+      const text =
+        theme.fg("toolTitle", theme.bold("exa_code_context ")) +
+        theme.fg("muted", preview) +
+        theme.fg("dim", ` ${desc}`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, options, theme, context) {
+      const details = result.details as CodeContextDetails | undefined;
+      const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+
+      let header = "";
+      if (details) {
+        const cost = details.cost ? ` • $${details.cost.total.toFixed(6)}` : "";
+        header = theme.fg(
+          "success",
+          `✓ ${details.resultsCount} sources • ${details.outputTokens} tokens${cost}`,
+        );
+      }
+
+      const preview = formatToolOutputPreview(result, options, theme);
+      text.setText(preview ? `${header}\n${preview}` : header);
+      return text;
+    },
+  });
+}

package/extensions/tools/fetch.ts

@@ -0,0 +1,154 @@
+/**
+ * Exa Fetch tool definition
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  defineTool,
+  formatSize,
+  truncateHead,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type, type Static } from "typebox";
+import Exa from "exa-js";
+
+import { getApiKey } from "../api-key.ts";
+import { createMissingApiKeyError } from "../errors.ts";
+import { mapFetchContentType } from "../content-types.ts";
+import { formatFetchResult, formatToolOutputPreview } from "../formatters.ts";
+import type { FetchContentType, FetchDetails, ExaSearchResult } from "../types.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 = getApiKey();
+      if (!apiKey) {
+        throw createMissingApiKeyError();
+      }
+
+      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;
+      let output = formatFetchResult(result, (params.contentType ?? "text") as FetchContentType);
+
+      const truncation = truncateHead(output, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+      });
+
+      let content = truncation.content;
+
+      if (truncation.truncated) {
+        const tempDir = await mkdtemp(join(tmpdir(), "pi-exa-"));
+        const tempFile = join(tempDir, "output.txt");
+        await writeFile(tempFile, output, "utf8");
+        content += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;
+        content += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
+        content += ` Full output saved to: ${tempFile}]`;
+      }
+
+      return {
+        content: [{ type: "text", text: content }],
+        details: {
+          url: params.url,
+          title: result.title,
+          cost: response.costDollars,
+        } as FetchDetails,
+      };
+    },
+
+    renderCall(args: FetchParams, theme: Theme) {
+      const urlPreview = args.url.length > 40 ? args.url.slice(0, 40) + "..." : args.url;
+      const desc = args.contentType ?? "text";
+      const text =
+        theme.fg("toolTitle", theme.bold("exa_fetch ")) +
+        theme.fg("muted", urlPreview) +
+        theme.fg("dim", ` ${desc}`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, options, theme, context) {
+      const details = result.details as FetchDetails | undefined;
+      const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+
+      let header = "";
+      if (details) {
+        const cost = details.cost ? ` • $${details.cost.total.toFixed(6)}` : "";
+        header = details.title
+          ? theme.fg("success", `✓ ${details.title}${cost}`)
+          : theme.fg("success", `✓ Fetched${cost}`);
+      }
+
+      const preview = formatToolOutputPreview(result, options, theme);
+      text.setText(preview ? `${header}\n${preview}` : header);
+      return text;
+    },
+  });
+}