@alasano/pi-exa 0.0.1

package/extensions/settings.ts

@@ -0,0 +1,263 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { getAgentDir, getSettingsListTheme } from '@earendil-works/pi-coding-agent';
+import { type SettingItem, SettingsList } from '@earendil-works/pi-tui';
+import { isRecord } from './util';
+
+const SETTINGS_PATH = join(getAgentDir(), 'state', 'extensions', 'pi-exa', 'tool-settings.json');
+const OVERLAY_MAX_INNER = 60;
+const GOLD_FG = '\x1b[38;2;212;162;46m';
+const RESET_FG = '\x1b[39m';
+const ANSI_RE = new RegExp(String.fromCharCode(0x1b) + '\\[[0-9;]*m', 'g');
+
+const PRIMARY_TOOL_ITEMS = [
+  { id: 'web_search_exa', label: 'web_search_exa' },
+  { id: 'web_search_advanced_exa', label: 'web_search_advanced_exa' },
+  { id: 'web_fetch_exa', label: 'web_fetch_exa' },
+  { id: 'web_answer_exa', label: 'web_answer_exa' },
+] as const;
+
+export const AGENT_TOOL_NAMES = [
+  'web_agent_exa',
+  'web_agent_get_exa',
+  'web_agent_list_exa',
+  'web_agent_cancel_exa',
+  'web_agent_delete_exa',
+  'web_agent_events_exa',
+] as const;
+
+export const ALL_EXA_TOOLS = [
+  ...PRIMARY_TOOL_ITEMS.map((item) => item.id),
+  ...AGENT_TOOL_NAMES,
+] as const;
+
+type ToolSettings = {
+  disabledTools: string[];
+};
+
+function checkboxValue(enabled: boolean): string {
+  return enabled ? '[x]' : '[ ]';
+}
+
+function gold(text: string): string {
+  return `${GOLD_FG}${text}${RESET_FG}`;
+}
+
+function isKnownExaTool(tool: string): tool is (typeof ALL_EXA_TOOLS)[number] {
+  return (ALL_EXA_TOOLS as readonly string[]).includes(tool);
+}
+
+export function normalizeExaToolSettings(raw: unknown): ToolSettings {
+  if (!isRecord(raw) || !Array.isArray(raw.disabledTools)) return { disabledTools: [] };
+
+  const disabled = raw.disabledTools.filter(
+    (tool: unknown): tool is string => typeof tool === 'string' && isKnownExaTool(tool),
+  );
+  const agentDisabled = disabled.some((tool) =>
+    (AGENT_TOOL_NAMES as readonly string[]).includes(tool),
+  );
+
+  return {
+    disabledTools: [
+      ...PRIMARY_TOOL_ITEMS.flatMap((item) => (disabled.includes(item.id) ? [item.id] : [])),
+      ...(agentDisabled ? [...AGENT_TOOL_NAMES] : []),
+    ],
+  };
+}
+
+function createDefaultSettings(): ToolSettings {
+  return { disabledTools: [] };
+}
+
+async function loadSettings(): Promise<ToolSettings> {
+  try {
+    return normalizeExaToolSettings(JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf8')));
+  } catch {
+    return createDefaultSettings();
+  }
+}
+
+async function saveSettings(settings: ToolSettings): Promise<boolean> {
+  try {
+    await fs.mkdir(dirname(SETTINGS_PATH), { recursive: true });
+    await fs.writeFile(SETTINGS_PATH, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function applySettings(pi: ExtensionAPI, settings: ToolSettings): void {
+  const currentTools = pi.getActiveTools();
+  const nonExaTools = currentTools.filter((tool) => !isKnownExaTool(tool));
+  const enabledExaTools = ALL_EXA_TOOLS.filter((tool) => !settings.disabledTools.includes(tool));
+  pi.setActiveTools([...nonExaTools, ...enabledExaTools]);
+}
+
+function isToolEnabled(settings: ToolSettings, tool: string): boolean {
+  return !settings.disabledTools.includes(tool);
+}
+
+function areAgentToolsEnabled(settings: ToolSettings): boolean {
+  return AGENT_TOOL_NAMES.every((tool) => isToolEnabled(settings, tool));
+}
+
+function buildItems(settings: ToolSettings): SettingItem[] {
+  return [
+    ...PRIMARY_TOOL_ITEMS.map((tool) => ({
+      id: tool.id,
+      label: tool.label,
+      currentValue: checkboxValue(isToolEnabled(settings, tool.id)),
+      values: ['[x]', '[ ]'],
+    })),
+    {
+      id: 'agent-tools',
+      label: `web_agent_exa + ${AGENT_TOOL_NAMES.length - 1} other tools`,
+      currentValue: checkboxValue(areAgentToolsEnabled(settings)),
+      values: ['[x]', '[ ]'],
+    },
+  ];
+}
+
+function stripAnsi(text: string): string {
+  return text.replace(ANSI_RE, '');
+}
+
+function visibleWidth(text: string): number {
+  return stripAnsi(text).length;
+}
+
+function padVisible(text: string, width: number): string {
+  const deficit = width - visibleWidth(text);
+  if (deficit <= 0) return text;
+  return `${text}${' '.repeat(deficit)}`;
+}
+
+function computeOverlayInner(bodyLines: string[], availableWidth: number): number {
+  const maxInner = Math.max(24, Math.min(availableWidth - 2, OVERLAY_MAX_INNER));
+  return Math.max(
+    24,
+    Math.min(
+      maxInner,
+      Math.max(...bodyLines.map((line) => visibleWidth(line)), visibleWidth('─ EXA TOOLS ')) + 2,
+    ),
+  );
+}
+
+function frameBody(title: string, bodyLines: string[], inner: number): string[] {
+  const leftHeader = `─ ${title} `;
+  const fill = Math.max(1, inner - leftHeader.length);
+  const top = gold('╭') + gold(leftHeader) + gold('─'.repeat(fill)) + gold('╮');
+  const bottom = gold('╰') + gold('─'.repeat(inner)) + gold('╯');
+  const contentWidth = Math.max(8, inner - 2);
+  const framedBody = bodyLines.map(
+    (line) => gold('│ ') + padVisible(line, contentWidth) + gold(' │'),
+  );
+  return [top, ...framedBody, bottom];
+}
+
+async function showToolSettingsOverlay(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  settings: ToolSettings,
+): Promise<void> {
+  const items = buildItems(settings);
+  const settingsTheme = getSettingsListTheme();
+  const maxVisibleItems = Math.min(items.length + 2, 12);
+
+  const probeList = new SettingsList(
+    items,
+    maxVisibleItems,
+    settingsTheme,
+    () => {},
+    () => {},
+  );
+  const probeLines = probeList.render(Math.max(8, OVERLAY_MAX_INNER - 2));
+  const overlayBodyLines = ['Configure Exa tools', '', ...probeLines];
+  const overlayWidth = computeOverlayInner(overlayBodyLines, OVERLAY_MAX_INNER + 2) + 2;
+
+  await ctx.ui.custom(
+    (_tui, theme, _kb, done) => {
+      const settingsList = new SettingsList(
+        items,
+        maxVisibleItems,
+        settingsTheme,
+        async (id, newValue) => {
+          const nextEnabled = newValue === '[x]';
+
+          if (id === 'agent-tools') {
+            settings.disabledTools = nextEnabled
+              ? settings.disabledTools.filter(
+                  (tool) => !(AGENT_TOOL_NAMES as readonly string[]).includes(tool),
+                )
+              : [
+                  ...settings.disabledTools.filter(
+                    (tool) => !(AGENT_TOOL_NAMES as readonly string[]).includes(tool),
+                  ),
+                  ...AGENT_TOOL_NAMES,
+                ];
+          } else if (nextEnabled) {
+            settings.disabledTools = settings.disabledTools.filter((tool) => tool !== id);
+          } else {
+            settings.disabledTools = [...settings.disabledTools.filter((tool) => tool !== id), id];
+          }
+
+          const normalized = normalizeExaToolSettings(settings);
+          settings.disabledTools = normalized.disabledTools;
+          settingsList.updateValue('agent-tools', checkboxValue(areAgentToolsEnabled(settings)));
+
+          await saveSettings(settings);
+          applySettings(pi, settings);
+        },
+        () => done(undefined),
+      );
+
+      return {
+        render(width: number) {
+          const safeWidth = Math.max(24, width);
+          const provisionalInner = Math.max(24, Math.min(safeWidth - 2, OVERLAY_MAX_INNER));
+          const listLines = settingsList.render(Math.max(8, provisionalInner - 2));
+          const bodyLines = [theme.fg('muted', 'Configure Exa tools'), '', ...listLines];
+          const naturalInner = computeOverlayInner(bodyLines, safeWidth);
+          return frameBody('EXA TOOLS', bodyLines, naturalInner);
+        },
+        invalidate() {
+          settingsList.invalidate();
+        },
+        handleInput(data: string) {
+          settingsList.handleInput?.(data);
+        },
+      };
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: 'center',
+        width: overlayWidth,
+      },
+    },
+  );
+}
+
+export async function registerExaSettings(pi: ExtensionAPI): Promise<void> {
+  let settings = await loadSettings();
+
+  pi.registerCommand('exa-settings', {
+    description: 'Open Exa tool settings',
+    handler: async (_args, ctx) => {
+      settings = await loadSettings();
+      await showToolSettingsOverlay(pi, ctx, settings);
+    },
+  });
+
+  pi.on('session_start', async (_event, _ctx) => {
+    settings = await loadSettings();
+    applySettings(pi, settings);
+  });
+
+  pi.on('session_before_switch', async (_event, _ctx) => {
+    settings = await loadSettings();
+    applySettings(pi, settings);
+  });
+}

package/extensions/tools/helpers.ts

@@ -0,0 +1,26 @@
+import type { ExtensionContext, ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { formatToolError } from '../client';
+import { resolveApiKey } from '../auth';
+
+export async function withExaApiKey<T>(
+  ctx: ExtensionContext,
+  callback: (apiKey: string) => Promise<T>,
+): Promise<T> {
+  const { apiKey } = await resolveApiKey(ctx, { promptIfMissing: true });
+  if (!apiKey) {
+    throw new Error(
+      'No Exa API key configured. Set EXA_API_KEY before starting pi or run /exa-auth set.',
+    );
+  }
+  return callback(apiKey);
+}
+
+export function errorResult(error: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: formatToolError(error) }],
+    details: undefined,
+    isError: true,
+  };
+}
+
+export type AnyExaTool = ToolDefinition<any, any, any>;

package/extensions/tools/index.ts

@@ -0,0 +1,28 @@
+import type { AgentRunTracker } from '../agent-tracker';
+import { createWebAnswerTool } from './web-answer';
+import { createWebAgentTool } from './web-agent';
+import {
+  createWebAgentCancelTool,
+  createWebAgentDeleteTool,
+  createWebAgentEventsTool,
+  createWebAgentGetTool,
+  createWebAgentListTool,
+} from './web-agent-runs';
+import { createWebFetchTool } from './web-fetch';
+import { createWebSearchTool } from './web-search';
+import { createWebSearchAdvancedTool } from './web-search-advanced';
+
+export function createExaTools(tracker: AgentRunTracker) {
+  return [
+    createWebSearchTool(),
+    createWebSearchAdvancedTool(),
+    createWebFetchTool(),
+    createWebAnswerTool(),
+    createWebAgentTool(tracker),
+    createWebAgentGetTool(),
+    createWebAgentListTool(),
+    createWebAgentCancelTool(),
+    createWebAgentDeleteTool(),
+    createWebAgentEventsTool(),
+  ];
+}

package/extensions/tools/web-agent-runs.ts

@@ -0,0 +1,377 @@
+import { defineTool } from '@earendil-works/pi-coding-agent';
+import type { Static } from '@sinclair/typebox';
+import {
+  cancelAgentRun,
+  deleteAgentRun,
+  getAgentRun,
+  listAgentRunEvents,
+  listAgentRuns,
+  replayAgentRunEvents,
+} from '../agent';
+import {
+  countAgentSources,
+  formatAgentEventListResponse,
+  formatAgentRunListResponse,
+  formatAgentRunResponse,
+  formatDeletedAgentRun,
+} from '../format';
+import { truncateToolOutput } from '../output';
+import {
+  buildAgentEventListPreview,
+  buildAgentRunListPreview,
+  buildAgentRunPreview,
+  buildDeletedAgentRunPreview,
+  metadataFromArgs,
+  renderExaCall,
+  renderExaResult,
+  sendProgress,
+} from '../render';
+import {
+  WebAgentEventsParamsSchema,
+  WebAgentListParamsSchema,
+  WebAgentRunParamsSchema,
+} from '../schemas';
+import type {
+  ExaAgentEventListResponse,
+  ExaAgentRun,
+  ExaAgentRunListResponse,
+  ExaDeletedAgentRun,
+  ExaToolDetails,
+} from '../types';
+import { compactObject } from '../util';
+import { errorResult, withExaApiKey } from './helpers';
+
+type WebAgentRunParams = Static<typeof WebAgentRunParamsSchema>;
+type WebAgentListParams = Static<typeof WebAgentListParamsSchema>;
+type WebAgentEventsParams = Static<typeof WebAgentEventsParamsSchema>;
+
+export interface AgentPaginationRequest {
+  limit?: number;
+  cursor?: string;
+  [key: string]: string | number | undefined;
+}
+
+export function buildAgentPaginationRequest(
+  params: WebAgentListParams | WebAgentEventsParams,
+): AgentPaginationRequest {
+  return compactObject({
+    limit: params.limit,
+    cursor: params.cursor,
+  }) as AgentPaginationRequest;
+}
+
+export interface AgentEventReplayRequest {
+  lastEventId?: string;
+}
+
+export function buildAgentEventReplayRequest(
+  params: WebAgentEventsParams,
+): AgentEventReplayRequest {
+  return compactObject({
+    lastEventId: params.lastEventId,
+  }) as AgentEventReplayRequest;
+}
+
+async function collectAsync<T>(items: AsyncIterable<T>): Promise<T[]> {
+  const output: T[] = [];
+  for await (const item of items) output.push(item);
+  return output;
+}
+
+export function createWebAgentGetTool() {
+  return defineTool<
+    typeof WebAgentRunParamsSchema,
+    ExaToolDetails<ExaAgentRun, WebAgentRunParams> | undefined
+  >({
+    name: 'web_agent_get_exa',
+    label: 'Exa Agent Get Run',
+    description:
+      'Retrieve a stored Exa Agent run by ID, including output, sources, usage, and cost.',
+    promptSnippet: 'Get an Exa Agent run by ID',
+    promptGuidelines: [
+      'Use web_agent_get_exa to inspect a known Agent run ID, including completed background runs. It returns the full Agent result payload, including structured output and grounding.',
+      'If a run is still queued or running, inspect events only when the user asked for progress/history; otherwise wait for background completion or user direction.',
+      'Do not repeatedly call web_agent_get_exa for a background run started by web_agent_exa; pi-exa tracks background completion and sends a follow-up.',
+    ],
+    parameters: WebAgentRunParamsSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      try {
+        return await withExaApiKey(ctx, async (apiKey) => {
+          const response = await getAgentRun(apiKey, params.runId, signal);
+          const output = await truncateToolOutput(
+            formatAgentRunResponse(response),
+            'web-agent-get-exa',
+            'Use a narrower Agent output schema for future runs, or inspect only events with web_agent_events_exa. ',
+            { maxLines: Number.MAX_SAFE_INTEGER, maxBytes: Number.MAX_SAFE_INTEGER },
+          );
+
+          return {
+            content: [{ type: 'text', text: output.text }],
+            details: {
+              endpoint: `/agent/runs/${params.runId}`,
+              request: params,
+              response,
+              requestId: response.id,
+              count: countAgentSources(response.output?.grounding),
+              costDollars: response.costDollars,
+              preview: buildAgentRunPreview(response, output),
+              truncated: output.truncation.truncated,
+              truncation: output.truncation,
+              fullOutputPath: output.fullOutputPath,
+            },
+            isError: response.status === 'failed',
+          };
+        });
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+    renderCall(args, theme) {
+      return renderExaCall('web_agent_get_exa', args.runId, theme);
+    },
+    renderResult(result, options, theme) {
+      return renderExaResult(result, options, theme, 'Getting Exa Agent run...');
+    },
+  });
+}
+
+export function createWebAgentListTool() {
+  return defineTool<
+    typeof WebAgentListParamsSchema,
+    ExaToolDetails<ExaAgentRunListResponse, AgentPaginationRequest> | undefined
+  >({
+    name: 'web_agent_list_exa',
+    label: 'Exa Agent List Runs',
+    description: 'List recent Exa Agent runs, with pagination support.',
+    promptSnippet: 'List recent Exa Agent runs',
+    promptGuidelines: [
+      'Use web_agent_list_exa when the user needs to find a run ID or inspect recent Agent run statuses.',
+      'Use cursor for pagination only when the first page does not contain the needed run.',
+      'Do not use web_agent_list_exa as a polling loop for a background run started in this session.',
+    ],
+    parameters: WebAgentListParamsSchema,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const request = buildAgentPaginationRequest(params);
+      try {
+        return await withExaApiKey(ctx, async (apiKey) => {
+          sendProgress(onUpdate, 'Listing Exa Agent runs...');
+          const response = await listAgentRuns(apiKey, request, signal);
+          const output = await truncateToolOutput(
+            formatAgentRunListResponse(response),
+            'web-agent-list-exa',
+            'Use a smaller limit, cursor pagination, or web_agent_get_exa for one run. ',
+          );
+
+          return {
+            content: [{ type: 'text', text: output.text }],
+            details: {
+              endpoint: '/agent/runs',
+              request,
+              response,
+              count: response.data?.length ?? 0,
+              preview: buildAgentRunListPreview(response, output),
+              truncated: output.truncation.truncated,
+              truncation: output.truncation,
+              fullOutputPath: output.fullOutputPath,
+            },
+          };
+        });
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+    renderCall(args, theme) {
+      return renderExaCall(
+        'web_agent_list_exa',
+        'recent runs',
+        theme,
+        metadataFromArgs(args, ['limit', 'cursor']),
+      );
+    },
+    renderResult(result, options, theme) {
+      return renderExaResult(result, options, theme, 'Listing Exa Agent runs...');
+    },
+  });
+}
+
+export function createWebAgentCancelTool() {
+  return defineTool<
+    typeof WebAgentRunParamsSchema,
+    ExaToolDetails<ExaAgentRun, WebAgentRunParams> | undefined
+  >({
+    name: 'web_agent_cancel_exa',
+    label: 'Exa Agent Cancel Run',
+    description: 'Cancel a queued or running Exa Agent run.',
+    promptSnippet: 'Cancel an Exa Agent run',
+    promptGuidelines: [
+      'Use web_agent_cancel_exa only when the user wants to stop a known queued or running Agent run.',
+      'After cancellation, use web_agent_get_exa if the user wants the stored final status and cost.',
+    ],
+    parameters: WebAgentRunParamsSchema,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      try {
+        return await withExaApiKey(ctx, async (apiKey) => {
+          sendProgress(onUpdate, `Cancelling Exa Agent run ${params.runId}...`);
+          const response = await cancelAgentRun(apiKey, params.runId, signal);
+          const output = await truncateToolOutput(
+            formatAgentRunResponse(response),
+            'web-agent-cancel-exa',
+            'Use web_agent_get_exa for the run ID if more detail is needed. ',
+          );
+
+          return {
+            content: [{ type: 'text', text: output.text }],
+            details: {
+              endpoint: `/agent/runs/${params.runId}/cancel`,
+              request: params,
+              response,
+              requestId: response.id,
+              costDollars: response.costDollars,
+              preview: buildAgentRunPreview(response, output),
+              truncated: output.truncation.truncated,
+              truncation: output.truncation,
+              fullOutputPath: output.fullOutputPath,
+            },
+            isError: response.status === 'failed',
+          };
+        });
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+    renderCall(args, theme) {
+      return renderExaCall('web_agent_cancel_exa', args.runId, theme);
+    },
+    renderResult(result, options, theme) {
+      return renderExaResult(result, options, theme, 'Cancelling Exa Agent run...');
+    },
+  });
+}
+
+export function createWebAgentDeleteTool() {
+  return defineTool<
+    typeof WebAgentRunParamsSchema,
+    ExaToolDetails<ExaDeletedAgentRun, WebAgentRunParams> | undefined
+  >({
+    name: 'web_agent_delete_exa',
+    label: 'Exa Agent Delete Run',
+    description: 'Delete a stored Exa Agent run by ID.',
+    promptSnippet: 'Delete a stored Exa Agent run',
+    promptGuidelines: [
+      'Use web_agent_delete_exa only when the user explicitly wants to delete a stored Agent run.',
+      'Deletion removes the stored run from Exa; prefer web_agent_cancel_exa for stopping active work.',
+    ],
+    parameters: WebAgentRunParamsSchema,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      try {
+        return await withExaApiKey(ctx, async (apiKey) => {
+          sendProgress(onUpdate, `Deleting Exa Agent run ${params.runId}...`);
+          const response = await deleteAgentRun(apiKey, params.runId, signal);
+          const output = await truncateToolOutput(
+            formatDeletedAgentRun(response),
+            'web-agent-delete-exa',
+            'List runs with web_agent_list_exa if you need another run ID. ',
+          );
+
+          return {
+            content: [{ type: 'text', text: output.text }],
+            details: {
+              endpoint: `/agent/runs/${params.runId}`,
+              request: params,
+              response,
+              requestId: response.id,
+              preview: buildDeletedAgentRunPreview(response, output),
+              truncated: output.truncation.truncated,
+              truncation: output.truncation,
+              fullOutputPath: output.fullOutputPath,
+            },
+            isError: !response.deleted,
+          };
+        });
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+    renderCall(args, theme) {
+      return renderExaCall('web_agent_delete_exa', args.runId, theme);
+    },
+    renderResult(result, options, theme) {
+      return renderExaResult(result, options, theme, 'Deleting Exa Agent run...');
+    },
+  });
+}
+
+export function createWebAgentEventsTool() {
+  return defineTool<
+    typeof WebAgentEventsParamsSchema,
+    ExaToolDetails<ExaAgentEventListResponse, WebAgentEventsParams> | undefined
+  >({
+    name: 'web_agent_events_exa',
+    label: 'Exa Agent Run Events',
+    description: 'List stored lifecycle events for an Exa Agent run.',
+    promptSnippet: 'List events for an Exa Agent run',
+    promptGuidelines: [
+      'Use web_agent_events_exa to inspect lifecycle progress or replay stored events for a known Agent run.',
+      'Use web_agent_get_exa when the user needs the run output rather than event history.',
+      'Do not call web_agent_events_exa repeatedly for background runs; the extension tracks background completion and sends a follow-up.',
+    ],
+    parameters: WebAgentEventsParamsSchema,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const request = params;
+      const pagination = buildAgentPaginationRequest(params);
+      const replay = buildAgentEventReplayRequest(params);
+      try {
+        return await withExaApiKey(ctx, async (apiKey) => {
+          sendProgress(
+            onUpdate,
+            params.replay
+              ? `Replaying events for Exa Agent run ${params.runId}...`
+              : `Listing events for Exa Agent run ${params.runId}...`,
+          );
+          const response = params.replay
+            ? {
+                object: 'list',
+                data: await collectAsync(
+                  replayAgentRunEvents(apiKey, params.runId, replay, signal),
+                ),
+                hasMore: false,
+                nextCursor: null,
+              }
+            : await listAgentRunEvents(apiKey, params.runId, pagination, signal);
+          const output = await truncateToolOutput(
+            formatAgentEventListResponse(response),
+            'web-agent-events-exa',
+            'Use a smaller limit, cursor pagination, replay with lastEventId, or web_agent_get_exa for run output. ',
+          );
+
+          return {
+            content: [{ type: 'text', text: output.text }],
+            details: {
+              endpoint: `/agent/runs/${params.runId}/events`,
+              request,
+              response,
+              count: response.data?.length ?? 0,
+              preview: buildAgentEventListPreview(response, output),
+              truncated: output.truncation.truncated,
+              truncation: output.truncation,
+              fullOutputPath: output.fullOutputPath,
+            },
+          };
+        });
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+    renderCall(args, theme) {
+      return renderExaCall(
+        'web_agent_events_exa',
+        args.runId,
+        theme,
+        metadataFromArgs(args, ['limit', 'cursor', 'replay', 'lastEventId']),
+      );
+    },
+    renderResult(result, options, theme) {
+      return renderExaResult(result, options, theme, 'Listing Exa Agent run events...');
+    },
+  });
+}