@alasano/pi-exa 0.0.1

package/extensions/render.ts

@@ -0,0 +1,394 @@
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  Theme,
+  ToolRenderResultOptions,
+} from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import type {
+  ExaAgentEventListResponse,
+  ExaAgentRun,
+  ExaAgentRunListResponse,
+  ExaDeletedAgentRun,
+  ExaAnswerResponse,
+  ExaContentsResponse,
+  ExaSearchResponse,
+  ExaSearchResult,
+  PreviewDetails,
+} from './types';
+import { asString } from './util';
+import type { TruncatedToolOutput } from './output';
+
+const DEFAULT_UI_PREVIEW_RESULT_COUNT = 3;
+const DEFAULT_UI_PREVIEW_EXCERPT_CHARS = 220;
+
+type ToolArgs = Record<string, unknown>;
+
+function normalizeWhitespace(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function stringifyValue(value: unknown): string | undefined {
+  if (typeof value === 'string') return value.trim() || undefined;
+  if (value === undefined || value === null) return undefined;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function toExcerpt(text: string | undefined, maxChars = DEFAULT_UI_PREVIEW_EXCERPT_CHARS) {
+  if (!text) return undefined;
+  const normalized = normalizeWhitespace(text);
+  if (!normalized) return undefined;
+  return normalized.length > maxChars
+    ? `${normalized.slice(0, Math.max(0, maxChars - 1)).trimEnd()}...`
+    : normalized;
+}
+
+function resultExcerpt(result: ExaSearchResult): string | undefined {
+  return (
+    toExcerpt(result.highlights?.join(' ')) ||
+    toExcerpt(stringifyValue(result.summary)) ||
+    toExcerpt(result.text)
+  );
+}
+
+function previewLinesFromResults(results: ExaSearchResult[]): string[] {
+  return results.slice(0, DEFAULT_UI_PREVIEW_RESULT_COUNT).flatMap((result, index) => {
+    const title =
+      asString(result.title) || asString(result.url) || asString(result.id) || 'Untitled';
+    const lines = [`${index + 1}. ${title}`];
+    if (result.url) lines.push(`   ${result.url}`);
+    const excerpt = resultExcerpt(result);
+    if (excerpt) lines.push(`   ${excerpt}`);
+    return lines;
+  });
+}
+
+function buildStatusSummary(statuses: ExaSearchResponse['statuses']): string | undefined {
+  if (!statuses?.length) return undefined;
+  const counts = new Map<string, number>();
+  for (const status of statuses) {
+    const key = asString(status.status) || 'unknown';
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([status, count]) => `${status}: ${count}`).join(' | ');
+}
+
+function previewFromOutput(output: TruncatedToolOutput) {
+  return {
+    truncated: output.truncation.truncated,
+    fullOutputPath: output.fullOutputPath,
+  };
+}
+
+export function buildSearchPreview(
+  response: ExaSearchResponse,
+  output: TruncatedToolOutput,
+): PreviewDetails {
+  const results = response.results || [];
+  const lines = previewLinesFromResults(results);
+  const synthesizedOutput = toExcerpt(stringifyValue(response.output?.content));
+  if (synthesizedOutput) lines.unshift(`Output: ${synthesizedOutput}`);
+
+  const statusSummary = buildStatusSummary(response.statuses);
+  if (statusSummary) lines.unshift(`Statuses: ${statusSummary}`);
+
+  return {
+    kind: 'search',
+    summary: `${results.length} result(s)`,
+    lines,
+    expandedLines: lines,
+    ...previewFromOutput(output),
+  };
+}
+
+export function buildContentsPreview(
+  response: ExaContentsResponse,
+  urlCount: number,
+  output: TruncatedToolOutput,
+): PreviewDetails {
+  const results = response.results || [];
+  const lines = previewLinesFromResults(results);
+  const statusSummary = buildStatusSummary(response.statuses);
+  if (statusSummary) lines.unshift(`Statuses: ${statusSummary}`);
+
+  return {
+    kind: 'contents',
+    summary: `${results.length} item(s) from ${urlCount} URL(s)`,
+    lines,
+    expandedLines: lines,
+    ...previewFromOutput(output),
+  };
+}
+
+export function buildAnswerPreview(
+  response: ExaAnswerResponse,
+  output: TruncatedToolOutput,
+): PreviewDetails {
+  const answer = stringifyValue(response.answer);
+  const citations = response.citations || [];
+  const lines = [
+    ...(answer ? [`1. Answer`, `   ${toExcerpt(answer)}`] : ['1. No answer returned']),
+    ...citations
+      .slice(0, Math.max(0, DEFAULT_UI_PREVIEW_RESULT_COUNT - 1))
+      .flatMap((citation, index) => {
+        const title = asString(citation.title) || asString(citation.url) || 'Source';
+        const entry = [`${index + 2}. ${title}`];
+        if (citation.url) entry.push(`   ${citation.url}`);
+        const excerpt = toExcerpt(citation.text);
+        if (excerpt) entry.push(`   ${excerpt}`);
+        return entry;
+      }),
+  ];
+
+  return {
+    kind: 'answer',
+    summary: `${citations.length} source(s)`,
+    lines,
+    expandedLines: lines,
+    ...previewFromOutput(output),
+  };
+}
+
+function agentRunExcerpt(run: ExaAgentRun): string | undefined {
+  return (
+    toExcerpt(run.output?.text || undefined) ||
+    toExcerpt(stringifyValue(run.output?.structured)) ||
+    toExcerpt(run.request?.query)
+  );
+}
+
+function agentStructuredSummary(run: ExaAgentRun): string | undefined {
+  const structured = run.output?.structured;
+  if (structured === undefined || structured === null) return undefined;
+  if (Array.isArray(structured)) return `Array with ${structured.length} item(s)`;
+  if (typeof structured === 'object') {
+    const entries = Object.entries(structured as Record<string, unknown>);
+    const arrayEntry = entries.find(([, value]) => Array.isArray(value));
+    if (arrayEntry && Array.isArray(arrayEntry[1])) {
+      return `${arrayEntry[0]}: ${arrayEntry[1].length} item(s)`;
+    }
+    return `Object with ${entries.length} field(s)`;
+  }
+  return toExcerpt(String(structured));
+}
+
+function agentCostSummary(run: ExaAgentRun): string | undefined {
+  const total = run.costDollars?.total;
+  return total === undefined ? undefined : `$${total}`;
+}
+
+export function buildAgentRunPreview(
+  run: ExaAgentRun,
+  output: TruncatedToolOutput,
+  options?: { timedOut?: boolean; background?: boolean },
+): PreviewDetails {
+  const lines: string[] = [];
+  const excerpt = agentRunExcerpt(run);
+  const structuredSummary = agentStructuredSummary(run);
+  if (run.output?.text && excerpt) lines.push(`Answer: ${excerpt}`);
+  if (structuredSummary) lines.push(`Structured: ${structuredSummary}`);
+  if (!run.output?.text && !structuredSummary && excerpt) lines.push(`Preview: ${excerpt}`);
+  if (options?.timedOut) lines.push('Timed out waiting; run can be inspected later.');
+  if (options?.background) {
+    lines.push('Background tracking enabled; the extension will notify on completion.');
+  }
+  if (lines.length === 0) lines.push(`Status: ${run.status}`);
+
+  const cost = agentCostSummary(run);
+  const summary = [run.status, cost].filter(Boolean).join(' | ');
+  const expandedLines = [
+    `Run ID: ${run.id}`,
+    ...(run.request?.query ? [`Query: ${toExcerpt(run.request.query, 500)}`] : []),
+    ...lines,
+  ];
+
+  return {
+    kind: 'agent',
+    summary,
+    lines,
+    expandedLines,
+    ...previewFromOutput(output),
+  };
+}
+
+export function buildAgentRunListPreview(
+  response: ExaAgentRunListResponse,
+  output: TruncatedToolOutput,
+): PreviewDetails {
+  const runs = response.data || [];
+  const lines = runs.slice(0, DEFAULT_UI_PREVIEW_RESULT_COUNT).flatMap((run, index) => {
+    const entry = [`${index + 1}. ${run.id} | ${run.status}`];
+    if (run.request?.query) entry.push(`   ${toExcerpt(run.request.query)}`);
+    return entry;
+  });
+  if (response.hasMore)
+    lines.push(`More available: ${response.nextCursor || 'next cursor omitted'}`);
+
+  return {
+    kind: 'agent',
+    summary: `${runs.length} run(s)`,
+    lines,
+    expandedLines: lines,
+    ...previewFromOutput(output),
+  };
+}
+
+export function buildAgentEventListPreview(
+  response: ExaAgentEventListResponse,
+  output: TruncatedToolOutput,
+): PreviewDetails {
+  const events = response.data || [];
+  const lines = events.slice(0, DEFAULT_UI_PREVIEW_RESULT_COUNT).map((event, index) => {
+    const runId = asString(event.data?.id) || asString(event.data?.runId);
+    return `${index + 1}. ${event.event}${runId ? ` | ${runId}` : ''}`;
+  });
+  if (response.hasMore)
+    lines.push(`More available: ${response.nextCursor || 'next cursor omitted'}`);
+
+  return {
+    kind: 'agent',
+    summary: `${events.length} event(s)`,
+    lines,
+    expandedLines: lines,
+    ...previewFromOutput(output),
+  };
+}
+
+export function buildDeletedAgentRunPreview(
+  response: ExaDeletedAgentRun,
+  output: TruncatedToolOutput,
+): PreviewDetails {
+  const lines = [`Run: ${response.id}`, `Deleted: ${response.deleted ? 'yes' : 'no'}`];
+
+  return {
+    kind: 'agent',
+    summary: response.deleted ? 'deleted' : 'not deleted',
+    lines,
+    expandedLines: lines,
+    ...previewFromOutput(output),
+  };
+}
+
+export function sendProgress<TDetails>(
+  onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
+  text: string,
+) {
+  onUpdate?.({
+    content: [{ type: 'text', text }],
+    details: { status: 'pending' } as TDetails,
+  });
+}
+
+export function renderExaCall(
+  toolName: string,
+  primary: string,
+  theme: Theme,
+  metadata: string[] = [],
+): Text {
+  let text = theme.fg('toolTitle', theme.bold(`${toolName} `));
+  text += theme.fg('accent', primary);
+  if (metadata.length > 0) text += theme.fg('dim', ` | ${metadata.join(' | ')}`);
+  return new Text(text, 0, 0);
+}
+
+function renderPreviewText(
+  preview: PreviewDetails | undefined,
+  expanded: boolean,
+  theme: Theme,
+  options?: { partial?: boolean; partialLabel?: string },
+) {
+  if (!preview) {
+    return theme.fg('dim', 'No preview available');
+  }
+
+  const lines = expanded ? (preview.expandedLines ?? preview.lines) : preview.lines;
+
+  let text = theme.fg('success', preview.summary);
+  if (preview.truncated) text += theme.fg('warning', ' | agent output truncated');
+
+  if (lines.length > 0) {
+    const label =
+      preview.kind === 'agent'
+        ? options?.partial
+          ? (options.partialLabel ?? 'Streaming events:')
+          : expanded
+            ? 'Expanded UI preview; Ctrl+O to hide:'
+            : 'Preview only; Ctrl+O to show full response:'
+        : 'UI preview only; the agent received a fuller payload:';
+    text += `\n${theme.fg('muted', label)}`;
+    for (const line of lines) {
+      text += `\n${theme.fg('dim', line)}`;
+    }
+  }
+
+  if (preview.fullOutputPath) {
+    text += `\n${theme.fg('muted', `Full output saved to ${preview.fullOutputPath}`)}`;
+  }
+
+  return text;
+}
+
+export function renderPreviewResult(
+  preview: PreviewDetails | undefined,
+  expanded: boolean,
+  theme: Theme,
+): Text {
+  return new Text(renderPreviewText(preview, expanded, theme), 0, 0);
+}
+
+function rawResponsePreview(details: unknown): string | undefined {
+  if (!details || typeof details !== 'object' || !('response' in details)) return undefined;
+  try {
+    return JSON.stringify((details as { response: unknown }).response, null, 2);
+  } catch {
+    return undefined;
+  }
+}
+
+export function renderExaResult<TDetails extends { preview?: PreviewDetails } | undefined>(
+  result: AgentToolResult<TDetails>,
+  options: ToolRenderResultOptions,
+  theme: Theme,
+  pendingText: string,
+): Text {
+  if (options.isPartial) {
+    if (result.details?.preview) {
+      const details = result.details as { monitor?: unknown; preview?: PreviewDetails };
+      const partialLabel =
+        details.preview?.kind === 'agent' && details.monitor === 'poll'
+          ? 'Polling status:'
+          : undefined;
+      return new Text(
+        renderPreviewText(result.details.preview, true, theme, { partial: true, partialLabel }),
+        0,
+        0,
+      );
+    }
+
+    const textContent = result.content?.find((item) => item.type === 'text')?.text;
+    return new Text(theme.fg('warning', textContent || pendingText), 0, 0);
+  }
+  let text = renderPreviewText(result.details?.preview, options.expanded, theme);
+
+  if (options.expanded && result.details?.preview?.kind === 'agent') {
+    const raw = rawResponsePreview(result.details);
+    if (raw) {
+      text += `\n${theme.fg('muted', 'UI-only raw API response:')}\n${theme.fg('dim', raw)}`;
+    }
+  }
+
+  return new Text(text, 0, 0);
+}
+
+export function metadataFromArgs(args: ToolArgs, keys: string[]): string[] {
+  return keys.flatMap((key) => {
+    const value = args[key];
+    if (value === undefined || value === null || value === false) return [];
+    if (value === true) return [key];
+    return [`${key}=${String(value)}`];
+  });
+}

package/extensions/schemas.ts

@@ -0,0 +1,239 @@
+import { Type } from '@sinclair/typebox';
+
+const JsonObjectSchema = Type.Object({}, { additionalProperties: true });
+
+export const SearchTypeSchema = Type.Union([
+  Type.Literal('auto'),
+  Type.Literal('fast'),
+  Type.Literal('instant'),
+]);
+
+export const CategorySchema = Type.Union([
+  Type.Literal('company'),
+  Type.Literal('research paper'),
+  Type.Literal('news'),
+  Type.Literal('pdf'),
+  Type.Literal('github'),
+  Type.Literal('personal site'),
+  Type.Literal('people'),
+  Type.Literal('financial report'),
+]);
+
+export const WebSearchParamsSchema = Type.Object({
+  query: Type.String({
+    description:
+      'Natural language search query. Prefer a specific description of the desired page over short keywords. Optional category:<type> hints are supported for company, people, news, research paper, and personal site.',
+  }),
+  numResults: Type.Optional(
+    Type.Integer({ minimum: 1, maximum: 100, description: 'Number of search results to return.' }),
+  ),
+});
+
+export const WebSearchAdvancedParamsSchema = Type.Object({
+  query: Type.String({ description: 'Search query.' }),
+  numResults: Type.Optional(
+    Type.Integer({ minimum: 1, maximum: 100, description: 'Number of search results to return.' }),
+  ),
+  type: Type.Optional(SearchTypeSchema),
+  category: Type.Optional(CategorySchema),
+  includeDomains: Type.Optional(Type.Array(Type.String())),
+  excludeDomains: Type.Optional(Type.Array(Type.String())),
+  startPublishedDate: Type.Optional(Type.String({ description: 'YYYY-MM-DD or ISO date.' })),
+  endPublishedDate: Type.Optional(Type.String({ description: 'YYYY-MM-DD or ISO date.' })),
+  startCrawlDate: Type.Optional(Type.String({ description: 'YYYY-MM-DD or ISO date.' })),
+  endCrawlDate: Type.Optional(Type.String({ description: 'YYYY-MM-DD or ISO date.' })),
+  includeText: Type.Optional(Type.Array(Type.String())),
+  excludeText: Type.Optional(Type.Array(Type.String())),
+  userLocation: Type.Optional(Type.String({ description: 'ISO country code, for example US.' })),
+  moderation: Type.Optional(Type.Boolean()),
+  additionalQueries: Type.Optional(Type.Array(Type.String())),
+  textMaxCharacters: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description:
+        'Maximum text characters per result. Omit to request uncapped text from advanced search.',
+    }),
+  ),
+  contextMaxCharacters: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: 'Maximum characters for Exa response-level context string.',
+    }),
+  ),
+  enableSummary: Type.Optional(Type.Boolean()),
+  summaryQuery: Type.Optional(Type.String()),
+  enableHighlights: Type.Optional(
+    Type.Boolean({
+      description: 'Set true to request highlights in addition to text. Defaults to false.',
+    }),
+  ),
+  highlightsMaxCharacters: Type.Optional(
+    Type.Integer({ minimum: 1, description: 'Maximum total highlight characters per URL.' }),
+  ),
+  highlightsQuery: Type.Optional(Type.String()),
+  maxAgeHours: Type.Optional(
+    Type.Integer({
+      minimum: -1,
+      description:
+        'Maximum cache age in hours. Use 0 to force fresh crawl where supported, -1 for cache-only where supported.',
+    }),
+  ),
+  livecrawlTimeout: Type.Optional(Type.Integer({ minimum: 1 })),
+  subpages: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
+  subpageTarget: Type.Optional(Type.Array(Type.String())),
+});
+
+export const WebFetchParamsSchema = Type.Object({
+  urls: Type.Array(Type.String({ minLength: 1 }), {
+    description: 'URLs to read. Batch multiple URLs in one call.',
+  }),
+  maxCharacters: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: 'Maximum characters to extract per page. Defaults to 3000.',
+    }),
+  ),
+});
+
+export const WebAnswerParamsSchema = Type.Object({
+  query: Type.String({ minLength: 1, description: 'Natural-language question to answer.' }),
+  text: Type.Optional(
+    Type.Boolean({
+      description: 'Whether to include full text for citations. Defaults to false.',
+    }),
+  ),
+  outputSchema: Type.Optional(
+    Type.Object({}, { additionalProperties: true, description: 'JSON Schema Draft 7 object.' }),
+  ),
+});
+
+export const AgentEffortSchema = Type.Union([
+  Type.Literal('minimal'),
+  Type.Literal('low'),
+  Type.Literal('medium'),
+  Type.Literal('high'),
+  Type.Literal('xhigh'),
+  Type.Literal('auto'),
+]);
+
+export const AgentRunIdSchema = Type.String({
+  minLength: 1,
+  maxLength: 200,
+  pattern: '^[A-Za-z0-9_.:-]+$',
+  description: 'Exa Agent run ID, usually prefixed with agent_run_.',
+});
+
+export const WebAgentParamsSchema = Type.Object({
+  query: Type.String({
+    minLength: 1,
+    description: 'Natural-language research, list-building, or enrichment task for Exa Agent.',
+  }),
+  systemPrompt: Type.Optional(
+    Type.String({
+      description:
+        'Additional behavior guidance, source preferences, disambiguation rules, novelty/deduping constraints, or output constraints.',
+    }),
+  ),
+  effort: Type.Optional(
+    Type.Union([AgentEffortSchema], {
+      description:
+        'Cost/quality/runtime preference. Defaults to auto. Use medium for standard single-entity research, auto for variable-scope list building.',
+    }),
+  ),
+  input: Type.Optional(
+    Type.Object(
+      {
+        data: Type.Optional(
+          Type.Array(JsonObjectSchema, {
+            description: 'Records the agent should process or enrich.',
+          }),
+        ),
+        exclusion: Type.Optional(
+          Type.Array(JsonObjectSchema, {
+            description: 'Records or entities the agent should avoid returning.',
+          }),
+        ),
+      },
+      {
+        additionalProperties: false,
+        description: 'Structured input rows or exclusions for the run.',
+      },
+    ),
+  ),
+  outputSchema: Type.Optional(
+    Type.Object(
+      {},
+      {
+        additionalProperties: true,
+        description:
+          'JSON Schema for validated structured output in output.structured. Supports draft-07, 2019-09, and 2020-12 via $schema. Bound arrays with maxItems when possible.',
+      },
+    ),
+  ),
+  previousRunId: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description:
+        'Completed same-team Agent run ID to continue from. Exa documents continuations as sharing the supplied previousRunId.',
+    }),
+  ),
+  metadata: Type.Optional(
+    Type.Record(Type.String(), Type.String(), {
+      description: 'Caller-provided key-value metadata for tracking.',
+    }),
+  ),
+  mode: Type.Optional(
+    Type.Union([Type.Literal('wait'), Type.Literal('background')], {
+      description:
+        'wait streams or polls until completion; background returns the run ID immediately and watches it in the session. Do not manually poll background runs unless the user asks.',
+    }),
+  ),
+  monitor: Type.Optional(
+    Type.Union([Type.Literal('stream'), Type.Literal('poll')], {
+      description:
+        'Only applies when mode=wait. stream uses server-sent events; poll uses GET /agent/runs/{id}. Ignored for mode=background.',
+    }),
+  ),
+  pollIntervalMs: Type.Optional(
+    Type.Integer({
+      minimum: 1000,
+      maximum: 60000,
+      description: 'Polling interval for poll mode or background tracking.',
+    }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1000,
+      maximum: 3600000,
+      description:
+        'Foreground wait timeout. If reached, the run keeps going and can be inspected later.',
+    }),
+  ),
+});
+
+export const WebAgentRunParamsSchema = Type.Object({
+  runId: AgentRunIdSchema,
+});
+
+export const WebAgentListParamsSchema = Type.Object({
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+  cursor: Type.Optional(Type.String({ minLength: 1 })),
+});
+
+export const WebAgentEventsParamsSchema = Type.Object({
+  runId: AgentRunIdSchema,
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+  cursor: Type.Optional(Type.String({ minLength: 1 })),
+  replay: Type.Optional(
+    Type.Boolean({
+      description:
+        'Replay stored events as server-sent events instead of listing JSON events. Use only for progress/history inspection.',
+    }),
+  ),
+  lastEventId: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description: 'For replay=true, return only events after this Last-Event-ID value.',
+    }),
+  ),
+});