Skip to main content

Event Types

Types for streaming events emitted during execution.

StreamEvent​

Union type of all possible events:

type StreamEvent =
  | SystemInitEvent
  | MessageEvent
  | ToolCallEvent
  | ToolResultEvent
  | TurnCompletedEvent
  | TurnFailedEvent;

SystemInitEvent​

Emitted at the start of execution:

interface SystemInitEvent {
  type: 'system';
  cwd: string;
  session_id: string;
  tools: string[];
  model: string;
}

MessageEvent​

User or assistant messages:

interface MessageEvent {
  type: 'message';
  role: 'user' | 'assistant';
  id: string;
  text: string;
  timestamp: number;
}

ToolCallEvent​

Tool invocations:

interface ToolCallEvent {
  type: 'tool_call';
  id: string;
  messageId: string;
  toolId: string;
  toolName: string;
  parameters: Record<string, unknown>;
  timestamp: number;
}

ToolResultEvent​

Tool execution results:

interface ToolResultEvent {
  type: 'tool_result';
  id: string;
  messageId: string;
  toolId: string;
  toolName: string;
  isError: boolean;
  value: string;
  timestamp: number;
}

TurnCompletedEvent​

Successful completion:

interface TurnCompletedEvent {
  type: 'completion';
  finalText: string;
  durationMs: number;
  numTurns: number;
}

TurnFailedEvent​

Execution failure:

interface TurnFailedEvent {
  type: 'turn.failed';
  error: {
    message: string;
    code?: string;
  };
}

Type Guards​

Import type guards for type-safe event handling:

import {
  isSystemInitEvent,
  isMessageEvent,
  isToolCallEvent,
  isToolResultEvent,
  isTurnCompletedEvent,
  isTurnFailedEvent
} from '@activade/droid-sdk';

for await (const event of events) {
  if (isToolCallEvent(event)) {
    // TypeScript knows: event is ToolCallEvent
    console.log(event.toolName, event.parameters);
  }

  if (isMessageEvent(event)) {
    // TypeScript knows: event is MessageEvent
    console.log(`[${event.role}] ${event.text}`);
  }
}

Type Guard Functions​

function isSystemInitEvent(e: StreamEvent): e is SystemInitEvent;
function isMessageEvent(e: StreamEvent): e is MessageEvent;
function isToolCallEvent(e: StreamEvent): e is ToolCallEvent;
function isToolResultEvent(e: StreamEvent): e is ToolResultEvent;
function isTurnCompletedEvent(e: StreamEvent): e is TurnCompletedEvent;
function isTurnFailedEvent(e: StreamEvent): e is TurnFailedEvent;

Complete Example​

import {
  isMessageEvent,
  isToolCallEvent,
  isToolResultEvent,
  isTurnFailedEvent
} from '@activade/droid-sdk';

const { events, result } = await thread.runStreamed('Build feature');

for await (const event of events) {
  if (isMessageEvent(event) && event.role === 'assistant') {
    console.log('AI:', event.text);
  }

  if (isToolCallEvent(event)) {
    console.log(`Running: ${event.toolName}`);
  }

  if (isToolResultEvent(event)) {
    console.log(`  ${event.isError ? '✗' : '✓'} ${event.toolName}`);
  }

  if (isTurnFailedEvent(event)) {
    console.error('Failed:', event.error.message);
  }
}