@jarcelao/pi-exa-api 0.2.2 → 0.3.0

package/extensions/tools/search.ts

@@ -0,0 +1,148 @@
+/**
+ * Exa Search 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 { mapSearchContentType } from "../content-types.ts";
+import { formatSearchResults, formatToolOutputPreview } from "../formatters.ts";
+import type { SearchContentType, SearchDetails, ExaSearchResult } from "../types.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 = getApiKey();
+      if (!apiKey) {
+        throw createMissingApiKeyError();
+      }
+
+      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}`);
+      }
+
+      let output = formatSearchResults({
+        results: response.results as ExaSearchResult[],
+        costDollars: response.costDollars as { total: number } | undefined,
+      });
+
+      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}]`;
+      }
+
+      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 preview = args.query.length > 50 ? args.query.slice(0, 50) + "..." : args.query;
+      const desc = `${args.numResults ?? 10} results • ${args.contentType ?? "highlights"}`;
+      const text =
+        theme.fg("toolTitle", theme.bold("exa_search ")) +
+        theme.fg("muted", preview) +
+        theme.fg("dim", ` ${desc}`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, options, theme, context) {
+      const details = result.details as SearchDetails | 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.numResults} results${cost}`);
+      }
+
+      const preview = formatToolOutputPreview(result, options, theme);
+      text.setText(preview ? `${header}\n${preview}` : header);
+      return text;
+    },
+  });
+}

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.0",
   "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",

package/tests/api-key.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { getApiKey, createMissingApiKeyError } from "../extensions/index.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/index.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("@mariozechner/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");
+  });
+});