@alasano/pi-exa 0.0.1

package/extensions/tools/web-search.ts

@@ -0,0 +1,112 @@
+import { defineTool } from '@earendil-works/pi-coding-agent';
+import type { Static } from '@sinclair/typebox';
+import { exaPost } from '../client';
+import { formatSearchResponse } from '../format';
+import { truncateToolOutput } from '../output';
+import {
+  buildSearchPreview,
+  metadataFromArgs,
+  renderExaCall,
+  renderExaResult,
+  sendProgress,
+} from '../render';
+import { WebSearchParamsSchema } from '../schemas';
+import type { ExaSearchResponse, ExaToolDetails, SearchCategory, SearchType } from '../types';
+import { withExaApiKey, errorResult } from './helpers';
+
+type WebSearchParams = Static<typeof WebSearchParamsSchema>;
+
+export interface WebSearchRequest {
+  query: string;
+  type: SearchType;
+  numResults: number;
+  category?: SearchCategory;
+  contents: {
+    highlights: true;
+  };
+}
+
+const CATEGORY_PATTERN = /\bcategory:(company|research\s*paper|news|personal\s*site|people)\b/i;
+
+function parseCategory(query: string): { query: string; category?: SearchCategory } {
+  const match = query.match(CATEGORY_PATTERN);
+  if (!match) return { query };
+
+  return {
+    query: query.replace(match[0], '').replace(/\s+/g, ' ').trim(),
+    category: match[1]?.toLowerCase().replace(/\s+/g, ' ') as SearchCategory,
+  };
+}
+
+export function buildWebSearchRequest(params: WebSearchParams): WebSearchRequest {
+  const parsed = parseCategory(params.query);
+  return {
+    query: parsed.query || params.query,
+    type: 'auto',
+    numResults: params.numResults ?? 10,
+    ...(parsed.category ? { category: parsed.category } : {}),
+    contents: {
+      highlights: true,
+    },
+  };
+}
+
+export function createWebSearchTool() {
+  return defineTool<
+    typeof WebSearchParamsSchema,
+    ExaToolDetails<ExaSearchResponse, WebSearchRequest> | undefined
+  >({
+    name: 'web_search_exa',
+    label: 'Exa Web Search',
+    description:
+      'Search the web with Exa and return compact, highlight-first results. Use for broad web lookup before fetching full pages.',
+    promptSnippet: 'Search the web with compact Exa highlights',
+    promptGuidelines: [
+      'Use web_search_exa for broad web lookup, then use web_fetch_exa only on selected URLs that need fuller content.',
+      'Prefer web_search_exa results as source leads; do not paste raw search output when a concise synthesis is enough.',
+    ],
+    parameters: WebSearchParamsSchema,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const request = buildWebSearchRequest(params);
+      try {
+        return await withExaApiKey(ctx, async (apiKey) => {
+          sendProgress(onUpdate, 'Searching Exa...');
+          const response = await exaPost<ExaSearchResponse>(apiKey, '/search', request, signal);
+          const output = await truncateToolOutput(
+            formatSearchResponse(response),
+            'web-search-exa',
+            'Refine your query, reduce numResults, or use web_fetch_exa only for selected URLs. ',
+          );
+          return {
+            content: [{ type: 'text', text: output.text }],
+            details: {
+              endpoint: '/search',
+              request,
+              response,
+              requestId: response.requestId,
+              count: response.results?.length ?? 0,
+              costDollars: response.costDollars,
+              preview: buildSearchPreview(response, output),
+              truncated: output.truncation.truncated,
+              truncation: output.truncation,
+              fullOutputPath: output.fullOutputPath,
+            },
+          };
+        });
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+    renderCall(args, theme) {
+      return renderExaCall(
+        'web_search_exa',
+        `"${args.query}"`,
+        theme,
+        metadataFromArgs(args, ['numResults']),
+      );
+    },
+    renderResult(result, options, theme) {
+      return renderExaResult(result, options, theme, 'Searching Exa...');
+    },
+  });
+}

package/extensions/types.ts

@@ -0,0 +1,238 @@
+export type JsonObject = Record<string, unknown>;
+
+export type SearchType = 'auto' | 'fast' | 'instant';
+
+export type ExaLink = {
+  url?: string;
+  title?: string;
+  altText?: string;
+};
+
+export type ExaExtras = {
+  links?: Array<string | ExaLink>;
+  imageLinks?: Array<string | ExaLink>;
+};
+
+export type ExaGroundingCitation = {
+  url?: string;
+  title?: string;
+};
+
+export type ExaGrounding = {
+  field?: string;
+  citations?: ExaGroundingCitation[];
+  confidence?: string;
+};
+
+export type ExaSearchOutput = {
+  content?: string | JsonObject;
+  grounding?: ExaGrounding[];
+};
+
+export type SearchCategory =
+  | 'company'
+  | 'research paper'
+  | 'news'
+  | 'pdf'
+  | 'github'
+  | 'personal site'
+  | 'people'
+  | 'financial report';
+
+export interface ExaSearchResult {
+  id?: string;
+  title?: string;
+  url?: string;
+  publishedDate?: string;
+  author?: string | null;
+  text?: string;
+  highlights?: string[];
+  summary?: string | JsonObject;
+  score?: number;
+  image?: string;
+  favicon?: string;
+  subpages?: ExaSearchResult[];
+  links?: Array<string | ExaLink>;
+  imageLinks?: Array<string | ExaLink>;
+  extras?: ExaExtras;
+  entities?: unknown[];
+}
+
+export interface ExaSearchResponse {
+  requestId?: string;
+  autopromptString?: string;
+  resolvedSearchType?: string;
+  searchType?: string | null;
+  searchTime?: number;
+  results?: ExaSearchResult[];
+  output?: ExaSearchOutput;
+  statuses?: ExaContentsStatus[];
+  context?: string;
+  autoDate?: string;
+  costDollars?: JsonObject;
+}
+
+export interface ExaContentsStatus {
+  id?: string;
+  url?: string;
+  status?: string;
+  error?:
+    | string
+    | {
+        tag?: string;
+        message?: string;
+        httpStatusCode?: number | null;
+      };
+}
+
+export interface ExaContentsResponse {
+  requestId?: string;
+  results?: ExaSearchResult[];
+  statuses?: ExaContentsStatus[];
+  costDollars?: JsonObject;
+}
+
+export interface ExaAnswerResponse {
+  requestId?: string;
+  answer?: string | JsonObject;
+  citations?: ExaSearchResult[];
+  costDollars?: JsonObject;
+}
+
+export type ExaAgentRunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+export type ExaAgentStopReason = 'schema_satisfied' | 'budget_reached' | 'error' | 'cancelled';
+
+export type ExaAgentEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'auto';
+
+export type ExaAgentConfidence = 'low' | 'medium' | 'high';
+
+export interface ExaAgentInput {
+  data?: JsonObject[];
+  exclusion?: JsonObject[];
+}
+
+export interface ExaAgentGroundingCitation {
+  url: string;
+  title?: string | null;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentGroundingEntry {
+  field?: string;
+  citations?: ExaAgentGroundingCitation[];
+  score?: number | null;
+  confidence?: ExaAgentConfidence | null;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentOutput {
+  text?: string | null;
+  structured?: unknown;
+  grounding?: ExaAgentGroundingEntry[] | null;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentUsage {
+  agentComputeUnits?: number;
+  searches?: number;
+  emails?: number;
+  phoneNumbers?: number;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentCostDollars {
+  total?: number;
+  agentCompute?: number;
+  search?: number;
+  emails?: number;
+  phoneNumbers?: number;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentError {
+  type?: string;
+  code?: string;
+  message?: string;
+  path?: string;
+  keyword?: string;
+  expected?: unknown;
+  actual?: unknown;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentRunRequest {
+  query?: string;
+  systemPrompt?: string;
+  input?: ExaAgentInput;
+  outputSchema?: JsonObject | null;
+  effort?: ExaAgentEffort;
+  previousRunId?: string;
+  metadata?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentRun {
+  id: string;
+  object?: string;
+  status: ExaAgentRunStatus;
+  stopReason?: ExaAgentStopReason | null;
+  createdAt?: string;
+  completedAt?: string | null;
+  request?: ExaAgentRunRequest | null;
+  output?: ExaAgentOutput | null;
+  usage?: ExaAgentUsage;
+  costDollars?: ExaAgentCostDollars;
+  error?: ExaAgentError;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentEvent {
+  id?: string;
+  event: string;
+  data: JsonObject;
+  createdAt?: string;
+  [key: string]: unknown;
+}
+
+export interface ExaAgentRunListResponse {
+  object?: string;
+  data: ExaAgentRun[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface ExaAgentEventListResponse {
+  object?: string;
+  data: ExaAgentEvent[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface ExaDeletedAgentRun {
+  id: string;
+  object?: string;
+  deleted: boolean;
+}
+
+export interface PreviewDetails {
+  kind: 'search' | 'contents' | 'answer' | 'agent';
+  summary: string;
+  lines: string[];
+  expandedLines?: string[];
+  truncated?: boolean;
+  fullOutputPath?: string;
+}
+
+export interface ExaToolDetails<TResponse = unknown, TRequest = unknown> {
+  endpoint: string;
+  request: TRequest;
+  response: TResponse;
+  requestId?: string;
+  count?: number;
+  costDollars?: JsonObject;
+  preview?: PreviewDetails;
+  truncated?: boolean;
+  truncation?: unknown;
+  fullOutputPath?: string;
+}

package/extensions/util.ts

@@ -0,0 +1,26 @@
+import type { JsonObject } from './types';
+
+export function asString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function isRecord(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function compactObject<T extends Record<string, unknown>>(input: T): Partial<T> {
+  const output: Partial<T> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) {
+      output[key as keyof T] = value as T[keyof T];
+    }
+  }
+  return output;
+}
+
+export function truncateText(text: string, maxCharacters: number): string {
+  if (text.length <= maxCharacters) return text;
+  return `${text.slice(0, Math.max(0, maxCharacters - 1)).trimEnd()}…`;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@alasano/pi-exa",
+  "version": "0.0.1",
+  "description": "Exa-powered web search, content retrieval, answers, and agentic search tools for pi",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasano/house-of-pi",
+    "directory": "packages/pi-exa"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/alasano/house-of-pi/master/packages/pi-exa/assets/screenshot.png"
+  },
+  "files": [
+    "extensions",
+    "skills",
+    "assets",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.79.9",
+    "@earendil-works/pi-tui": "^0.79.9"
+  }
+}

package/skills/exa-search/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: exa-search
+description: Web research with Exa search, advanced search, URL fetch, and sourced answers. Use when current web information, source discovery, page extraction, or sourced web answers are needed.
+---
+
+# Exa Search
+
+Use Exa with a search-first, context-disciplined workflow. Prefer small, high-signal calls that discover sources, then fetch only the pages that are worth reading.
+
+## Tool Choice
+
+- Use `web_search_exa` for normal web searches, current information lookup, source discovery, and quick orientation. It returns compact highlights.
+- Use `web_search_advanced_exa` when filters or content controls matter: domains, dates, categories, freshness, summaries, highlights, subpages, response-level context, or extracted text. It returns full per-result text by default; set `textMaxCharacters` when that would be too much.
+- Use `web_fetch_exa` after search when a specific URL needs fuller markdown content. Fetch selected URLs only.
+- Use `web_answer_exa` when a direct answer with citations is more useful than a result list, especially for factual questions or concise sourced summaries.
+- Use `web_agent_exa` only for deeper Agent workflows: multi-hop research, list building, row enrichment, entity research across many fields, or structured outputs that require broader web work than one search/answer/fetch call. Before using `web_agent_exa` or any `web_agent_*_exa` lifecycle tool, read `references/web-agent-exa.md`.
+- If the user's task could benefit from Exa Agent but would cost more or run longer than normal search, briefly recommend Agent as an option instead of using it silently.
+- After starting `web_agent_exa` with `mode: "background"`, do not repeatedly poll the run. The extension tracks it and sends a compact follow-up when it completes. Treat that follow-up as a notification, not the full result; call `web_agent_get_exa` before answering with detailed findings from the run.
+
+## Search Workflow
+
+1. Start with `web_search_exa` unless you already know you need filters or page text.
+2. Read result titles, URLs, and highlights. Identify the best sources before doing another call.
+3. Use `web_search_advanced_exa` to narrow by domain, date, category, geography, freshness, or content extraction. Remember that advanced search returns text by default.
+4. Use `web_fetch_exa` only for URLs that need closer inspection.
+5. Deduplicate similar results before answering. Keep only the best representative source for repeated articles, mirrors, copied docs, or forks.
+
+## Query Patterns
+
+- General research: describe the ideal source, not just keywords. Example: `independent analysis of 2026 US EV tax credit changes`.
+- Current events: include names, dates, organizations, and the event type. Use advanced search with date filters when recency matters.
+- Official documentation: include the product, API, version, and the exact concept. Prefer `includeDomains` for official domains when the source matters.
+- Code examples: include language, framework, major version, package name, and exact API. Example: `TypeScript React 19 useActionState form example`.
+- Error/debugging searches: include the exact error string, runtime, library, and version when known.
+- Comparison research: search each side explicitly, then dedupe and compare sources instead of relying on one broad query.
+
+## Advanced Search Recipes
+
+- Domain-restricted research: set `includeDomains` for official docs, vendor docs, standards bodies, or trusted publications.
+- Exclusions: set `excludeDomains` for sources that are duplicated, low quality, or not relevant to the user.
+- Date-sensitive research: use published or crawl date filters when older sources would mislead the answer.
+- Category search: use categories such as news, company, people, research paper, GitHub, PDF, financial report, or personal site when the source type matters.
+- Text extraction: advanced search requests full text by default. Set `textMaxCharacters` when each result should be bounded, especially for broad queries or many results.
+- Response context: set `contextMaxCharacters` when you want Exa to return a compact combined context string in addition to per-result fields.
+- Highlights: set `enableHighlights` when you want compact evidence in addition to text. Add `highlightsQuery` when the highlight should focus on a specific claim or API.
+- Summaries: set `enableSummary` when a short page-level summary is more useful than reading result text. Add `summaryQuery` to focus the summary.
+- Freshness: use `maxAgeHours` when cached content could be stale. Use small values for fast-moving pages and omit it when freshness is not important.
+- Subpages: use `subpages` and `subpageTarget` for docs sites where the useful answer may live below a landing page.
+
+## Fetch Guidance
+
+- Fetch after choosing URLs from search results, not as a substitute for search.
+- Keep `maxCharacters` tight by default. Increase it only when the selected URL is clearly worth reading in detail.
+- For several candidate URLs, fetch the strongest one or two first, then decide whether more context is needed.
+- Treat fetched text as more complete than search highlights, and keep track of where it came from.
+
+## Answer Guidance
+
+- Use `web_answer_exa` for direct factual questions, quick sourced summaries, and cases where a sourced answer is enough.
+- Use search instead when you need to compare sources, inspect exact wording, evaluate freshness, or gather multiple perspectives.
+- Set `text: true` only when citation page text is needed; it can make the result larger.
+- Use `outputSchema` when the answer must be structured JSON.
+
+## Agent Guidance
+
+`web_agent_exa` is a higher-compute async workflow tool, not the default search path. Use it when the job genuinely needs Agent behavior, and read `references/web-agent-exa.md` first for effort choices, foreground/background mode, schema design, lifecycle tools, cost notes, background tracking, and examples.
+
+## Context Discipline
+
+- Prefer highlights, summaries, and short fetched excerpts before large text dumps.
+- Use one good query before issuing variants. Refine based on observed sources.
+- Keep enough source information to support web-dependent claims when the answer needs it.
+- Separate what Exa returned from your own synthesis.
+- Do not paste raw Exa output when a concise answer with citations is enough.
+- If the result set is noisy, narrow the query or filters before fetching.
+
+## Output Guidance
+
+Answer in the format the user asked for. If no format was specified, give a clear, concise response that uses the searched information without dumping raw tool output.
+
+Include source links, excerpts, or uncertainty notes when they are useful for the task, when the user asked for them, or when the answer depends on a specific current source. Keep fetched excerpts short unless the user asks for detail.