@alasano/pi-exa 0.1.1 → 0.1.2

package/extensions/agent-timeline.ts

@@ -0,0 +1,83 @@
+export const AGENT_TIMELINE_MAX_EVENTS = 6;
+export const AGENT_TIMELINE_UPDATE_THROTTLE_MS = 100;
+
+export interface AgentTimelineSnapshot {
+  events: string[];
+  totalEvents: number;
+  status: string;
+}
+
+interface AgentTimelineOptions {
+  maxEvents?: number;
+  throttleMs?: number;
+}
+
+export class AgentTimeline {
+  private readonly events: string[] = [];
+  private readonly maxEvents: number;
+  private readonly throttleMs: number;
+  private totalEvents = 0;
+  private status = 'running';
+  private updateTimer: ReturnType<typeof setTimeout> | undefined;
+  private updateDirty = false;
+  private lastUpdateAt = 0;
+
+  constructor(
+    private readonly onUpdate: (snapshot: AgentTimelineSnapshot) => void,
+    options: AgentTimelineOptions = {},
+  ) {
+    this.maxEvents = Math.max(1, options.maxEvents ?? AGENT_TIMELINE_MAX_EVENTS);
+    this.throttleMs = Math.max(0, options.throttleMs ?? AGENT_TIMELINE_UPDATE_THROTTLE_MS);
+  }
+
+  append(event: string, status = 'running'): void {
+    this.totalEvents += 1;
+    this.status = status;
+    this.events.push(event);
+    if (this.events.length > this.maxEvents) {
+      this.events.splice(0, this.events.length - this.maxEvents);
+    }
+    this.scheduleUpdate();
+  }
+
+  flush(): void {
+    this.clearUpdateTimer();
+    this.emitUpdate();
+  }
+
+  dispose(): void {
+    this.clearUpdateTimer();
+  }
+
+  private scheduleUpdate(): void {
+    this.updateDirty = true;
+    const delay = this.throttleMs - (Date.now() - this.lastUpdateAt);
+    if (delay <= 0) {
+      this.clearUpdateTimer();
+      this.emitUpdate();
+      return;
+    }
+
+    this.updateTimer ??= setTimeout(() => {
+      this.updateTimer = undefined;
+      this.emitUpdate();
+    }, delay);
+  }
+
+  private emitUpdate(): void {
+    if (!this.updateDirty) return;
+    this.updateDirty = false;
+    this.lastUpdateAt = Date.now();
+    this.onUpdate({
+      events: [...this.events],
+      totalEvents: this.totalEvents,
+      status: this.status,
+    });
+  }
+
+  private clearUpdateTimer(): void {
+    if (!this.updateTimer) return;
+    clearTimeout(this.updateTimer);
+    this.updateTimer = undefined;
+  }
+}

package/extensions/render.ts

@@ -314,7 +314,7 @@ function renderPreviewText(
     const label =
       preview.kind === 'agent'
         ? options?.partial
-          ? (options.partialLabel ?? 'Streaming events:')
+          ? (options.partialLabel ?? 'Latest streaming events:')
           : expanded
             ? 'Expanded UI preview; Ctrl+O to hide:'
             : 'Preview only; Ctrl+O to show full response:'
@@ -363,7 +363,10 @@ export function renderExaResult<TDetails extends { preview?: PreviewDetails } |
           ? 'Polling status:'
           : undefined;
       return new Text(
-        renderPreviewText(result.details.preview, true, theme, { partial: true, partialLabel }),
+        renderPreviewText(result.details.preview, options.expanded, theme, {
+          partial: true,
+          partialLabel,
+        }),
         0,
         0,
       );

package/extensions/tools/web-agent.ts

@@ -10,6 +10,7 @@ import {
   streamAgentRunEvents,
   type ExaAgentCreateRequest,
 } from '../agent';
+import { AgentTimeline, type AgentTimelineSnapshot } from '../agent-timeline';
 import type { AgentRunTracker } from '../agent-tracker';
 import { countAgentSources, formatAgentRunResponse } from '../format';
 import { truncateToolOutput } from '../output';
@@ -38,6 +39,7 @@ type WebAgentDetails =
       monitor?: 'stream' | 'poll';
       timedOut?: boolean;
       events?: string[];
+      eventCount?: number;
     })
   | undefined;
 
@@ -79,23 +81,28 @@ function agentEventProgress(event: ExaAgentEvent): string {
 
 function sendAgentTimelineUpdate(
   onUpdate: AgentToolUpdateCallback<WebAgentDetails> | undefined,
-  events: string[],
-  summary = 'running',
+  snapshot: AgentTimelineSnapshot,
 ) {
+  const eventLabel = snapshot.totalEvents === 1 ? 'event' : 'events';
   const preview: PreviewDetails = {
     kind: 'agent',
-    summary,
-    lines: events.slice(-6),
-    expandedLines: events,
+    summary: `${snapshot.status} | ${snapshot.totalEvents} ${eventLabel}`,
+    lines: snapshot.events,
   };
 
   onUpdate?.({
-    content: [{ type: 'text', text: events[events.length - 1] || 'Running Exa Agent...' }],
+    content: [
+      {
+        type: 'text',
+        text: snapshot.events[snapshot.events.length - 1] || 'Running Exa Agent...',
+      },
+    ],
     details: {
       endpoint: '/agent/runs',
       mode: 'wait',
       monitor: 'stream',
-      events,
+      events: snapshot.events,
+      eventCount: snapshot.totalEvents,
       preview,
     },
   });
@@ -192,7 +199,7 @@ async function waitWithStreaming(
   const timeoutSignal = createTimeoutSignal(signal, timeoutMs);
   let runId: string | undefined;
   let terminalFromStream = false;
-  const events: string[] = [];
+  const timeline = new AgentTimeline((snapshot) => sendAgentTimelineUpdate(onUpdate, snapshot));
 
   try {
     sendProgress(onUpdate, 'Starting Exa Agent run with streaming events...');
@@ -200,11 +207,10 @@ async function waitWithStreaming(
       runId = getRunIdFromAgentEvent(event) ?? runId;
       const status = typeof event.data.status === 'string' ? event.data.status : undefined;
       terminalFromStream = terminalFromStream || isTerminalAgentStatus(status);
-      const line = agentEventProgress(event);
-      events.push(line);
-      sendAgentTimelineUpdate(onUpdate, events, status || 'running');
+      timeline.append(agentEventProgress(event), status || 'running');
     }
   } catch (error) {
+    timeline.flush();
     if (!runId || (!timeoutSignal.isTimedOut() && signal?.aborted)) throw error;
     if (timeoutSignal.isTimedOut()) {
       const run = await getAgentRun(apiKey, runId, signal);
@@ -218,6 +224,8 @@ async function waitWithStreaming(
       signal,
     });
   } finally {
+    timeline.flush();
+    timeline.dispose();
     timeoutSignal.dispose();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alasano/pi-exa",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Exa-powered web search, content retrieval, answers, and agentic search tools for pi",
   "keywords": [
     "pi-package"