Interface: TokenHandlers

Defined in: packages/core/src/types.ts:380

Object-based token handlers for better ergonomics and type safety Each handler is optional and receives strongly-typed event data

Handlers are organized into two categories:

• STREAMING EVENTS: Real-time events during execution (use these for live updates)
• FINAL EVENTS: Completion events when operations finish (also available via process() return value)

Example

const handlers: TokenHandlers = {
  // Streaming events (real-time)
  onTextDelta(botName, event) {
    process.stdout.write(event.content);  // Stream as it generates
  },
  onToolExecutionStart(botName, event) {
    console.log(`${botName} starting ${event.toolName}`);
  },
  // Final events (when complete)
  onToolExecutionOutput(botName, event) {
    console.log(`Result: ${event.result}`);
  }
  // Other handlers are optional - omit what you don't need
};

await bot.process(input, { onToken: handlers });

Properties

onError?

optional onError?: (botName, event) => void

Defined in: packages/core/src/types.ts:428

Called when an error occurs

Parameters

botName

string

event

error

Error | { message: string; name?: string; stack?: string; } = ...

type

"error" = ...

Returns

void

---

onReasoning?

optional onReasoning?: (botName, event) => void

Defined in: packages/core/src/types.ts:422

Called when reasoning content is generated

Parameters

botName

string

event

content

string = ...

type

"reasoning" = ...

Returns

void

---

onSkillActivated?

optional onSkillActivated?: (botName, event) => void

Defined in: packages/core/src/types.ts:425

Called once per turn for each Skill whose instructions shaped the prompt (keyword match or prior load_skill)

Parameters

botName

string

event

reason

"keyword" | "load_skill" = ...

Why it was active this turn: a keyword match, or a prior load_skill call.

skill

string = ...

The activated skill's name.

timestamp

number = ...

type

"skill_activated" = ...

Returns

void

---

onStructuredOutputDelta?

optional onStructuredOutputDelta?: (botName, event) => void

Defined in: packages/core/src/types.ts:391

Called for each structured output token during streaming

Parameters

botName

string

event

content

string = ...

type

"structured_output_delta" = ...

Returns

void

---

onTextDelta?

optional onTextDelta?: (botName, event) => void

Defined in: packages/core/src/types.ts:388

Called for each text token during streaming

Parameters

botName

string

event

content

string = ...

type

"text_delta" = ...

Returns

void

---

onToolCallArgumentsDelta?

optional onToolCallArgumentsDelta?: (botName, event) => void

Defined in: packages/core/src/types.ts:398

Called for each chunk of tool arguments as LLM streams them

Parameters

botName

string

event

argumentsDelta

string = ...

id

string = ...

type

"tool_call_arguments_delta" = ...

Returns

void

---

onToolCallStreamComplete?

optional onToolCallStreamComplete?: (botName, event) => void

Defined in: packages/core/src/types.ts:401

Called when LLM finishes streaming a tool call (before execution)

Parameters

botName

string

event

arguments

unknown = ...

id

string = ...

toolName

string = ...

type

"tool_call_stream_complete" = ...

Returns

void

---

onToolCallStreamStart?

optional onToolCallStreamStart?: (botName, event) => void

Defined in: packages/core/src/types.ts:395

Called when LLM starts streaming a tool call

Parameters

botName

string

event

id

string = ...

toolName

string = ...

type

"tool_call_stream_start" = ...

Returns

void

---

onToolCallValidationError?

optional onToolCallValidationError?: (botName, event) => void

Defined in: packages/core/src/types.ts:419

Called when tool arguments fail validation

Parameters

botName

string

event

receivedArguments

unknown = ...

toolName

string = ...

type

"tool_validation_error" = ...

validationErrors

unknown = ...

Returns

void

---

onToolExecutionOutput?

optional onToolExecutionOutput?: (botName, event) => void

Defined in: packages/core/src/types.ts:416

Called when tool execution completes with output

Parameters

botName

string

event

arguments?

unknown = ...

error?

string = ...

errorDetail?

{ code?: string; message: string; type?: string; } = ...

errorDetail.code?

string = ...

errorDetail.message

string = ...

errorDetail.type?

string = ...

id

string = ...

result

unknown = ...

toolName

string = ...

type

"tool_execution_output" = ...

Returns

void

---

onToolExecutionStart?

optional onToolExecutionStart?: (botName, event) => void

Defined in: packages/core/src/types.ts:405

Called when tool execution starts

Parameters

botName

string

event

arguments

unknown = ...

id

string = ...

toolName

string = ...

type

"tool_execution_start" = ...

Returns

void

---

onToolExecutionStream?

optional onToolExecutionStream?: (botName, event) => void

Defined in: packages/core/src/types.ts:408

Called when tool execution emits nested streaming events (e.g., from child bots)

Parameters

botName

string

event

ToolExecutionStreamEvent

Returns

void