Skip to main content

Interface: TokenHandlers

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

One optional handler per event type, each receiving its event narrowed.

Example​

const handlers: TokenHandlers = {
onTextDelta(botName, event) {
process.stdout.write(event.content);
},
onToolExecutionOutput(botName, event) {
console.log(`Result: ${event.result}`);
}
};

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

Properties​

onContextCompacted?​

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

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

Called when a durable loop folds its older steps to stay inside its token budget.

Parameters​

botName​

string

event​
completedSteps​

number = ...

Steps completed in the run so far.

foldedSteps​

number = ...

Steps the compaction now covers (folded into a summary, or with their tool results cleared).

strategy​

"summary" | "cleared" = ...

timestamp​

number = ...

type​

"context_compacted" = ...

Returns​

void


onDecisionAnswered?​

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

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

Parameters​

botName​

string

event​
answers​

object[] = ...

One entry per question asked, in the order it was declared.

decision​

string = ...

The decision processor that asked.

model​

string = ...

timestamp​

number = ...

type​

"decision_answered" = ...

Returns​

void


onError?​

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

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

Parameters​

botName​

string

event​
error​

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

type​

"error" = ...

Returns​

void


onModelFallback?​

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

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

Called when a failed model call moves the loop to the next model in the chain.

Parameters​

botName​

string

event​
completedSteps​

number = ...

Steps completed (and kept) before the failure. Text streamed for the failed step is superseded.

from​

string = ...

Model that failed.

reason​

string = ...

The failure, as a message.

timestamp​

number = ...

to​

string = ...

Model the loop continues on.

type​

"model_fallback" = ...

Returns​

void


onReasoning?​

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

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

Parameters​

botName​

string

event​
block?​

{ producer?: { model: string; provider: string; }; providerMetadata?: Record<string, unknown>; text: string; } = ...

Set once, when a reasoning block ends: the whole block as the provider sent it — its text (empty when the provider omits it), its provider metadata (an Anthropic signature or redacted data), and the provider and model that produced it. History keeps it so a rebuilt turn resends the block, to that model only.

block.producer?​

{ model: string; provider: string; } = ...

block.producer.model​

string = ...

block.producer.provider​

string = ...

block.providerMetadata?​

Record<string, unknown> = ...

block.text​

string = ...

content​

string = ...

type​

"reasoning" = ...

Returns​

void


onSkillActivated?​

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

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

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" | "requested" = ...

Why it was active this turn: a keyword match, a load_skill call, or the host requested it (ProcessOptions.activeSkills).

skill​

string = ...

timestamp​

number = ...

type​

"skill_activated" = ...

Returns​

void


onSteerMerged?​

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

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

Called when steering is merged into the conversation before a step.

Parameters​

botName​

string

event​
items​

object[] = ...

step​

number = ...

The step the items were merged before (0-based, within the current model attempt).

timestamp​

number = ...

type​

"steer_merged" = ...

Returns​

void


onStepFinished?​

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

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

Called once per completed model step with its usage (and provider-reported cost, when there is one).

Parameters​

botName​

string

event​
cost?​

number = ...

Generation USD the provider reported (OpenRouter, xAI). Absent when it reports tokens only.

finishReason?​

string = ...

modelId?​

string = ...

The model id the provider reported for this step (prepareStep may have swapped it).

step​

number = ...

0-based index of the step within this call.

timestamp​

number = ...

type​

"step_finished" = ...

usage​

{ cacheReadTokens?: number; cacheWriteTokens?: number; inputTokens?: number; outputTokens?: number; totalTokens?: number; } = ...

usage.cacheReadTokens?​

number = ...

usage.cacheWriteTokens?​

number = ...

usage.inputTokens?​

number = ...

usage.outputTokens?​

number = ...

usage.totalTokens?​

number = ...

Returns​

void


onStructuredOutputDelta?​

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

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

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:635

Parameters​

botName​

string

event​
content​

string = ...

type​

"text_delta" = ...

Returns​

void


onToolCallArgumentsDelta?​

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

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

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:645

The model finished writing a tool call; the tool has not run yet.

Parameters​

botName​

string

event​
arguments​

unknown = ...

display?​

{ headline?: string; kind?: string; title?: string; } = ...

display.headline?​

string = ...

display.kind?​

string = ...

display.title?​

string = ...

id​

string = ...

invalid?​

boolean = ...

AI SDK refused the call before any tool ran (input that fails the tool's schema, a tool outside the active set). A tool_call_stream_error with the reason follows; the model sees it and may correct the call.

producer?​

{ model: string; provider: string; } = ...

producer.model​

string = ...

producer.provider​

string = ...

providerMetadata?​

Record<string, unknown> = ...

The provider's metadata on the call as the model produced it (Anthropic: caller), and who produced it.

toolName​

string = ...

type​

"tool_call_stream_complete" = ...

Returns​

void


onToolCallStreamStart?​

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

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

The model started writing a tool call.

Parameters​

botName​

string

event​
display?​

{ headline?: string; kind?: string; title?: string; } = ...

Title and kind only: the input has not streamed yet.

display.headline?​

string = ...

display.kind?​

string = ...

display.title?​

string = ...

id​

string = ...

toolName​

string = ...

type​

"tool_call_stream_start" = ...

Returns​

void


onToolCallValidationError?​

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

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

Tool arguments failed 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:652

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:647

Parameters​

botName​

string

event​
arguments​

unknown = ...

display?​

{ headline?: string; kind?: string; title?: string; } = ...

With the headline for this call's input.

display.headline?​

string = ...

display.kind?​

string = ...

display.title?​

string = ...

id​

string = ...

toolName​

string = ...

type​

"tool_execution_start" = ...

Returns​

void


onToolExecutionStream?​

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

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

A running tool's nested events (e.g., from child bots).

Parameters​

botName​

string

event​

ToolExecutionStreamEvent

Returns​

void