@alasano/pi-exa 0.0.1

package/README.md

@@ -0,0 +1,109 @@
+# @alasano/pi-exa
+
+<p align="center">
+  <img src="assets/screenshot.png" alt="pi-exa settings overlay" />
+</p>
+
+<p align="center"><em>Configure Exa tools from the settings overlay.</em></p>
+
+---
+
+<p align="center">
+  <img src="assets/web_search_exa.png" alt="web_search_exa result preview" />
+</p>
+
+<p align="center"><em>Readable web search previews keep the UI clean while full tool output remains available to the agent.</em></p>
+
+[Exa](https://exa.ai)-powered web search, content retrieval, answers, and agentic search tools for [pi](https://pi.dev). This package has parity with the official Exa MCP server's current search and content-retrieval tools, then adds two Pi-specific capabilities: Exa's Answer API and the newly announced Exa Agent API for long-running research workflows.
+
+It also ships a bundled `exa-search` skill that guides the agent on when to search, when to fetch, when to use Answer, and when to escalate to Exa Agent without flooding context.
+
+## Prerequisites
+
+You need an [Exa API key](https://dashboard.exa.ai/api-keys).
+
+## Install
+
+```bash
+pi install npm:@alasano/pi-exa
+```
+
+## Authentication
+
+Set `EXA_API_KEY` in the environment before starting pi, or run:
+
+```sh
+/exa-auth set
+```
+
+The command stores credentials under the pi agent directory for this package only.
+
+## Settings
+
+Run `/exa-settings` to open the tool settings overlay. Search, advanced search, fetch, and answer can be toggled individually. Agent lifecycle tools are toggled as one group so create/get/list/cancel/delete/events stay consistent.
+
+Disabled tools are removed from the agent's active tool list immediately for the next turn.
+
+## Skill
+
+The package includes the `exa-search` skill. It guides the agent to:
+
+- start with lightweight search for source discovery
+- use advanced search only when filters or content controls matter
+- fetch selected URLs instead of dumping broad page text
+- use Answer for concise sourced answers
+- use the newly announced Exa Agent API for deeper multi-hop or long-running async research workflows
+- retrieve the full stored Agent result after compact background completion notices
+
+## Workflow
+
+Use the tools as a pipeline:
+
+1. `web_search_exa` for normal source discovery.
+2. `web_search_advanced_exa` when domains, dates, categories, freshness, summaries, highlights, subpages, or extracted text matter.
+3. `web_fetch_exa` for selected URLs that need full markdown content.
+4. `web_answer_exa` when a direct answer with sources is enough.
+5. `web_agent_exa` when the task is bigger than search: long-running research, multi-hop source gathering, or structured output across many sources.
+
+Foreground Agent runs return the full Agent result to the agent. Background Agent runs return promptly, show a persistent status panel, and send a compact completion notice that tells the agent to call `web_agent_get_exa` before using detailed findings.
+
+## Tools (10)
+
+### Search, Content, And Answers
+
+| Tool                      | Description                                                                                                                                              |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `web_search_exa`          | Search the web with compact, highlight-first results for normal source discovery.                                                                        |
+| `web_search_advanced_exa` | Search with filters and content controls: domains, dates, categories, freshness, summaries, highlights, subpages, text extraction, and response context. |
+| `web_fetch_exa`           | Retrieve clean markdown/text content from selected known URLs. Defaults to bounded content so fetches stay focused.                                      |
+| `web_answer_exa`          | Ask Exa's Answer API for a direct sourced answer when a result list would be too much.                                                                   |
+
+### Exa Agent
+
+`web_agent_exa` is the main Agent tool. Use it for high-value async workflows that need more than search/fetch/answer: long-running research, structured JSON output, or multi-hop source gathering.
+
+| Tool                   | Role                                                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `web_agent_exa`        | Create an Agent run. Supports foreground wait mode and background tracking.                                    |
+| `web_agent_get_exa`    | Retrieve the full stored Agent result, including text, structured output, citation grounding, usage, and cost. |
+| `web_agent_list_exa`   | List recent Agent runs to find IDs or inspect statuses.                                                        |
+| `web_agent_cancel_exa` | Cancel a queued or running Agent run.                                                                          |
+| `web_agent_delete_exa` | Delete a stored Agent run when explicitly requested.                                                           |
+| `web_agent_events_exa` | Inspect stored lifecycle events or replay the event stream for debugging/progress history.                     |
+
+## Agent Modes
+
+| Mode                              | Behavior                                                                                                                                                |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode: "wait", monitor: "stream"` | Foreground run with server-sent lifecycle events. Best default when the user needs the result in the current turn.                                      |
+| `mode: "wait", monitor: "poll"`   | Foreground run using `GET /agent/runs/{id}` polling. Useful if streaming is undesirable.                                                                |
+| `mode: "background"`              | Returns the run ID immediately, tracks the run in a pi widget, and sends a compact follow-up when it finishes. `monitor` is ignored in background mode. |
+
+## Output And Context Discipline
+
+- Search defaults to compact highlights rather than full page text.
+- Advanced search returns extracted text by default; use `textMaxCharacters` for broad queries.
+- Fetch is for selected known URLs, not broad discovery.
+- Agent foreground/get results return full structured output and citation grounding to the agent.
+- Background completion notices stay compact and instruct the agent to retrieve the full result before answering in detail.
+- Ctrl+O in the UI exposes expanded previews/raw API diagnostics without changing what the agent receives.

package/extensions/agent-tracker.ts

@@ -0,0 +1,258 @@
+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 } from '@earendil-works/pi-coding-agent';
+import { getAgentRun, isTerminalAgentStatus } from './agent';
+import { AgentRunsWidget } from './agent-widget';
+import { resolveApiKey } from './auth';
+import type { ExaAgentRun } from './types';
+import { asString, isRecord, truncateText } from './util';
+
+const TRACKED_RUNS_PATH = join(getAgentDir(), 'state', 'extensions', 'pi-exa', 'agent-runs.json');
+const DEFAULT_BACKGROUND_POLL_INTERVAL_MS = 10_000;
+const BACKGROUND_FOLLOW_UP_MAX_CHARS = 3000;
+const STATUS_KEY = 'pi-exa-agent';
+const WIDGET_KEY = 'pi-exa-agent-runs';
+
+export interface TrackedAgentRun {
+  runId: string;
+  query?: string;
+  createdAt?: string;
+  lastStatus?: string;
+  pollIntervalMs?: number;
+}
+
+function normalizeTrackedRun(value: unknown): TrackedAgentRun | undefined {
+  if (!isRecord(value)) return undefined;
+  const runId = asString(value.runId);
+  if (!runId) return undefined;
+
+  return {
+    runId,
+    query: asString(value.query),
+    createdAt: asString(value.createdAt),
+    lastStatus: asString(value.lastStatus),
+    pollIntervalMs:
+      typeof value.pollIntervalMs === 'number' && Number.isFinite(value.pollIntervalMs)
+        ? value.pollIntervalMs
+        : undefined,
+  };
+}
+
+async function readTrackedRuns(): Promise<TrackedAgentRun[]> {
+  try {
+    const raw = JSON.parse(await fs.readFile(TRACKED_RUNS_PATH, 'utf8'));
+    const runs = Array.isArray(raw?.runs) ? raw.runs : [];
+    const seen = new Set<string>();
+    return runs.flatMap((item: unknown) => {
+      const normalized = normalizeTrackedRun(item);
+      if (!normalized || seen.has(normalized.runId)) return [];
+      seen.add(normalized.runId);
+      return [normalized];
+    });
+  } catch {
+    return [];
+  }
+}
+
+async function writeTrackedRuns(runs: TrackedAgentRun[]): Promise<void> {
+  await fs.mkdir(dirname(TRACKED_RUNS_PATH), { recursive: true });
+  await fs.writeFile(TRACKED_RUNS_PATH, `${JSON.stringify({ runs }, null, 2)}\n`, 'utf8');
+}
+
+function makeFollowUp(run: ExaAgentRun): string {
+  const terminalLabel =
+    run.status === 'completed'
+      ? 'Exa Agent background run completed'
+      : `Exa Agent background run ${run.status}`;
+  const lines = [terminalLabel, `Run ID: ${run.id}`];
+
+  if (run.stopReason) lines.push(`Stop reason: ${run.stopReason}`);
+  if (run.costDollars?.total !== undefined) lines.push(`Cost: $${run.costDollars.total}`);
+  if (run.output?.text) lines.push(`Summary: ${truncateText(run.output.text, 800)}`);
+
+  const structuredSummary = summarizeStructuredOutput(run.output?.structured);
+  if (structuredSummary) lines.push(`Structured: ${structuredSummary}`);
+
+  const sourceUrls = collectSourceUrls(run).slice(0, 6);
+  if (sourceUrls.length > 0) {
+    lines.push('Sources:');
+    lines.push(...sourceUrls.map((url) => `- ${url}`));
+  }
+
+  lines.push('');
+  lines.push('This is a compact completion notice, not the full Agent result.');
+  lines.push(
+    `Before answering with details from this run, call web_agent_get_exa with runId "${run.id}". Do not poll unless more detail is needed.`,
+  );
+
+  return truncateText(lines.join('\n'), BACKGROUND_FOLLOW_UP_MAX_CHARS);
+}
+
+function summarizeStructuredOutput(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (Array.isArray(value)) return `array with ${value.length} item(s)`;
+  if (typeof value !== 'object') return truncateText(String(value), 300);
+
+  const entries = Object.entries(value as Record<string, unknown>);
+  const arrayEntry = entries.find(([, item]) => Array.isArray(item));
+  if (arrayEntry && Array.isArray(arrayEntry[1])) {
+    return `${arrayEntry[0]} has ${arrayEntry[1].length} item(s)`;
+  }
+
+  return `object with ${entries.length} field(s): ${entries
+    .slice(0, 8)
+    .map(([key]) => key)
+    .join(', ')}`;
+}
+
+function collectSourceUrls(run: ExaAgentRun): string[] {
+  const seen = new Set<string>();
+  const urls: string[] = [];
+
+  for (const grounding of run.output?.grounding || []) {
+    for (const citation of grounding.citations || []) {
+      if (!citation.url || seen.has(citation.url)) continue;
+      seen.add(citation.url);
+      urls.push(citation.url);
+    }
+  }
+
+  return urls;
+}
+
+export class AgentRunTracker {
+  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private widget: AgentRunsWidget | undefined;
+  private widgetContext: ExtensionContext | undefined;
+  private shuttingDown = false;
+
+  constructor(private readonly pi: ExtensionAPI) {}
+
+  async track(
+    run: ExaAgentRun,
+    options?: { pollIntervalMs?: number },
+    ctx?: ExtensionContext,
+  ): Promise<void> {
+    if (isTerminalAgentStatus(run.status)) return;
+
+    const runs = await readTrackedRuns();
+    const existing = runs.find((item) => item.runId === run.id);
+    const tracked: TrackedAgentRun = {
+      runId: run.id,
+      query: run.request?.query,
+      createdAt: run.createdAt,
+      lastStatus: run.status,
+      pollIntervalMs: options?.pollIntervalMs,
+    };
+
+    if (existing) {
+      Object.assign(existing, tracked);
+    } else {
+      runs.push(tracked);
+    }
+
+    await writeTrackedRuns(runs);
+    this.updateUi(ctx, runs);
+    this.startPolling(tracked, ctx);
+  }
+
+  async resume(ctx?: ExtensionContext): Promise<void> {
+    this.shuttingDown = false;
+    const runs = await readTrackedRuns();
+    this.updateUi(ctx, runs);
+    for (const run of runs) {
+      this.startPolling(run, ctx);
+    }
+  }
+
+  shutdown(ctx?: ExtensionContext): void {
+    this.shuttingDown = true;
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+    this.updateUi(ctx, []);
+  }
+
+  private startPolling(run: TrackedAgentRun, ctx?: ExtensionContext): void {
+    if (this.shuttingDown || this.timers.has(run.runId)) return;
+    this.schedule(run, ctx, 0);
+  }
+
+  private updateUi(ctx: ExtensionContext | undefined, runs: TrackedAgentRun[]): void {
+    if (!ctx?.hasUI) return;
+
+    if (runs.length === 0) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      ctx.ui.setWidget(WIDGET_KEY, undefined);
+      this.widget = undefined;
+      this.widgetContext = undefined;
+      return;
+    }
+
+    ctx.ui.setStatus(STATUS_KEY, `Exa Agent: ${runs.length} running`);
+    if (this.widget && this.widgetContext === ctx) {
+      this.widget.setRuns(runs);
+      return;
+    }
+
+    if (this.widget) {
+      this.widget.dispose();
+      this.widget = undefined;
+      this.widgetContext = undefined;
+    }
+
+    ctx.ui.setWidget(
+      WIDGET_KEY,
+      (tui, _theme) => {
+        this.widget = new AgentRunsWidget(tui, runs);
+        this.widgetContext = ctx;
+        return this.widget;
+      },
+      { placement: 'belowEditor' },
+    );
+  }
+
+  private schedule(run: TrackedAgentRun, ctx: ExtensionContext | undefined, delayMs: number): void {
+    if (this.shuttingDown) return;
+
+    const timer = setTimeout(() => {
+      this.timers.delete(run.runId);
+      void this.poll(run, ctx);
+    }, delayMs);
+    this.timers.set(run.runId, timer);
+  }
+
+  private async poll(run: TrackedAgentRun, ctx?: ExtensionContext): Promise<void> {
+    if (this.shuttingDown) return;
+
+    const { apiKey } = await resolveApiKey(ctx, { promptIfMissing: false });
+    if (!apiKey) return;
+
+    try {
+      const latest = await getAgentRun(apiKey, run.runId);
+      if (isTerminalAgentStatus(latest.status)) {
+        const runs = (await readTrackedRuns()).filter((item) => item.runId !== run.runId);
+        await writeTrackedRuns(runs);
+        this.updateUi(ctx, runs);
+        this.pi.sendUserMessage(makeFollowUp(latest), { deliverAs: 'followUp' });
+        return;
+      }
+
+      const runs = await readTrackedRuns();
+      const existing = runs.find((item) => item.runId === run.runId);
+      if (existing) {
+        existing.lastStatus = latest.status;
+        await writeTrackedRuns(runs);
+        this.updateUi(ctx, runs);
+      }
+    } catch {
+      // Keep the run tracked; transient API/network failures can be retried next interval.
+    }
+
+    this.schedule(
+      run,
+      ctx,
+      Math.max(1000, run.pollIntervalMs ?? DEFAULT_BACKGROUND_POLL_INTERVAL_MS),
+    );
+  }
+}

package/extensions/agent-widget.ts

@@ -0,0 +1,136 @@
+import { truncateToWidth, visibleWidth, type Component, type TUI } from '@earendil-works/pi-tui';
+import type { TrackedAgentRun } from './agent-tracker';
+
+const GOLD_FG = '\x1b[38;2;212;162;46m';
+const GREEN_FG = '\x1b[38;2;96;176;88m';
+const RESET_FG = '\x1b[39m';
+const SEPARATOR = ' │ ';
+const MIN_INNER = 34;
+const MAX_INNER = 96;
+
+function tint(text: string, color: string): string {
+  return `${color}${text}${RESET_FG}`;
+}
+
+function gold(text: string): string {
+  return tint(text, GOLD_FG);
+}
+
+function padVisible(text: string, width: number): string {
+  const deficit = width - visibleWidth(text);
+  return deficit <= 0 ? text : `${text}${' '.repeat(deficit)}`;
+}
+
+function panelHeaderLeft(title: string): string {
+  return `─ ${title} `;
+}
+
+function formatElapsed(createdAt: string | undefined): string | undefined {
+  if (!createdAt) return undefined;
+  const startedAt = Date.parse(createdAt);
+  if (!Number.isFinite(startedAt)) return undefined;
+
+  const seconds = Math.max(0, Math.floor((Date.now() - startedAt) / 1000));
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${String(minutes).padStart(2, '0')}:${String(remainingSeconds).padStart(2, '0')}`;
+}
+
+function runLabel(runs: TrackedAgentRun[]): string {
+  if (runs.length !== 1) return `${runs.length} running`;
+
+  const run = runs[0]!;
+  const status = run.lastStatus || 'running';
+  const elapsed = formatElapsed(run.createdAt);
+  return elapsed ? `${status} ${elapsed}` : status;
+}
+
+function taskText(runs: TrackedAgentRun[]): string {
+  const first = runs[0];
+  const base = first?.query || '(no query)';
+  return runs.length > 1 ? `${base} (+${runs.length - 1} more)` : base;
+}
+
+function renderRow(label: string, content: string, contentWidth: number): string {
+  const labelText = tint(label, GREEN_FG);
+  const valueWidth = Math.max(1, contentWidth - visibleWidth(label) - visibleWidth(SEPARATOR));
+  return `${labelText}${SEPARATOR}${truncateToWidth(content, valueWidth, '…', true)}`;
+}
+
+function framePanel(title: string, rightText: string, bodyLine: string, inner: number): string[] {
+  const leftHeader = panelHeaderLeft(title);
+  const rightSegment = rightText ? ` ${rightText} ` : '';
+  const fill = Math.max(1, inner - visibleWidth(leftHeader) - visibleWidth(rightSegment));
+  const top =
+    gold('╭') +
+    gold(leftHeader) +
+    gold('─'.repeat(fill)) +
+    (rightSegment ? gold(rightSegment) : '') +
+    gold('╮');
+  const bottom = gold('╰') + gold('─'.repeat(inner)) + gold('╯');
+  const contentWidth = Math.max(8, inner - 2);
+  return [top, gold('│ ') + padVisible(bodyLine, contentWidth) + gold(' │'), bottom];
+}
+
+function computeInnerWidth({
+  title,
+  rightText,
+  bodyWidth,
+  maxInner,
+}: {
+  title: string;
+  rightText: string;
+  bodyWidth: number;
+  maxInner: number;
+}): number {
+  const headerWidth = visibleWidth(panelHeaderLeft(title)) + visibleWidth(` ${rightText} `) + 1;
+  const naturalInner = Math.max(headerWidth, bodyWidth + 2);
+  return Math.max(Math.min(maxInner, naturalInner), Math.min(maxInner, MIN_INNER));
+}
+
+export class AgentRunsWidget implements Component {
+  private runs: TrackedAgentRun[];
+  private readonly timer: ReturnType<typeof setInterval>;
+
+  constructor(
+    private readonly tui: TUI,
+    runs: TrackedAgentRun[],
+  ) {
+    this.runs = runs.map((run) => ({ ...run }));
+    this.timer = setInterval(() => this.tui.requestRender(), 1000);
+  }
+
+  setRuns(runs: TrackedAgentRun[]): void {
+    this.runs = runs.map((run) => ({ ...run }));
+    this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    if (this.runs.length === 0) return [];
+
+    const safeWidth = Math.max(1, width);
+    const title = 'EXA AGENT';
+    const rightText = runLabel(this.runs);
+    const label = this.runs.length === 1 ? 'task' : 'tasks';
+    const content = taskText(this.runs).replace(/\s+/g, ' ').trim();
+    const naturalBodyWidth = visibleWidth(label) + visibleWidth(SEPARATOR) + visibleWidth(content);
+    const maxInner = Math.max(8, Math.min(safeWidth - 2, MAX_INNER));
+    const inner = computeInnerWidth({
+      title,
+      rightText,
+      bodyWidth: naturalBodyWidth,
+      maxInner,
+    });
+    const bodyLine = renderRow(label, content, Math.max(8, inner - 2));
+
+    return framePanel(title, rightText, bodyLine, inner).map((line) =>
+      truncateToWidth(line, safeWidth, '', true),
+    );
+  }
+
+  invalidate(): void {}
+
+  dispose(): void {
+    clearInterval(this.timer);
+  }
+}