@jarcelao/pi-exa-api 0.2.0 → 0.2.2

package/README.md

@@ -1,6 +1,6 @@
 # pi-exa-api
 
-Web search and content fetching for [pi](https://pi.dev) via the [Exa API](https://exa.ai/).
+Web search, content fetching, and code context for [pi](https://pi.dev) via the [Exa API](https://exa.ai/).
 
 ## Installation
 
@@ -10,6 +10,9 @@ Install as a pi package:
 pi install npm:@jarcelao/pi-exa-api
 ```
 
+> [!NOTE]
+> This extension is compatible with `pi-coding-agent` v0.69.0
+
 ## Configuration
 
 Set your Exa API key as an environment variable before starting pi:
@@ -66,6 +69,23 @@ Fetch the content from https://example.com/article
   - `summary` - AI-generated summary
 - `maxCharacters` (optional) - Maximum characters to return (1000-100000)
 
+### Code Context
+
+The agent can use `exa_code_context` to find code snippets and examples from open source libraries and repositories:
+
+```
+Find examples of React hooks for state management
+```
+
+It's ideal for understanding how libraries, frameworks, or programming concepts are implemented in practice.
+
+**Parameters:**
+
+- `query` (required) - Search query for code snippets and examples (1-2000 characters)
+- `tokensNum` (optional) - Token limit for the response:
+  - `"dynamic"` (default) - Automatically determine optimal response length
+  - `50-100000` - Specific number of tokens (5000 is a good default, use 10000 when more context is needed)
+
 ## Development
 
 ```bash

package/exa-search.test.ts

@@ -298,6 +298,7 @@ describe("Fetch Result Formatting", () => {
 
   it("should format highlights", () => {
     const result = {
+      title: "Test Page",
       url: "https://example.com",
       highlights: ["Key point 1", "Key point 2"],
     };
@@ -311,6 +312,7 @@ describe("Fetch Result Formatting", () => {
 
   it("should format summary", () => {
     const result = {
+      title: "Test Page",
       url: "https://example.com",
       summary: "This page is about...",
     };
@@ -324,9 +326,9 @@ describe("Fetch Result Formatting", () => {
     const result = {
       url: "https://example.com",
       text: "Content only",
-    };
+    } as { title?: string; url: string; text: string };
 
-    const formatted = formatFetchResult(result, "text");
+    const formatted = formatFetchResult(result as Parameters<typeof formatFetchResult>[0], "text");
     expect(formatted).toContain("https://example.com");
     expect(formatted).not.toContain("Title:");
   });
@@ -485,6 +487,60 @@ describe("Code Context Parameter Validation", () => {
   });
 });
 
+describe("tokensNum Type Coercion", () => {
+  // Helper function that mirrors the type coercion logic in exa_code_context execute
+  function coerceTokensNum(tokensNum: string | number | undefined): string | number {
+    const value = tokensNum ?? "dynamic";
+    if (typeof value === "string" && value !== "dynamic") {
+      return Number(value);
+    }
+    return value;
+  }
+
+  it("should return 'dynamic' when tokensNum is undefined", () => {
+    const result = coerceTokensNum(undefined);
+    expect(result).toBe("dynamic");
+    expect(typeof result).toBe("string");
+  });
+
+  it("should preserve 'dynamic' string", () => {
+    const result = coerceTokensNum("dynamic");
+    expect(result).toBe("dynamic");
+    expect(typeof result).toBe("string");
+  });
+
+  it("should preserve numeric tokens", () => {
+    const result = coerceTokensNum(5000);
+    expect(result).toBe(5000);
+    expect(typeof result).toBe("number");
+  });
+
+  it("should coerce numeric string to number", () => {
+    const result = coerceTokensNum("5000");
+    expect(result).toBe(5000);
+    expect(typeof result).toBe("number");
+  });
+
+  it("should coerce various numeric strings", () => {
+    expect(coerceTokensNum("1000")).toBe(1000);
+    expect(coerceTokensNum("10000")).toBe(10000);
+    expect(coerceTokensNum("3000")).toBe(3000);
+    expect(typeof coerceTokensNum("5000")).toBe("number");
+  });
+
+  it("should handle boundary token values", () => {
+    expect(coerceTokensNum(50)).toBe(50);
+    expect(coerceTokensNum(100000)).toBe(100000);
+  });
+
+  it("should not modify actual numbers", () => {
+    const originalNumber = 7500;
+    const result = coerceTokensNum(originalNumber);
+    expect(result).toBe(originalNumber);
+    expect(result).toBe(7500);
+  });
+});
+
 describe("Extension Registration", () => {
   function createMockExtensionAPI() {
     const tools: unknown[] = [];
@@ -622,7 +678,6 @@ describe("Extension Registration", () => {
       mockResult,
       { expanded: false, isPartial: false },
       mockTheme,
-      {},
     );
 
     expect(rendered.text).toContain("Test Page");
@@ -654,7 +709,6 @@ describe("Extension Registration", () => {
       mockResult,
       { expanded: false, isPartial: false },
       mockTheme,
-      {},
     );
 
     expect(rendered.text).toContain("Fetched");
@@ -688,7 +742,6 @@ describe("Extension Registration", () => {
       mockResult,
       { expanded: false, isPartial: false },
       mockTheme,
-      {},
     );
 
     expect(rendered.text).toContain("502 sources");
@@ -722,7 +775,6 @@ describe("Extension Registration", () => {
       mockResult,
       { expanded: false, isPartial: false },
       mockTheme,
-      {},
     );
 
     expect(rendered.text).toContain("100 sources");
@@ -751,7 +803,6 @@ describe("Extension Registration", () => {
       mockResult,
       { expanded: false, isPartial: false },
       mockTheme,
-      {},
     );
 
     expect(rendered.text).toContain("Some code context");

package/extensions/exa-search.ts

@@ -9,17 +9,19 @@
  * Also registers the /exa-status command to check API key configuration.
  */
 
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
-import { Type, type Static } from "@sinclair/typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
 import {
-  truncateHead,
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
+  defineTool,
   formatSize,
-  writeTempFile,
+  truncateHead,
 } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type, type Static } from "typebox";
 import Exa from "exa-js";
 
 // API Key Management
@@ -29,6 +31,15 @@ function getApiKey(): string | undefined {
   return key && key.length > 0 ? key : undefined;
 }
 
+// Temp File Helper
+
+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;
+}
+
 // Type Definitions
 
 type SearchContentType = "text" | "highlights" | "summary" | "none";
@@ -251,7 +262,14 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
     query: Type.String({
       description: "Natural language search query",
     }),
-    contentType: Type.Optional(StringEnum(["text", "highlights", "summary", "none"] as const)),
+    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)",
@@ -259,9 +277,10 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
     ),
   });
 
-  pi.registerTool({
-    name: "exa_search",
-    label: "Exa Search",
+  pi.registerTool(
+    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,
@@ -312,7 +331,7 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
       let result = truncation.content;
 
       if (truncation.truncated) {
-        const tempFile = writeTempFile(output);
+        const tempFile = await writeTempFile(output);
         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}]`;
@@ -338,7 +357,7 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
 
-    renderResult(result, { expanded: _expanded, isPartial: _isPartial }, theme, _context) {
+    renderResult(result, _options, theme) {
       const details = result.details as SearchDetails | undefined;
 
       if (!details) {
@@ -349,7 +368,9 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
       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
 
@@ -357,7 +378,9 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
     url: Type.String({
       description: "URL to fetch content from",
     }),
-    contentType: Type.Optional(StringEnum(["text", "highlights", "summary"] as const)),
+    contentType: Type.Optional(
+      Type.Union([Type.Literal("text"), Type.Literal("highlights"), Type.Literal("summary")]),
+    ),
     maxCharacters: Type.Optional(
       Type.Number({
         description: "Maximum characters to return",
@@ -365,9 +388,10 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
     ),
   });
 
-  pi.registerTool({
-    name: "exa_fetch",
-    label: "Exa Fetch",
+  pi.registerTool(
+    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,
@@ -427,7 +451,7 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
       let content = truncation.content;
 
       if (truncation.truncated) {
-        const tempFile = writeTempFile(output);
+        const tempFile = await writeTempFile(output);
         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}]`;
@@ -453,7 +477,7 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
 
-    renderResult(result, { expanded: _expanded, isPartial: _isPartial }, theme, _context) {
+    renderResult(result, _options, theme) {
       const details = result.details as FetchDetails | undefined;
 
       if (!details) {
@@ -469,7 +493,8 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
 
       return new Text(theme.fg("success", `✓ Fetched${cost}`), 0, 0);
     },
-  });
+    })
+  );
 
   // Register exa_code_context tool
 
@@ -489,9 +514,10 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
     ),
   });
 
-  pi.registerTool({
-    name: "exa_code_context",
-    label: "Exa Code Context",
+  pi.registerTool(
+    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,
@@ -508,7 +534,14 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
         throw createMissingApiKeyError();
       }
 
-      const tokensNum = params.tokensNum ?? "dynamic";
+      // 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;
       try {
@@ -545,7 +578,7 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
       let result = truncation.content;
 
       if (truncation.truncated) {
-        const tempFile = writeTempFile(output);
+        const tempFile = await writeTempFile(output);
         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}]`;
@@ -574,7 +607,7 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
 
-    renderResult(result, { expanded: _expanded, isPartial: _isPartial }, theme, _context) {
+    renderResult(result, _options, theme) {
       const details = result.details as CodeContextDetails | undefined;
 
       if (!details) {
@@ -584,12 +617,17 @@ export default function exaSearchExtension(pi: ExtensionAPI): void {
 
       const cost = details.cost ? ` • $${details.cost.total.toFixed(6)}` : "";
       return new Text(
-        theme.fg("success", `✓ ${details.resultsCount} sources • ${details.outputTokens} tokens${cost}`),
+        theme.fg(
+          "success",
+          `✓ ${details.resultsCount} sources • ${details.outputTokens} tokens${cost}`,
+        ),
         0,
         0,
       );
     },
-  });
+    })
+  );
+
 
   // Register /exa-status command
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarcelao/pi-exa-api",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Web search and content fetching for pi via the Exa API",
   "keywords": [
     "pi-package"
@@ -34,7 +34,7 @@
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "typebox": "*"
   },
   "pi": {
     "extensions": [

package/tsconfig.json

@@ -8,8 +8,9 @@
     "skipLibCheck": true,
     "noEmit": true,
     "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
     "types": ["node"]
   },
-  "include": ["*.ts"],
+  "include": ["*.ts", "extensions/**/*.ts"],
   "exclude": ["node_modules"]
 }