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?
optionalonContextCompacted?: (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?
optionalonDecisionAnswered?: (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?
optionalonError?: (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?
optionalonModelFallback?: (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?
optionalonReasoning?: (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?
optionalonSkillActivated?: (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?
optionalonSteerMerged?: (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?
optionalonStepFinished?: (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?
optionalonStructuredOutputDelta?: (botName,event) =>void
Defined in: packages/core/src/types.ts:637
Parameters
botName
string
event
content
string = ...
type
"structured_output_delta" = ...
Returns
void
onTextDelta?
optionalonTextDelta?: (botName,event) =>void
Defined in: packages/core/src/types.ts:635
Parameters
botName
string
event
content
string = ...
type
"text_delta" = ...
Returns
void
onToolCallArgumentsDelta?
optionalonToolCallArgumentsDelta?: (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?
optionalonToolCallStreamComplete?: (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?
optionalonToolCallStreamStart?: (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?
optionalonToolCallValidationError?: (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?
optionalonToolExecutionOutput?: (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?
optionalonToolExecutionStart?: (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?
optionalonToolExecutionStream?: (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