@jarcelao/pi-exa-api 0.1.1

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jericho Renniel Arcelao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,88 @@
+# pi-exa-api
+
+Web search and content fetching for [pi](https://pi.dev) via the [Exa API](https://exa.ai/).
+
+
+## Installation
+
+Install as a pi package:
+
+```bash
+pi install npm:@jarcelao/pi-exa-api@0.1.0
+```
+
+## Configuration
+
+Set your Exa API key as an environment variable before starting pi:
+
+```bash
+export EXA_API_KEY="your-api-key-here"
+pi
+```
+
+Or add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) for persistence.
+
+### Check Configuration
+
+Run the `/exa-status` command in pi to verify your API key is configured:
+
+```
+/exa-status
+```
+
+## Usage
+
+### Web Search
+
+The agent can use `exa_search` to find information on the web:
+
+```
+Search for recent developments in quantum computing
+```
+
+**Parameters:**
+
+- `query` (required) - Natural language search query
+- `contentType` (optional) - Type of content to retrieve:
+  - `highlights` (default) - Key excerpts from each result
+  - `text` - Full text content (may be truncated)
+  - `summary` - AI-generated summary
+  - `none` - Metadata only (title, URL, date, author)
+- `numResults` (optional) - Number of results (1-100, default: 10)
+
+### Fetch URL Content
+
+The agent can use `exa_fetch` to extract content from a specific URL:
+
+```
+Fetch the content from https://example.com/article
+```
+
+**Parameters:**
+
+- `url` (required) - URL to fetch
+- `contentType` (optional) - Type of content:
+  - `text` (default) - Full page text
+  - `highlights` - Key excerpts
+  - `summary` - AI-generated summary
+- `maxCharacters` (optional) - Maximum characters to return (1000-100000)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run linting
+npm run lint
+
+# Format code
+npm run format
+```
+
+## License
+
+MIT

package/exa-search.test.ts

@@ -0,0 +1,459 @@
+import { describe, it, expect, afterEach } from "vitest";
+import exaSearchExtension, {
+  getApiKey,
+  mapSearchContentType,
+  mapFetchContentType,
+  formatSearchResults,
+  formatFetchResult,
+  createMissingApiKeyError,
+} from "./extensions/exa-search.ts";
+import {
+  truncateHead,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+} from "@mariozechner/pi-coding-agent";
+
+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("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 });
+  });
+});
+
+describe("Parameter Validation", () => {
+  it("should accept valid search params (query only)", () => {
+    const params = { query: "test query" };
+    expect(params.query).toBeTruthy();
+    expect(params.query.trim()).not.toBe("");
+  });
+
+  it("should accept valid search params (all options)", () => {
+    const params = {
+      query: "test",
+      contentType: "highlights" as const,
+      numResults: 10,
+    };
+    expect(params.query).toBeTruthy();
+    expect(["text", "highlights", "summary", "none"].includes(params.contentType)).toBe(true);
+    expect(params.numResults).toBeGreaterThanOrEqual(1);
+    expect(params.numResults).toBeLessThanOrEqual(100);
+  });
+
+  it("should accept valid fetch params", () => {
+    const params = {
+      url: "https://example.com",
+      contentType: "text" as const,
+      maxCharacters: 5000,
+    };
+    expect(params.url).toBeTruthy();
+    expect(["text", "highlights", "summary"].includes(params.contentType)).toBe(true);
+    expect(params.maxCharacters).toBeGreaterThan(0);
+  });
+
+  it("should reject fetch params with invalid contentType", () => {
+    const invalidContentTypes = ["none", "invalid", "full"];
+    for (const ct of invalidContentTypes) {
+      expect(["text", "highlights", "summary"].includes(ct as string)).toBe(false);
+    }
+  });
+});
+
+describe("Output Truncation", () => {
+  it("should not truncate short output", () => {
+    const text = "Short text";
+    const result = truncateHead(text);
+    expect(result.truncated).toBe(false);
+    expect(result.content).toBe(text);
+    expect(result.outputLines).toBe(1);
+  });
+
+  it("should truncate by line count", () => {
+    const lines = Array.from({ length: 100 }, (_, i) => `Line ${i}`);
+    const text = lines.join("\n");
+    const result = truncateHead(text, { maxLines: 10 });
+    expect(result.truncated).toBe(true);
+    expect(result.outputLines).toBe(10);
+    expect(result.totalLines).toBe(100);
+  });
+
+  it("should truncate by byte size", () => {
+    const text = "x".repeat(10000);
+    const result = truncateHead(text, { maxBytes: 1000 });
+    expect(result.truncated).toBe(true);
+    expect(result.outputBytes).toBeLessThanOrEqual(1000);
+  });
+
+  it("should respect DEFAULT_MAX_LINES constant", () => {
+    expect(DEFAULT_MAX_LINES).toBe(2000);
+  });
+
+  it("should respect DEFAULT_MAX_BYTES constant", () => {
+    expect(DEFAULT_MAX_BYTES).toBe(50 * 1024);
+  });
+
+  it("formatSize should format bytes correctly", () => {
+    expect(formatSize(500)).toBe("500B");
+    expect(formatSize(1024)).toBe("1.0KB");
+    expect(formatSize(1024 * 50)).toBe("50.0KB");
+    expect(formatSize(1024 * 1024)).toBe("1.0MB");
+  });
+});
+
+describe("Search Result Formatting", () => {
+  it("should format basic search results", () => {
+    const response = {
+      results: [
+        {
+          title: "Test Article",
+          url: "https://example.com/article",
+          publishedDate: "2024-01-15",
+          author: "John Doe",
+        },
+      ],
+    };
+
+    const formatted = formatSearchResults(response);
+    expect(formatted).toContain("Test Article");
+    expect(formatted).toContain("https://example.com/article");
+    expect(formatted).toContain("2024-01-15");
+    expect(formatted).toContain("John Doe");
+    expect(formatted).toContain("--- Result 1 ---");
+  });
+
+  it("should format results with highlights", () => {
+    const response = {
+      results: [
+        {
+          title: "Test",
+          url: "https://example.com",
+          highlights: ["First highlight", "Second highlight"],
+        },
+      ],
+    };
+
+    const formatted = formatSearchResults(response);
+    expect(formatted).toContain("Highlights:");
+    expect(formatted).toContain("First highlight");
+    expect(formatted).toContain("Second highlight");
+    expect(formatted).toContain("  • First highlight");
+  });
+
+  it("should format results with summary", () => {
+    const response = {
+      results: [
+        {
+          title: "Test",
+          url: "https://example.com",
+          summary: "This is a summary",
+        },
+      ],
+    };
+
+    const formatted = formatSearchResults(response);
+    expect(formatted).toContain("Summary: This is a summary");
+  });
+
+  it("should include cost information", () => {
+    const response = {
+      results: [{ title: "Test", url: "https://example.com" }],
+      costDollars: { total: 0.000123 },
+    };
+
+    const formatted = formatSearchResults(response);
+    expect(formatted).toContain("Cost: $0.000123");
+  });
+
+  it("should handle null publishedDate and author", () => {
+    const response = {
+      results: [
+        {
+          title: "Test",
+          url: "https://example.com",
+          publishedDate: null,
+          author: null,
+        },
+      ],
+    };
+
+    const formatted = formatSearchResults(response);
+    expect(formatted).toContain("Title: Test");
+    expect(formatted).not.toContain("Published:");
+    expect(formatted).not.toContain("Author:");
+  });
+
+  it("should truncate long text preview", () => {
+    const longText = "a".repeat(600);
+    const response = {
+      results: [
+        {
+          title: "Test",
+          url: "https://example.com",
+          text: longText,
+        },
+      ],
+    };
+
+    const formatted = formatSearchResults(response);
+    expect(formatted).toContain("a".repeat(500));
+    expect(formatted).toContain("...");
+    expect(formatted).not.toContain("a".repeat(501));
+  });
+});
+
+describe("Fetch Result Formatting", () => {
+  it("should format text content", () => {
+    const result = {
+      title: "Page Title",
+      url: "https://example.com",
+      text: "Full page content here",
+    };
+
+    const formatted = formatFetchResult(result, "text");
+    expect(formatted).toContain("Title: Page Title");
+    expect(formatted).toContain("Full page content here");
+  });
+
+  it("should format highlights", () => {
+    const result = {
+      url: "https://example.com",
+      highlights: ["Key point 1", "Key point 2"],
+    };
+
+    const formatted = formatFetchResult(result, "highlights");
+    expect(formatted).toContain("Highlights:");
+    expect(formatted).toContain("Key point 1");
+    expect(formatted).toContain("Key point 2");
+    expect(formatted).toContain("  • Key point 1");
+  });
+
+  it("should format summary", () => {
+    const result = {
+      url: "https://example.com",
+      summary: "This page is about...",
+    };
+
+    const formatted = formatFetchResult(result, "summary");
+    expect(formatted).toContain("Summary:");
+    expect(formatted).toContain("This page is about...");
+  });
+
+  it("should not include title if not provided", () => {
+    const result = {
+      url: "https://example.com",
+      text: "Content only",
+    };
+
+    const formatted = formatFetchResult(result, "text");
+    expect(formatted).toContain("https://example.com");
+    expect(formatted).not.toContain("Title:");
+  });
+});
+
+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");
+  });
+});
+
+describe("Extension Registration", () => {
+  function createMockExtensionAPI() {
+    const tools: unknown[] = [];
+    const commands: Map<string, unknown> = new Map();
+    const eventHandlers: Map<string, unknown[]> = new Map();
+
+    const api = {
+      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,
+      getCommands: () => Array.from(commands.entries()),
+      getEventHandlers: (event: string) => eventHandlers.get(event) || [],
+    };
+
+    return api;
+  }
+
+  it("should register exa_search tool", () => {
+    const api = createMockExtensionAPI();
+    exaSearchExtension(api as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI);
+
+    const tools = api.getTools();
+    expect(tools.length).toBeGreaterThanOrEqual(2);
+
+    const exaSearchTool = tools.find((t: unknown) => (t as { name: string }).name === "exa_search");
+    expect(exaSearchTool).toBeDefined();
+    expect((exaSearchTool as { name: string }).name).toBe("exa_search");
+    expect((exaSearchTool as { label: string }).label).toBe("Exa Search");
+  });
+
+  it("should register exa_fetch tool", () => {
+    const api = createMockExtensionAPI();
+    exaSearchExtension(api as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI);
+
+    const tools = api.getTools();
+    const exaFetchTool = tools.find((t: unknown) => (t as { name: string }).name === "exa_fetch");
+    expect(exaFetchTool).toBeDefined();
+    expect((exaFetchTool as { name: string }).name).toBe("exa_fetch");
+    expect((exaFetchTool as { label: string }).label).toBe("Exa Fetch");
+  });
+
+  it("should register /exa-status command", () => {
+    const api = createMockExtensionAPI();
+    exaSearchExtension(api as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI);
+
+    const commands = api.getCommands();
+    const exaStatusCmd = commands.find(([name]) => name === "exa-status");
+    expect(exaStatusCmd).toBeDefined();
+    expect(exaStatusCmd![0]).toBe("exa-status");
+    expect((exaStatusCmd![1] as { description: string }).description).toContain("API key");
+  });
+
+  it("should register session_start event handler", () => {
+    const api = createMockExtensionAPI();
+    exaSearchExtension(api as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI);
+
+    const handlers = api.getEventHandlers("session_start");
+    expect(handlers.length).toBe(1);
+  });
+
+  it("should have execute function on exa_search tool", () => {
+    const api = createMockExtensionAPI();
+    exaSearchExtension(api as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI);
+
+    const tools = api.getTools();
+    const exaSearchTool = tools.find(
+      (t: unknown) => (t as { name: string }).name === "exa_search",
+    ) as { execute: unknown };
+    expect(typeof exaSearchTool?.execute).toBe("function");
+  });
+
+  it("should have execute function on exa_fetch tool", () => {
+    const api = createMockExtensionAPI();
+    exaSearchExtension(api as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI);
+
+    const tools = api.getTools();
+    const exaFetchTool = tools.find(
+      (t: unknown) => (t as { name: string }).name === "exa_fetch",
+    ) as { execute: unknown };
+    expect(typeof exaFetchTool?.execute).toBe("function");
+  });
+});
+
+describe("Tool Execute Validation", () => {
+  it("should validate search parameters structure", () => {
+    const searchParams = {
+      query: "test query",
+      contentType: "highlights" as const,
+      numResults: 10,
+    };
+
+    expect(typeof searchParams.query).toBe("string");
+    expect(searchParams.query.trim().length).toBeGreaterThan(0);
+    expect(["text", "highlights", "summary", "none"].includes(searchParams.contentType)).toBe(true);
+    expect(searchParams.numResults).toBeGreaterThanOrEqual(1);
+    expect(searchParams.numResults).toBeLessThanOrEqual(100);
+  });
+
+  it("should validate fetch parameters structure", () => {
+    const fetchParams = {
+      url: "https://example.com",
+      contentType: "text" as const,
+      maxCharacters: 5000,
+    };
+
+    expect(typeof fetchParams.url).toBe("string");
+    expect(fetchParams.url.length).toBeGreaterThan(0);
+    expect(["text", "highlights", "summary"].includes(fetchParams.contentType)).toBe(true);
+    expect(fetchParams.maxCharacters).toBeGreaterThan(0);
+  });
+
+  it("should handle getContents options mapping", () => {
+    const url = "https://example.com";
+    const options = {
+      text: true,
+      maxCharacters: 10000,
+    };
+
+    expect(url).toBeTruthy();
+    expect(options.text).toBe(true);
+    expect(options.maxCharacters).toBeGreaterThan(0);
+  });
+});

package/extensions/exa-search.ts

@@ -0,0 +1,441 @@
+/**
+ * exa-search Extension
+ *
+ * Registers two tools for web search and content fetching using the Exa API:
+ * - exa_search: Natural language web search
+ * - exa_fetch: Fetch and extract content from URLs
+ *
+ * Also registers the /exa-status command to check API key configuration.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type, type Static } from "@sinclair/typebox";
+import {
+  truncateHead,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+} from "@mariozechner/pi-coding-agent";
+import Exa from "exa-js";
+
+// API Key Management
+
+function getApiKey(): string | undefined {
+  const key = process.env.EXA_API_KEY;
+  return key && key.length > 0 ? key : undefined;
+}
+
+// Type Definitions
+
+type SearchContentType = "text" | "highlights" | "summary" | "none";
+type FetchContentType = "text" | "highlights" | "summary";
+
+interface SearchDetails {
+  query: string;
+  numResults: number;
+  cost?: { total: number };
+}
+
+interface FetchDetails {
+  url: string;
+  title?: string;
+}
+
+// Content Type Mapping
+
+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 };
+  }
+}
+
+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 };
+  }
+}
+
+// Result Formatting
+
+interface ExaSearchResult {
+  title: string;
+  url: string;
+  publishedDate?: string | null;
+  author?: string | null;
+  text?: string;
+  highlights?: string[];
+  summary?: string;
+}
+
+interface ExaSearchResponse {
+  results: ExaSearchResult[];
+  costDollars?: { total: number };
+}
+
+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");
+}
+
+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");
+}
+
+// Error Creation
+
+function createMissingApiKeyError(): Error {
+  return new Error(
+    "Exa API key not configured. Set EXA_API_KEY environment variable before starting pi.",
+  );
+}
+
+// Exports
+
+export { getApiKey, mapSearchContentType, mapFetchContentType, formatSearchResults, formatFetchResult, createMissingApiKeyError };
+
+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 exa_search tool
+
+  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)",
+      }),
+    ),
+  });
+
+  pi.registerTool({
+    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: Static<typeof ExaSearchParams>,
+      _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);
+        return {
+          content: [{ type: "text", text: `Exa API error: ${message}` }],
+          details: { query: params.query, numResults: 0 } as SearchDetails,
+        };
+      }
+
+      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) {
+        result += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;
+        result += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).]`;
+      }
+
+      return {
+        content: [{ type: "text", text: result }],
+        details: {
+          query: params.query,
+          numResults: response.results.length,
+          cost: response.costDollars,
+        } as SearchDetails,
+      };
+    },
+
+    renderCall(args, 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, { expanded: _expanded }, theme) {
+      const details = result.details as SearchDetails | undefined;
+
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === "text" ? text.text.slice(0, 60) : "", 0, 0);
+      }
+
+      const cost = details.cost ? ` • $${details.cost.total.toFixed(6)}` : "";
+      return new Text(theme.fg("success", `✓ ${details.numResults} results${cost}`), 0, 0);
+    },
+  });
+
+  // Register exa_fetch tool
+
+  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",
+      }),
+    ),
+  });
+
+  pi.registerTool({
+    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: Static<typeof ExaFetchParams>,
+      _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);
+        return {
+          content: [{ type: "text", text: `Exa API error: ${message}` }],
+          details: { url: params.url } as FetchDetails,
+        };
+      }
+
+      if (!response.results || response.results.length === 0) {
+        return {
+          content: [{ type: "text", text: "No content found at this URL." }],
+          details: { url: params.url } 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) {
+        content += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;
+        content += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).]`;
+      }
+
+      return {
+        content: [{ type: "text", text: content }],
+        details: {
+          url: params.url,
+          title: result.title,
+        } as FetchDetails,
+      };
+    },
+
+    renderCall(args, 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, { expanded: _expanded }, theme) {
+      const details = result.details as FetchDetails | undefined;
+
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === "text" ? text.text.slice(0, 60) : "", 0, 0);
+      }
+
+      if (details.title) {
+        return new Text(theme.fg("success", "✓ ") + theme.fg("accent", details.title), 0, 0);
+      }
+
+      return new Text(theme.fg("muted", "Done"), 0, 0);
+    },
+  });
+
+  // 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/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@jarcelao/pi-exa-api",
+  "version": "0.1.1",
+  "description": "Web search and content fetching for pi via the Exa API",
+  "keywords": [
+    "pi-package"
+  ],
+  "main": "./extensions/exa-search.ts",
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check"
+  },
+  "dependencies": {
+    "exa-js": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "oxfmt": "^0.41.0",
+    "oxlint": "^1.56.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["**/*.test.ts"],
+  },
+});