Interface: TokenHandlers

Defined in: core/dist/types/types.d.ts:636

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

onDecisionAnswered?

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

Defined in: core/dist/types/types.d.ts:681

Parameters

botName

string

event

answers

object[]

decision

string

model

string

timestamp

number

type

"decision_answered"

Returns

void

---

onError?

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

Defined in: core/dist/types/types.d.ts:685

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: core/dist/types/types.d.ts:674

Called when reasoning content is generated

Parameters

botName

string

event

content

string

type

"reasoning"

Returns

void

---

onSkillActivated?

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

Defined in: core/dist/types/types.d.ts:678

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"

skill

string

timestamp

number

type

"skill_activated"

Returns

void

---

onStructuredOutputDelta?

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

Defined in: core/dist/types/types.d.ts:642

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: core/dist/types/types.d.ts:638

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: core/dist/types/types.d.ts:650

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: core/dist/types/types.d.ts:654

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: core/dist/types/types.d.ts:646

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: core/dist/types/types.d.ts:670

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: core/dist/types/types.d.ts:666

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: core/dist/types/types.d.ts:658

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: core/dist/types/types.d.ts:662

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

Parameters

botName

string

event

ToolExecutionStreamEvent

Returns

void