Events

Overview

Events are the units of information that flow through harnesses. Every harness invocation yields a sequence of events — from streaming text chunks to tool calls to usage metrics. Events form an immutable log that can be reduced into a conversation graph. All events carry two fields for graph construction:

runId

string

required

Identifies the harness run that produced this event. Each agent invocation gets a unique runId (a UUID v7).

parentId

string

Links this event to its parent. For subagents, parentId is the tool call ID that spawned them. For top-level agents, parentId is undefined.

Event types

Events are defined as a discriminated union in packages/ai/types.ts:77. The type field determines which other fields are present.

Content events

These events carry the actual LLM output:

text
reasoning

A chunk of streamed text content from the model.

{
  type: "text",
  runId: string,
  parentId?: string,
  id: string,        // Stable across chunks of the same text stream
  content: string    // The text fragment
}

Example:

let fullText = "";
for await (const event of harness.invoke(params)) {
  if (event.type === "text") {
    fullText += event.content;
    process.stdout.write(event.content);
  }
}

Emitted by: Provider harnesses (e.g., harness/providers/zen.ts:269)
Passthrough: Agent harness re-yields text events with provider’s runId

A chunk of streamed reasoning or chain-of-thought content (provider-dependent).

{
  type: "reasoning",
  runId: string,
  parentId?: string,
  id: string,        // Stable across chunks of the same reasoning block
  content: string    // The reasoning fragment
}

Example:

for await (const event of harness.invoke(params)) {
  if (event.type === "reasoning") {
    console.log("[thinking]", event.content);
  }
}

Supported by: Zen (via reasoning_content), models that expose chain-of-thought
Emitted by: Provider harnesses that support reasoning (e.g., harness/providers/zen.ts:259)

Tool events

These events track tool call requests and results:

tool_call
tool_result
tool_progress

The model is requesting a tool invocation.

{
  type: "tool_call",
  runId: string,
  parentId?: string,
  id: string,        // Tool call identifier (namespaced by agent)
  name: string,      // Tool name
  input: unknown     // Parsed arguments (or { __toolParseError, parseError, rawArguments } on malformed JSON)
}

Example:

for await (const event of agent.invoke(params)) {
  if (event.type === "tool_call") {
    console.log(`Calling ${event.name} with`, event.input);
  }
}

Emitted by:

Provider harnesses yield raw tool calls after the stream ends
Agent harness re-yields approved calls with namespaced IDs (format: {agentRunId}/{rawId})

If the model emits malformed JSON for tool arguments, input will be an object with __toolParseError: true, parseError, and rawArguments fields. The agent harness will yield a tool_result with the error and continue.

Result of executing a tool.

{
  type: "tool_result",
  runId: string,
  parentId?: string,
  id: string,        // Matches the tool_call id
  name: string,      // Tool name
  output: unknown    // { context, result } on success
                      // { status: "denied", reason } on denial
                      // { error } on failure
}

Example:

for await (const event of agent.invoke(params)) {
  if (event.type === "tool_result") {
    if (event.output.error) {
      console.error(`Tool ${event.name} failed:`, event.output.error);
    } else if (event.output.status === "denied") {
      console.log(`Tool ${event.name} was denied:`, event.output.reason);
    } else {
      console.log(`Tool ${event.name} result:`, event.output.context);
    }
  }
}

Emitted by: Agent harness only (harness/agent.ts:193, harness/agent.ts:280)

Live progress updates during long-running tool execution.

{
  type: "tool_progress",
  runId: string,
  parentId?: string,
  id: string,
  toolCallId: string,  // The tool call this progress belongs to
  name: string,        // Tool name
  content: unknown     // Progress data (format depends on tool)
}

Example:

for await (const event of agent.invoke(params)) {
  if (event.type === "tool_progress") {
    console.log(`[${event.name}]`, event.content);
  }
}

Emitted by: Tools that report progress (e.g., bash tool streaming stdout)

Lifecycle events

harness_start
harness_end

Marks the beginning of a harness run.

{
  type: "harness_start",
  runId: string,
  parentId?: string,
  depth?: number,         // Recursion depth for nested RLM sessions
  maxIterations?: number  // Configured iteration limit
}

Emitted by: Agent harness (harness/agent.ts:51), RLM harness

Marks the end of a harness run. Emitted on normal completion, error, or max iterations.

{
  type: "harness_end",
  runId: string,
  parentId?: string,
  reason?: "final" | "max_iterations",  // Optional, RLM only
  iterations?: number,                   // Number of REPL iterations completed
  totalUsage?: {                         // Aggregate token usage
    inputTokens: number,
    outputTokens: number
  }
}

Emitted by: Agent harness (harness/agent.ts:99, harness/agent.ts:122, harness/agent.ts:325), RLM harness

System events

usage
error
relay

Token usage for one LLM call.

{
  type: "usage",
  runId: string,
  parentId?: string,
  inputTokens: number,        // Prompt tokens consumed
  outputTokens: number,       // Completion tokens generated
  cacheReadTokens?: number,   // Tokens read from cache
  cacheCreationTokens?: number // Tokens written to cache
}

Example:

let totalInput = 0, totalOutput = 0;
for await (const event of agent.invoke(params)) {
  if (event.type === "usage") {
    totalInput += event.inputTokens;
    totalOutput += event.outputTokens;
  }
}
console.log(`Total: ${totalInput} in / ${totalOutput} out`);

Emitted by: Provider harnesses (e.g., harness/providers/zen.ts:325)
Passthrough: Agent harness re-yields usage events

An error occurred during invocation.

{
  type: "error",
  runId: string,
  parentId?: string,
  error: Error  // The error instance
}

Example:

for await (const event of agent.invoke(params)) {
  if (event.type === "error") {
    console.error(`Error in ${event.runId}:`, event.error.message);
  }
}

Emitted by: Both provider and agent harnesses

Provider: API/stream errors (e.g., harness/providers/zen.ts:203)
Agent: Tool execution errors, missing executors (e.g., harness/agent.ts:245)

A permission request that pauses the harness until resolved.

{
  type: "relay",
  kind: "permission",         // Extensible to other relay kinds
  runId: string,
  id: string,
  parentId?: string,
  toolCallId: string,         // The namespaced tool call ID
  tool: string,               // Tool name
  params: Record<string, unknown>,  // Tool arguments
  respond: (response: PermissionResponse) => void  // Callback to approve/deny
}

Example:

for await (const event of agent.invoke(params)) {
  if (event.type === "relay" && event.kind === "permission") {
    const approved = await askUser(`Allow ${event.tool}?`);
    event.respond({ approved, reason: approved ? undefined : "User denied" });
  }
}

Emitted by: Agent harness only (harness/agent.ts:169)
Behavior: The generator pauses until respond() is called via a deferred promise

The respond callback is stripped from relay events when they pass through the orchestrator. Use resolveRelay() on the orchestrator instead.

RLM events

These events are specific to the Recursive Language Model harness:

repl_input
repl_progress
repl_output

Code extracted from the model’s response, about to be executed.

{
  type: "repl_input",
  runId: string,
  id: string,
  parentId?: string,
  code: string,       // The JavaScript code to execute
  iteration?: number  // Zero-based loop index
}

Live output streamed during REPL execution.

{
  type: "repl_progress",
  runId: string,
  id: string,
  parentId?: string,
  chunk: string,              // The output fragment
  stream: "stdout" | "stderr" // Which stream this came from
}

Complete result of a REPL execution.

{
  type: "repl_output",
  runId: string,
  id: string,
  parentId?: string,
  stdout: string,         // Full accumulated output
  error?: string,         // Error message if execution failed
  done: boolean,          // Whether FINAL() was called
  iteration?: number,     // Zero-based loop index
  durationMs?: number,    // Wall-clock execution time
  truncated?: boolean     // True if stdout was truncated
}

Event sequences

Understanding typical event sequences helps you handle them correctly:

Simple LLM call (provider only)

1. text (streamed chunks)
2. text
3. text
...
N. usage

LLM call with tool request (provider only)

1. text (streamed response)
2. text
...
N-1. tool_call (after stream ends)
N. usage

Agent with single tool call

harness_start
text (from provider)
tool_call (from provider)
usage (from provider)
relay (permission request, agent pauses)
   ... (waiting for respond()) ...
tool_call (re-emitted after approval)
tool_result (after execution)
text (next LLM call)
usage
harness_end

Agent with concurrent tool calls

harness_start
text
tool_call (id: tc-1)
tool_call (id: tc-2)
usage
relay (for tc-1)
relay (for tc-2)
   ... (permission phase, sequential) ...
tool_call (tc-1 re-emitted)
tool_call (tc-2 re-emitted)
   ... (execution phase, concurrent) ...
tool_result (tc-1)  // May arrive in any order
tool_result (tc-2)
text (next iteration)
usage
harness_end

Event accumulation patterns

Streaming text

Text and reasoning events arrive incrementally. Accumulate by id:

const textById = new Map<string, string>();

for await (const event of harness.invoke(params)) {
  if (event.type === "text") {
    const current = textById.get(event.id) ?? "";
    textById.set(event.id, current + event.content);
  }
}

Tool call lifecycle

Match tool calls with their results using the id field:

const toolCalls = new Map();
const toolResults = new Map();

for await (const event of agent.invoke(params)) {
  if (event.type === "tool_call") {
    toolCalls.set(event.id, event);
  }
  if (event.type === "tool_result") {
    toolResults.set(event.id, event);
    const call = toolCalls.get(event.id);
    console.log(`${call.name}(${JSON.stringify(call.input)}) => ${JSON.stringify(event.output)}`);
  }
}

Usage tracking

Sum usage events across iterations:

let totalTokens = { input: 0, output: 0, cached: 0 };

for await (const event of agent.invoke(params)) {
  if (event.type === "usage") {
    totalTokens.input += event.inputTokens;
    totalTokens.output += event.outputTokens;
    totalTokens.cached += event.cacheReadTokens ?? 0;
  }
}

Building the conversation graph

Events are reduced into an immutable conversation graph using runId and parentId for edges. The graph reducer in packages/ai/client/graph.ts accumulates events:

import { createGraph, reduceEvent } from "./packages/ai/client/graph";

let graph = createGraph();

for await (const event of orchestrator.events()) {
  graph = reduceEvent(graph, event);
  // Now graph.nodes contains all events as nodes
  // and graph.edges links them by runId → parentId
}

See Conversation Graph for details on graph structure and querying, and Client Library for the full graph API.

Type safety

Events are a discriminated union, so TypeScript narrows the type when you check the type field:

for await (const event of agent.invoke(params)) {
  if (event.type === "text") {
    // TypeScript knows event.content is a string
    process.stdout.write(event.content);
  }
  if (event.type === "tool_call") {
    // TypeScript knows event.name and event.input exist
    console.log(`Calling ${event.name}`);
  }
}

Next steps

Conversation Graph

Learn how events form an immutable graph structure

Client Rendering

Use graph projections to render conversations

Types Reference

Full TypeScript type definitions for all events

Harnesses

Return to harness fundamentals

Get Started

Core Concepts

Guides

Building Extensions

Deployment

Overview

Event types

Content events

Tool events

Lifecycle events

System events

RLM events

Event sequences

Simple LLM call (provider only)

LLM call with tool request (provider only)

Agent with single tool call

Agent with concurrent tool calls

Event accumulation patterns

Building the conversation graph

Type safety

Next steps

Conversation Graph

Client Rendering

Types Reference

Harnesses

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Building Extensions

Deployment

​Overview

​Event types

​Content events

​Tool events

​Lifecycle events

​System events

​RLM events

​Event sequences

​Simple LLM call (provider only)

​LLM call with tool request (provider only)

​Agent with single tool call

​Agent with concurrent tool calls

​Event accumulation patterns

​Building the conversation graph

​Type safety

​Next steps

Conversation Graph

Client Rendering

Types Reference

Harnesses

Build docs developers (and LLMs) love

Overview

Event types

Content events

Tool events

Lifecycle events

System events

RLM events

Event sequences

Simple LLM call (provider only)

LLM call with tool request (provider only)

Agent with single tool call

Agent with concurrent tool calls

Event accumulation patterns

Building the conversation graph

Type safety

Next steps