@jarcelao/pi-exa-api 0.2.2 → 0.3.1

package/extensions/tools/shared.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared utilities for Exa tools
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import { getApiKey } from "../api-key.ts";
+import { createMissingApiKeyError } from "../errors.ts";
+import { formatToolOutputPreview } from "../formatters.ts";
+
+/** Exa Context API base URL */
+export const EXA_CONTEXT_API_URL = "https://api.exa.ai/context";
+
+/**
+ * Require an API key to be configured, throwing if missing.
+ * @returns The API key
+ */
+export function requireApiKey(): string {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw createMissingApiKeyError();
+  }
+  return apiKey;
+}
+
+/**
+ * Truncate output and save to temp file if needed.
+ * @param output - The full output string
+ * @returns Object with the (possibly truncated) content string
+ */
+export async function truncateAndSave(output: string): Promise<string> {
+  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;
+}
+
+/**
+ * Format the tool call preview for TUI display.
+ * @param label - The tool label (e.g., "exa_search")
+ * @param preview - The main preview text
+ * @param desc - The description text
+ * @param theme - The theme object
+ */
+export function renderToolCall(label: string, preview: string, desc: string, theme: Theme): Text {
+  const truncatedPreview = preview.length > 50 ? preview.slice(0, 50) + "..." : preview;
+  const text =
+    theme.fg("toolTitle", theme.bold(`${label} `)) +
+    theme.fg("muted", truncatedPreview) +
+    theme.fg("dim", ` ${desc}`);
+  return new Text(text, 0, 0);
+}
+
+/**
+ * Format the tool result for TUI display with optional header and preview.
+ * @param details - The details object with optional cost info
+ * @param headerText - The header text to display
+ * @param result - The full result object
+ * @param options - The display options
+ * @param theme - The theme object
+ * @param context - The context object
+ */
+export function renderToolResult(
+  headerText: string,
+  result: { content: Array<{ type: string; text?: string }> },
+  options: { expanded: boolean },
+  theme: Theme,
+  context: { lastComponent?: unknown },
+): Text {
+  const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+  const preview = formatToolOutputPreview(result, options, theme);
+  text.setText(preview ? `${headerText}\n${preview}` : headerText);
+  return text;
+}
+
+/**
+ * Format cost for display.
+ * @param cost - Cost object with total property
+ * @returns Formatted cost string or empty string
+ */
+export function formatCost(cost?: { total: number }): string {
+  return cost ? ` • $${cost.total.toFixed(6)}` : "";
+}

package/extensions/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Type definitions for Exa API extension
+ */
+
+// Content type options
+export type SearchContentType = "text" | "highlights" | "summary" | "none";
+export type FetchContentType = "text" | "highlights" | "summary";
+
+// Search result types
+export interface ExaSearchResult {
+  title: string;
+  url: string;
+  publishedDate?: string | null;
+  author?: string | null;
+  text?: string;
+  highlights?: string[];
+  summary?: string;
+}
+
+export interface ExaSearchResponse {
+  results: ExaSearchResult[];
+  costDollars?: { total: number };
+}
+
+// Tool detail types
+export interface SearchDetails {
+  query: string;
+  numResults: number;
+  cost?: { total: number };
+}
+
+export interface FetchDetails {
+  url: string;
+  title?: string;
+  cost?: { total: number };
+}
+
+export interface CodeContextDetails {
+  query: string;
+  resultsCount: number;
+  outputTokens: number;
+  cost?: { total: number };
+}
+
+// Code context API response type
+export interface CodeContextResponse {
+  requestId: string;
+  query: string;
+  response: string;
+  resultsCount: number;
+  costDollars: string | { total: number };
+  searchTime: number;
+  outputTokens: number;
+}
+
+// Exa search options type
+export interface SearchOptions {
+  numResults: number;
+  contents?: { text?: true; highlights?: true; summary?: true };
+}
+
+// Exa getContents options type
+export interface GetContentsOptions {
+  text?: true;
+  highlights?: true;
+  summary?: true;
+  maxCharacters?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarcelao/pi-exa-api",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Web search and content fetching for pi via the Exa API",
   "keywords": [
     "pi-package"
@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/jarcelao/pi-exa-api.git"
   },
-  "main": "./extensions/exa-search.ts",
+  "main": "./extensions/index.ts",
   "scripts": {
     "test": "vitest",
     "test:run": "vitest run",
@@ -22,18 +22,18 @@
     "format:check": "oxfmt --check"
   },
   "dependencies": {
-    "exa-js": "^2.10.1"
+    "exa-js": "^2.12.1"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "oxfmt": "^0.41.0",
+    "oxfmt": "^0.48.0",
     "oxlint": "^1.56.0",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "pi": {

package/tests/api-key.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { getApiKey } from "../extensions/api-key.ts";
+import { createMissingApiKeyError } from "../extensions/errors.ts";
+
+describe("API Key Management", () => {
+  afterEach(() => {
+    delete process.env.EXA_API_KEY;
+  });
+
+  it("should return undefined when EXA_API_KEY is not set", () => {
+    delete process.env.EXA_API_KEY;
+    expect(getApiKey()).toBeUndefined();
+  });
+
+  it("should return API key when EXA_API_KEY is set", () => {
+    const testKey = "test-api-key-123";
+    process.env.EXA_API_KEY = testKey;
+    expect(getApiKey()).toBe(testKey);
+  });
+
+  it("should treat empty string as not configured", () => {
+    process.env.EXA_API_KEY = "";
+    expect(getApiKey()).toBeUndefined();
+  });
+
+  it("should throw descriptive error when API key is missing", () => {
+    const error = createMissingApiKeyError();
+    expect(error.message).toContain("EXA_API_KEY");
+    expect(error.message).toContain("environment variable");
+  });
+});
+
+describe("Error Handling", () => {
+  it("should create descriptive missing API key error", () => {
+    const error = createMissingApiKeyError();
+    expect(error.message).toContain("Exa API key");
+    expect(error.message).toContain("EXA_API_KEY");
+    expect(error.message).toContain("environment variable");
+  });
+});

package/tests/content-type-mapping.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { mapSearchContentType, mapFetchContentType } from "../extensions/content-types.ts";
+
+describe("ContentType Mapping (Search)", () => {
+  it('should map "text" to contents.text', () => {
+    const result = mapSearchContentType("text");
+    expect(result).toEqual({ text: true });
+  });
+
+  it('should map "highlights" to contents.highlights', () => {
+    const result = mapSearchContentType("highlights");
+    expect(result).toEqual({ highlights: true });
+  });
+
+  it('should map "summary" to contents.summary', () => {
+    const result = mapSearchContentType("summary");
+    expect(result).toEqual({ summary: true });
+  });
+
+  it('should map "none" to undefined (metadata only)', () => {
+    const result = mapSearchContentType("none");
+    expect(result).toBeUndefined();
+  });
+
+  it("should default to highlights when not specified", () => {
+    const result = mapSearchContentType(undefined);
+    expect(result).toEqual({ highlights: true });
+  });
+});
+
+describe("ContentType Mapping (Fetch)", () => {
+  it('should map "text" to contents.text', () => {
+    const result = mapFetchContentType("text");
+    expect(result).toEqual({ text: true });
+  });
+
+  it('should map "highlights" to contents.highlights', () => {
+    const result = mapFetchContentType("highlights");
+    expect(result).toEqual({ highlights: true });
+  });
+
+  it('should map "summary" to contents.summary', () => {
+    const result = mapFetchContentType("summary");
+    expect(result).toEqual({ summary: true });
+  });
+
+  it("should default to text for fetch when not specified", () => {
+    const result = mapFetchContentType(undefined);
+    expect(result).toEqual({ text: true });
+  });
+});

package/tests/extension-registration.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect } from "vitest";
+import exaSearchExtension from "../extensions/index.ts";
+
+function createMockExtensionAPI() {
+  const tools: unknown[] = [];
+  const commands: Map<string, unknown> = new Map();
+  const eventHandlers: Map<string, unknown[]> = new Map();
+
+  return {
+    registerTool: (tool: unknown) => tools.push(tool),
+    registerCommand: (name: string, command: unknown) => commands.set(name, command),
+    on: (event: string, handler: unknown) => {
+      const handlers = eventHandlers.get(event) || [];
+      handlers.push(handler);
+      eventHandlers.set(event, handlers);
+    },
+    getTools: () => tools,
+    getCommand: (name: string) => commands.get(name),
+    getEventHandlers: (event: string) => eventHandlers.get(event) || [],
+    findTool: (name: string) => tools.find((t: unknown) => (t as { name: string }).name === name),
+  };
+}
+
+function setup() {
+  const api = createMockExtensionAPI();
+  exaSearchExtension(api as unknown as import("@earendil-works/pi-coding-agent").ExtensionAPI);
+  return api;
+}
+
+const mockTheme = { fg: (_name: string, text: string) => text };
+
+describe("Extension Registration", () => {
+  it("should register all three tools with correct names and labels", () => {
+    const api = setup();
+    const tools = api.getTools();
+    expect(tools).toHaveLength(3);
+
+    const expected = [
+      { name: "exa_search", label: "Exa Search" },
+      { name: "exa_fetch", label: "Exa Fetch" },
+      { name: "exa_code_context", label: "Exa Code Context" },
+    ];
+
+    for (const { name, label } of expected) {
+      const tool = api.findTool(name) as { name: string; label: string; execute: unknown };
+      expect(tool).toBeDefined();
+      expect(tool.name).toBe(name);
+      expect(tool.label).toBe(label);
+      expect(typeof tool.execute).toBe("function");
+    }
+  });
+
+  it("should register /exa-status command", () => {
+    const api = setup();
+    const cmd = api.getCommand("exa-status") as { description: string; handler: Function };
+    expect(cmd).toBeDefined();
+    expect(cmd.description).toContain("API key");
+    expect(typeof cmd.handler).toBe("function");
+  });
+
+  it("should register session_start event handler", () => {
+    const api = setup();
+    expect(api.getEventHandlers("session_start")).toHaveLength(1);
+  });
+});
+
+describe("exa_fetch renderResult", () => {
+  it("should display title and cost when both present", () => {
+    const api = setup();
+    const tool = api.findTool("exa_fetch") as { renderResult: Function };
+    const rendered = tool.renderResult(
+      {
+        content: [],
+        details: { url: "https://example.com", title: "Test Page", cost: { total: 0.000123 } },
+      },
+      { expanded: false, isPartial: false },
+      mockTheme,
+      { lastComponent: undefined },
+    );
+    expect(rendered.text).toContain("Test Page");
+    expect(rendered.text).toContain("$0.000123");
+  });
+
+  it("should display Fetched when no title", () => {
+    const api = setup();
+    const tool = api.findTool("exa_fetch") as { renderResult: Function };
+    const rendered = tool.renderResult(
+      { content: [], details: { url: "https://example.com", cost: { total: 0.000456 } } },
+      { expanded: false, isPartial: false },
+      mockTheme,
+      { lastComponent: undefined },
+    );
+    expect(rendered.text).toContain("Fetched");
+    expect(rendered.text).toContain("$0.000456");
+  });
+
+  it("should display empty string when no details", () => {
+    const api = setup();
+    const tool = api.findTool("exa_fetch") as { renderResult: Function };
+    const rendered = tool.renderResult(
+      { content: [] },
+      { expanded: false, isPartial: false },
+      mockTheme,
+      { lastComponent: undefined },
+    );
+    expect(rendered.text).toBe("");
+  });
+});
+
+describe("exa_code_context renderResult", () => {
+  it("should display stats and cost when details present", () => {
+    const api = setup();
+    const tool = api.findTool("exa_code_context") as { renderResult: Function };
+    const rendered = tool.renderResult(
+      {
+        content: [],
+        details: {
+          query: "React hooks",
+          resultsCount: 502,
+          outputTokens: 4805,
+          cost: { total: 1.0 },
+        },
+      },
+      { expanded: false, isPartial: false },
+      mockTheme,
+      { lastComponent: undefined },
+    );
+    expect(rendered.text).toContain("502 sources");
+    expect(rendered.text).toContain("4805 tokens");
+    expect(rendered.text).toContain("$1.000000");
+  });
+
+  it("should display stats without cost when cost missing", () => {
+    const api = setup();
+    const tool = api.findTool("exa_code_context") as { renderResult: Function };
+    const rendered = tool.renderResult(
+      {
+        content: [],
+        details: { query: "Express middleware", resultsCount: 100, outputTokens: 2000 },
+      },
+      { expanded: false, isPartial: false },
+      mockTheme,
+      { lastComponent: undefined },
+    );
+    expect(rendered.text).toContain("100 sources");
+    expect(rendered.text).toContain("2000 tokens");
+    expect(rendered.text).not.toContain("$");
+  });
+
+  it("should fall back to content text when no details", () => {
+    const api = setup();
+    const tool = api.findTool("exa_code_context") as { renderResult: Function };
+    const rendered = tool.renderResult(
+      { content: [{ type: "text", text: "Some code context output here" }] },
+      { expanded: false, isPartial: false },
+      mockTheme,
+      { lastComponent: undefined },
+    );
+    expect(rendered.text).toContain("Some code context");
+  });
+});

package/tests/formatting.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from "vitest";
+import {
+  formatSearchResults,
+  formatFetchResult,
+  formatCodeContextResult,
+  parseCostDollars,
+} from "../extensions/formatters.ts";
+
+describe("formatSearchResults", () => {
+  it("should format basic result fields", () => {
+    const formatted = formatSearchResults({
+      results: [
+        {
+          title: "Test Article",
+          url: "https://example.com/article",
+          publishedDate: "2024-01-15",
+          author: "John Doe",
+        },
+      ],
+    });
+    expect(formatted).toContain("--- Result 1 ---");
+    expect(formatted).toContain("Title: Test Article");
+    expect(formatted).toContain("URL: https://example.com/article");
+    expect(formatted).toContain("Published: 2024-01-15");
+    expect(formatted).toContain("Author: John Doe");
+  });
+
+  it("should omit publishedDate and author when null", () => {
+    const formatted = formatSearchResults({
+      results: [{ title: "Test", url: "https://example.com", publishedDate: null, author: null }],
+    });
+    expect(formatted).toContain("Title: Test");
+    expect(formatted).not.toContain("Published:");
+    expect(formatted).not.toContain("Author:");
+  });
+
+  it("should format highlights with bullet points", () => {
+    const formatted = formatSearchResults({
+      results: [
+        {
+          title: "Test",
+          url: "https://example.com",
+          highlights: ["First highlight", "Second highlight"],
+        },
+      ],
+    });
+    expect(formatted).toContain("Highlights:");
+    expect(formatted).toContain("  • First highlight");
+    expect(formatted).toContain("  • Second highlight");
+  });
+
+  it("should format summary inline", () => {
+    const formatted = formatSearchResults({
+      results: [{ title: "Test", url: "https://example.com", summary: "This is a summary" }],
+    });
+    expect(formatted).toContain("Summary: This is a summary");
+  });
+
+  it("should truncate text preview to 500 characters", () => {
+    const longText = "a".repeat(600);
+    const formatted = formatSearchResults({
+      results: [{ title: "Test", url: "https://example.com", text: longText }],
+    });
+    expect(formatted).toContain("a".repeat(500));
+    expect(formatted).toContain("...");
+    expect(formatted).not.toContain("a".repeat(501));
+  });
+
+  it("should not append ellipsis for short text", () => {
+    const formatted = formatSearchResults({
+      results: [{ title: "Test", url: "https://example.com", text: "short" }],
+    });
+    expect(formatted).toContain("Text: short");
+    expect(formatted).not.toContain("short...");
+  });
+
+  it("should include cost when provided", () => {
+    const formatted = formatSearchResults({
+      results: [{ title: "Test", url: "https://example.com" }],
+      costDollars: { total: 0.000123 },
+    });
+    expect(formatted).toContain("Cost: $0.000123");
+  });
+
+  it("should omit cost line when not provided", () => {
+    const formatted = formatSearchResults({
+      results: [{ title: "Test", url: "https://example.com" }],
+    });
+    expect(formatted).not.toContain("Cost:");
+  });
+
+  it("should number multiple results sequentially", () => {
+    const formatted = formatSearchResults({
+      results: [
+        { title: "First", url: "https://a.com" },
+        { title: "Second", url: "https://b.com" },
+        { title: "Third", url: "https://c.com" },
+      ],
+    });
+    expect(formatted).toContain("--- Result 1 ---");
+    expect(formatted).toContain("--- Result 2 ---");
+    expect(formatted).toContain("--- Result 3 ---");
+  });
+});
+
+describe("formatFetchResult", () => {
+  it("should format text content", () => {
+    const formatted = formatFetchResult(
+      { title: "Page Title", url: "https://example.com", text: "Full page content" },
+      "text",
+    );
+    expect(formatted).toContain("Title: Page Title");
+    expect(formatted).toContain("Full page content");
+  });
+
+  it("should format highlights with bullet points", () => {
+    const formatted = formatFetchResult(
+      { title: "Test", url: "https://example.com", highlights: ["Key point 1", "Key point 2"] },
+      "highlights",
+    );
+    expect(formatted).toContain("Highlights:");
+    expect(formatted).toContain("  • Key point 1");
+    expect(formatted).toContain("  • Key point 2");
+  });
+
+  it("should format summary", () => {
+    const formatted = formatFetchResult(
+      { title: "Test", url: "https://example.com", summary: "This page is about..." },
+      "summary",
+    );
+    expect(formatted).toContain("Summary:");
+    expect(formatted).toContain("This page is about...");
+  });
+
+  it("should omit title when not provided", () => {
+    const formatted = formatFetchResult(
+      { url: "https://example.com", text: "Content only" } as Parameters<
+        typeof formatFetchResult
+      >[0],
+      "text",
+    );
+    expect(formatted).toContain("URL: https://example.com");
+    expect(formatted).not.toContain("Title:");
+  });
+
+  it("should handle empty highlights array", () => {
+    const formatted = formatFetchResult(
+      { title: "Test", url: "https://example.com", highlights: [] },
+      "highlights",
+    );
+    expect(formatted).toContain("URL: https://example.com");
+    expect(formatted).not.toContain("Highlights:");
+  });
+
+  it("should handle missing text for text contentType", () => {
+    const formatted = formatFetchResult({ title: "Test", url: "https://example.com" }, "text");
+    expect(formatted).toContain("URL: https://example.com");
+    // No text section should appear
+    expect(formatted).not.toContain("Text:");
+  });
+});
+
+describe("parseCostDollars", () => {
+  it("should parse JSON string costDollars", () => {
+    const parsed = parseCostDollars('{"total":0.007,"search":{"neural":0.007}}');
+    expect(parsed).toEqual({ total: 0.007, search: { neural: 0.007 } });
+  });
+
+  it("should pass through object costDollars unchanged", () => {
+    const costObject = { total: 1.5 };
+    expect(parseCostDollars(costObject)).toBe(costObject);
+  });
+
+  it("should handle zero cost", () => {
+    expect(parseCostDollars('{"total":0}').total).toBe(0);
+  });
+});
+
+describe("formatCodeContextResult", () => {
+  const baseResponse = {
+    requestId: "req_123",
+    query: "React hooks state management",
+    response: "## Example\n\n```js\nconst [count, setCount] = useState(0);\n```",
+    resultsCount: 502,
+    costDollars: '{"total":0.007}',
+    searchTime: 1.234,
+    outputTokens: 4805,
+  };
+
+  it("should include all key fields", () => {
+    const formatted = formatCodeContextResult(baseResponse);
+    expect(formatted).toContain("Query: React hooks state management");
+    expect(formatted).toContain("Results: 502 sources");
+    expect(formatted).toContain("Output tokens: 4805");
+    expect(formatted).toContain("--- Code Context ---");
+    expect(formatted).toContain("## Example");
+  });
+
+  it("should format cost from JSON string", () => {
+    const formatted = formatCodeContextResult(baseResponse);
+    expect(formatted).toContain("Cost: $0.007000");
+  });
+
+  it("should format cost from object", () => {
+    const formatted = formatCodeContextResult({ ...baseResponse, costDollars: { total: 1.5 } });
+    expect(formatted).toContain("Cost: $1.500000");
+  });
+
+  it("should format cost with full decimal precision", () => {
+    const formatted = formatCodeContextResult({
+      ...baseResponse,
+      costDollars: '{"total":0.123456}',
+    });
+    expect(formatted).toContain("Cost: $0.123456");
+  });
+});