Stream events

​

Event schema (version 1)

​

Ordering guarantees

• run.start is first and run.done is last, each exactly once.
• Each step.start is followed by exactly one step.done with the same step, before the next step.start. Everything a step does happens between the two.
• Inside a step: compaction.start / compaction.done (if the request was compacted, before the model call), provider.retry / provider.fallback events (if the model call fails), then text.delta events, then text.done, then the tool events.
• Tool calls of one step run in parallel (see toolConcurrency): tool.start events come in the model’s call order and tool.done / tool.error events in completion order. Match them by toolCallId.
• input.queued comes when run.enqueue() is called (after run.start, even for input queued before the run got going), so it can fall inside a step. Its input.applied comes between the step.done of the step that was running and the next step.start, which carries the step it names.
• input.steered comes when run.steer() is called. With mode: 'immediate' the running step ends next with step.done ('steered', no text events from its aborted call), then input.applied and the next step.start.
• When a call needs approval, the calls before it run and report, then approval.requested, step.done ('awaiting-approval') and run.done ('awaiting-approval') follow. Calls after it never start.
• When a guardrail blocks, guardrail.tripped comes just before the end: for an input guardrail right after run.start (no step starts); for an output or tool guardrail inside the step, followed by step.done and run.done ('guardrail'). A blocked output has no text.done; calls after a blocked tool call never start.

run.start → step.start → text.delta × n → text.done → step.done → run.done

run.start
step.start(1) → tool.start → tool.done → step.done(1, 'tool_calls')
step.start(2) → text.delta × n → text.done → step.done(2, 'stop')
run.done('stop')

​

TypeScript

import { isAgentEvent, isToolEvent, type AgentEvent } from '@lousho/build-ai-agent';

function render(event: AgentEvent): string {
  switch (event.type) {
    case 'text.delta':
      return event.text;
    case 'tool.start':
      return `\n[${event.toolName}] ${JSON.stringify(event.args)}\n`;
    case 'tool.error':
      return `\n[${event.toolName} failed: ${event.error.message}]\n`;
    case 'run.done':
      return `\n(${event.finishReason})\n`;
    default:
      return '';
  }
}

// isToolEvent / isTextEvent / isStepEvent narrow to an event family:
const toolNames = (events: AgentEvent[]) => events.filter(isToolEvent).map((e) => e.toolName);

// isAgentEvent validates an event received over the wire:
const received: unknown = JSON.parse('{"type":"run.start","runId":"r","seq":0,"timestamp":"","v":1,"agentName":"a"}');
if (isAgentEvent(received)) console.log(render(received), toolNames([received]));

​

Versioning