@alasano/pi-exa 0.0.1

package/extensions/agent.ts

@@ -0,0 +1,289 @@
+import {
+  ExaApiError,
+  exaDelete,
+  exaGet,
+  exaPost,
+  exaRawRequest,
+  parseResponseBody,
+} from './client';
+import type {
+  ExaAgentEvent,
+  ExaAgentEventListResponse,
+  ExaAgentRun,
+  ExaAgentRunListResponse,
+  ExaDeletedAgentRun,
+  JsonObject,
+} from './types';
+import { isRecord } from './util';
+
+export const TERMINAL_AGENT_STATUSES = ['completed', 'failed', 'cancelled'] as const;
+
+export interface ExaAgentCreateRequest {
+  query: string;
+  systemPrompt?: string;
+  input?: {
+    data?: JsonObject[];
+    exclusion?: JsonObject[];
+  };
+  outputSchema?: JsonObject;
+  effort?: string;
+  previousRunId?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface ExaAgentPaginationParams {
+  limit?: number;
+  cursor?: string;
+  [key: string]: string | number | undefined;
+}
+
+export interface ExaAgentEventReplayParams {
+  lastEventId?: string;
+}
+
+export interface AgentPollOptions {
+  pollIntervalMs: number;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  onPoll?: (run: ExaAgentRun) => void;
+}
+
+export interface AgentPollResult {
+  run: ExaAgentRun;
+  timedOut: boolean;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error('Operation aborted.'));
+      return;
+    }
+
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timeout);
+        reject(signal.reason ?? new Error('Operation aborted.'));
+      },
+      { once: true },
+    );
+  });
+}
+
+function parseSsePart(part: string): ExaAgentEvent | undefined {
+  const event: Partial<ExaAgentEvent> = {};
+  const dataLines: string[] = [];
+
+  for (const line of part.split('\n')) {
+    if (!line || !line.includes(':')) continue;
+    const [field, ...rest] = line.split(':');
+    const value = rest.join(':').replace(/^ /, '');
+
+    if (field === 'id') event.id = value;
+    if (field === 'event') event.event = value;
+    if (field === 'data') dataLines.push(value);
+  }
+
+  if (!event.event || dataLines.length === 0) return undefined;
+
+  const data = dataLines.join('\n');
+  try {
+    const parsed = JSON.parse(data);
+    event.data = isRecord(parsed) ? parsed : { value: parsed };
+  } catch {
+    event.data = { value: data };
+  }
+
+  return event as ExaAgentEvent;
+}
+
+export function isTerminalAgentStatus(status: unknown): boolean {
+  return TERMINAL_AGENT_STATUSES.includes(status as (typeof TERMINAL_AGENT_STATUSES)[number]);
+}
+
+export function getRunIdFromAgentEvent(event: ExaAgentEvent): string | undefined {
+  if (typeof event.data.id === 'string') return event.data.id;
+  if (isRecord(event.data.run) && typeof event.data.run.id === 'string') return event.data.run.id;
+  if (typeof event.data.runId === 'string') return event.data.runId;
+  return undefined;
+}
+
+export async function createAgentRun(
+  apiKey: string,
+  request: ExaAgentCreateRequest,
+  signal?: AbortSignal,
+): Promise<ExaAgentRun> {
+  return exaPost<ExaAgentRun>(apiKey, '/agent/runs', request, signal);
+}
+
+export async function getAgentRun(
+  apiKey: string,
+  runId: string,
+  signal?: AbortSignal,
+): Promise<ExaAgentRun> {
+  return exaGet<ExaAgentRun>(apiKey, `/agent/runs/${encodeURIComponent(runId)}`, undefined, signal);
+}
+
+export async function listAgentRuns(
+  apiKey: string,
+  params: ExaAgentPaginationParams,
+  signal?: AbortSignal,
+): Promise<ExaAgentRunListResponse> {
+  return exaGet<ExaAgentRunListResponse>(apiKey, '/agent/runs', params, signal);
+}
+
+export async function cancelAgentRun(
+  apiKey: string,
+  runId: string,
+  signal?: AbortSignal,
+): Promise<ExaAgentRun> {
+  return exaPost<ExaAgentRun>(
+    apiKey,
+    `/agent/runs/${encodeURIComponent(runId)}/cancel`,
+    undefined,
+    signal,
+  );
+}
+
+export async function deleteAgentRun(
+  apiKey: string,
+  runId: string,
+  signal?: AbortSignal,
+): Promise<ExaDeletedAgentRun> {
+  return exaDelete<ExaDeletedAgentRun>(apiKey, `/agent/runs/${encodeURIComponent(runId)}`, signal);
+}
+
+export async function listAgentRunEvents(
+  apiKey: string,
+  runId: string,
+  params: ExaAgentPaginationParams,
+  signal?: AbortSignal,
+): Promise<ExaAgentEventListResponse> {
+  return exaGet<ExaAgentEventListResponse>(
+    apiKey,
+    `/agent/runs/${encodeURIComponent(runId)}/events`,
+    params,
+    signal,
+  );
+}
+
+async function* streamAgentEventsFromResponse(response: Response): AsyncGenerator<ExaAgentEvent> {
+  if (!response.body) throw new Error('No response body for Exa Agent event stream.');
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let finished = false;
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        finished = true;
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split('\n\n');
+      buffer = parts.pop() ?? '';
+
+      for (const part of parts) {
+        const event = parseSsePart(part);
+        if (event) yield event;
+      }
+    }
+
+    if (buffer.trim()) {
+      const event = parseSsePart(buffer.trim());
+      if (event) yield event;
+    }
+  } finally {
+    if (!finished) await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}
+
+export async function* streamAgentRunEvents(
+  apiKey: string,
+  request: ExaAgentCreateRequest,
+  signal?: AbortSignal,
+): AsyncGenerator<ExaAgentEvent> {
+  const response = await exaRawRequest(apiKey, '/agent/runs', {
+    method: 'POST',
+    body: request,
+    headers: { Accept: 'text/event-stream' },
+    signal,
+  });
+
+  if (!response.ok) {
+    const responseBody = await parseResponseBody(response);
+    throw new ExaApiError(
+      `Exa API request failed: ${
+        isRecord(responseBody) && typeof responseBody.message === 'string'
+          ? responseBody.message
+          : `${response.status} ${response.statusText}`
+      }`,
+      response.status,
+      responseBody,
+    );
+  }
+
+  if (!response.body) throw new Error('No response body for Exa Agent event stream.');
+
+  yield* streamAgentEventsFromResponse(response);
+}
+
+export async function* replayAgentRunEvents(
+  apiKey: string,
+  runId: string,
+  params: ExaAgentEventReplayParams = {},
+  signal?: AbortSignal,
+): AsyncGenerator<ExaAgentEvent> {
+  const headers: Record<string, string> = { Accept: 'text/event-stream' };
+  if (params.lastEventId) headers['Last-Event-ID'] = params.lastEventId;
+
+  const response = await exaRawRequest(apiKey, `/agent/runs/${encodeURIComponent(runId)}/events`, {
+    method: 'GET',
+    headers,
+    signal,
+  });
+
+  if (!response.ok) {
+    const responseBody = await parseResponseBody(response);
+    throw new ExaApiError(
+      `Exa API request failed: ${
+        isRecord(responseBody) && typeof responseBody.message === 'string'
+          ? responseBody.message
+          : `${response.status} ${response.statusText}`
+      }`,
+      response.status,
+      responseBody,
+    );
+  }
+
+  yield* streamAgentEventsFromResponse(response);
+}
+
+export async function pollAgentRunUntilFinished(
+  apiKey: string,
+  runId: string,
+  options: AgentPollOptions,
+): Promise<AgentPollResult> {
+  const start = Date.now();
+  let run = await getAgentRun(apiKey, runId, options.signal);
+  options.onPoll?.(run);
+
+  while (!isTerminalAgentStatus(run.status)) {
+    if (Date.now() - start >= options.timeoutMs) {
+      return { run, timedOut: true };
+    }
+
+    await sleep(options.pollIntervalMs, options.signal);
+    run = await getAgentRun(apiKey, runId, options.signal);
+    options.onPoll?.(run);
+  }
+
+  return { run, timedOut: false };
+}

package/extensions/auth.ts

@@ -0,0 +1,66 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getAgentDir, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { asString, isRecord } from './util';
+
+const CREDENTIALS_FILENAME = 'credentials.json';
+
+interface ExaCredentials {
+  apiKey?: string;
+}
+
+export function getCredentialFilePath() {
+  return join(getAgentDir(), 'extensions', 'pi-exa', CREDENTIALS_FILENAME);
+}
+
+export async function readCredentials(): Promise<ExaCredentials> {
+  try {
+    const raw = await fs.readFile(getCredentialFilePath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) return {};
+    return { apiKey: asString(parsed.apiKey) };
+  } catch {
+    return {};
+  }
+}
+
+export async function writeCredentials(apiKey: string): Promise<void> {
+  const filePath = getCredentialFilePath();
+  await fs.mkdir(dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify({ apiKey }, null, 2), { mode: 0o600 });
+  await fs.chmod(filePath, 0o600).catch(() => undefined);
+}
+
+export async function clearCredentials(): Promise<void> {
+  await fs.rm(getCredentialFilePath(), { force: true }).catch(() => undefined);
+}
+
+export async function resolveApiKey(
+  ctx?: ExtensionContext,
+  options?: { promptIfMissing?: boolean },
+): Promise<{ apiKey?: string; source: 'env' | 'credentials' | 'none' }> {
+  const envApiKey = asString(process.env.EXA_API_KEY);
+  if (envApiKey) return { apiKey: envApiKey, source: 'env' };
+
+  const credentials = await readCredentials();
+  if (credentials.apiKey) return { apiKey: credentials.apiKey, source: 'credentials' };
+
+  const promptIfMissing = options?.promptIfMissing ?? false;
+  if (promptIfMissing && ctx?.hasUI) {
+    const shouldSetKey = await ctx.ui.confirm(
+      'Exa API key required',
+      'No EXA_API_KEY env var or pi-exa credential is configured. Would you like to set one now?',
+    );
+    if (!shouldSetKey) return { source: 'none' };
+
+    const keyInput = await ctx.ui.input('Exa API key', 'exa_...');
+    const apiKey = asString(keyInput);
+    if (!apiKey) return { source: 'none' };
+
+    await writeCredentials(apiKey);
+    ctx.ui.notify('Exa API key saved for pi-exa', 'info');
+    return { apiKey, source: 'credentials' };
+  }
+
+  return { source: 'none' };
+}

package/extensions/client.ts

@@ -0,0 +1,146 @@
+import { isRecord } from './util';
+
+export const EXA_API_BASE_URL = 'https://api.exa.ai';
+
+export type ExaEndpoint =
+  | '/search'
+  | '/contents'
+  | '/answer'
+  | '/agent/runs'
+  | `/agent/runs/${string}`;
+
+export type ExaQueryParams = Record<string, string | number | boolean | undefined>;
+
+export type ExaMethod = 'GET' | 'POST' | 'DELETE';
+
+export interface ExaRequestOptions {
+  method?: ExaMethod;
+  body?: unknown;
+  query?: ExaQueryParams;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export class ExaApiError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly responseBody?: unknown,
+  ) {
+    super(message);
+    this.name = 'ExaApiError';
+  }
+}
+
+export async function parseResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return undefined;
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function errorMessage(body: unknown, fallback: string): string {
+  if (isRecord(body)) {
+    const message = body.message ?? body.error;
+    if (typeof message === 'string' && message.trim()) return message;
+  }
+  return fallback;
+}
+
+function buildUrl(endpoint: ExaEndpoint, query?: ExaQueryParams): string {
+  const url = new URL(`${EXA_API_BASE_URL}${endpoint}`);
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value !== undefined) url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
+export async function exaRawRequest(
+  apiKey: string,
+  endpoint: ExaEndpoint,
+  options: ExaRequestOptions = {},
+): Promise<Response> {
+  const headers: Record<string, string> = {
+    'x-api-key': apiKey,
+    'x-exa-integration': 'pi-exa',
+    ...options.headers,
+  };
+
+  let body: BodyInit | undefined;
+  if (options.body !== undefined) {
+    headers['Content-Type'] = headers['Content-Type'] ?? 'application/json';
+    body = JSON.stringify(options.body);
+  }
+
+  return fetch(buildUrl(endpoint, options.query), {
+    method: options.method ?? 'POST',
+    headers: {
+      ...headers,
+    },
+    body,
+    signal: options.signal,
+  });
+}
+
+export async function exaRequest<TResponse>(
+  apiKey: string,
+  endpoint: ExaEndpoint,
+  options: ExaRequestOptions = {},
+): Promise<TResponse> {
+  const response = await exaRawRequest(apiKey, endpoint, options);
+
+  const responseBody = await parseResponseBody(response);
+
+  if (!response.ok) {
+    throw new ExaApiError(
+      `Exa API request failed: ${errorMessage(responseBody, `${response.status} ${response.statusText}`)}`,
+      response.status,
+      responseBody,
+    );
+  }
+
+  return responseBody as TResponse;
+}
+
+export async function exaGet<TResponse>(
+  apiKey: string,
+  endpoint: ExaEndpoint,
+  query?: ExaQueryParams,
+  signal?: AbortSignal,
+): Promise<TResponse> {
+  return exaRequest<TResponse>(apiKey, endpoint, { method: 'GET', query, signal });
+}
+
+export async function exaPost<TResponse>(
+  apiKey: string,
+  endpoint: ExaEndpoint,
+  body: unknown,
+  signal?: AbortSignal,
+  headers?: Record<string, string>,
+): Promise<TResponse> {
+  return exaRequest<TResponse>(apiKey, endpoint, { method: 'POST', body, signal, headers });
+}
+
+export async function exaDelete<TResponse>(
+  apiKey: string,
+  endpoint: ExaEndpoint,
+  signal?: AbortSignal,
+): Promise<TResponse> {
+  return exaRequest<TResponse>(apiKey, endpoint, { method: 'DELETE', signal });
+}
+
+export function formatToolError(error: unknown): string {
+  if (error instanceof ExaApiError) {
+    if (error.status === 401 || error.status === 403) {
+      return `${error.message}\n\nSet EXA_API_KEY before starting pi or run /exa-auth set.`;
+    }
+    return error.message;
+  }
+
+  if (error instanceof Error) return error.message;
+  return String(error);
+}