Interface: ProcessOptions
Defined in: core/dist/types/types.d.ts:596
What every call of every Processable carries: cancellation, callbacks, composition hooks.
Extends
LeafCallOptions
Properties
activeSkills?
optionalactiveSkills?: readonlystring[]
Defined in: core/dist/types/baleybot-call-options.d.ts:271
Skills to activate for this call only (by name), as if a keyword had
matched: their instructions join the system prompt and, with
toolSearch, their tools load from the first step. Reason requested on
the skill_activated event. Not persisted — the model's own load_skill
choices are the state (skillState). Unknown names are ignored with
a warning. A host router (e.g. a Jev route) passes its pick here.
Inherited from
LeafCallOptions.activeSkills
activeTools?
optionalactiveTools?: readonlystring[]
Defined in: core/dist/types/baleybot-call-options.d.ts:329
Override AI SDK activeTools for this call only (restrict callable tools). Thin passthrough.
Inherited from
LeafCallOptions.activeTools
additionalTools?
optionaladditionalTools?:Tools
Defined in: core/dist/types/baleybot-call-options.d.ts:262
Extra tools for this call only, added on top of the ones the processable
was built with. Composites forward options to their children, so tools
added here reach every LLM turn the call performs.
This is how a caller lends a processable a capability without rebuilding it: an orchestrator can hand a worker collaboration tools while the agent keeps its own model, system prompt and tools.
A name already configured on the processable wins — an added tool must
not silently replace one the agent was built with. Use activeTools to
restrict the merged set.
Inherited from
LeafCallOptions.additionalTools
approvalResponses?
optionalapprovalResponses?:ApprovalResponse[]
Defined in: core/dist/types/baleybot-call-options.d.ts:165
Resume a paused tool-approval turn (resumable approvals).
When a gated tool (requiresApproval) is reached without an in-process
onApprovalRequired handler, the loop pauses and emits a
tool_approval_request event carrying an approvalId. Collect the user's
decision out-of-band, then call process() again with the same input plus
these responses — each is threaded straight into AI SDK's native
approval-response message so the loop continues where it left off.
The prior turn's messages (the assistant turn containing the approval
request) must be supplied via conversationHistory or keepHistory.
Example
await bot.process('Delete temp.txt', {
conversationHistory: priorMessages,
approvalResponses: [{ approvalId, approved: true }],
});
Inherited from
LeafCallOptions.approvalResponses
cache?
optionalcache?:CacheControlOption
Defined in: core/dist/types/baleybot-call-options.d.ts:109
Prompt-cache plan. Wins over cacheControl and enableCaching.
{ scope: 'prefix', ttl: '1h' }— last always-loaded tool + system{ scope: 'chat' }— last-tool + system + last four messages, capped at 4false— off{ system: true, tools: true, lastMessages: 0, ttl: '1h' }— same as prefix
Optional file/image stamps (file(..., { cacheControl: true })) are
reserved in the four-breakpoint budget. ttl is forwarded to
@ai-sdk/anthropic.
Inherited from
LeafCallOptions.cache
cacheControl?
optionalcacheControl?:CacheControlOption
Defined in: core/dist/types/baleybot-call-options.d.ts:352
Override prompt-cache-control for this call only. Takes precedence over
construction-time model.cacheControl and enableCaching. false
disables. An object is the same plan as cache; if both are set,
cache wins.
Inherited from
LeafCallOptions.cacheControl
checkpointSteps?
optionalcheckpointSteps?:boolean
Defined in: core/dist/types/baleybot-call-options.d.ts:293
Checkpoint every completed step of the tool loop in execution (which
must be durable), and continue after the last checkpointed step when this
call repeats a run that stopped part-way (overrides
BaleybotConfig.checkpointSteps). A turn that already finished returns
its recorded answer.
Inherited from
LeafCallOptions.checkpointSteps
compaction?
optionalcompaction?:StepCompaction
Defined in: core/dist/types/baleybot-call-options.d.ts:308
With checkpointSteps: keep a long run's conversation inside a token
budget by folding its older steps — clearing their tool results, or
summarising them (overrides BaleybotConfig.compaction).
Inherited from
LeafCallOptions.compaction
conversationHistory?
optionalconversationHistory?:object[]
Defined in: core/dist/types/baleybot-call-options.d.ts:187
Conversation history for multi-turn conversations (uses OpenAI ChatMessage format from providers)
content
content:
string|MessageContentBlock[]
role
role:
"system"|"user"|"assistant"|"tool"
tool_call_id?
optionaltool_call_id?:string
tool_calls?
optionaltool_calls?:object[]
Inherited from
LeafCallOptions.conversationHistory
defaults?
optionaldefaults?:DefaultsPatch
Defined in: core/dist/types/baleybot-call-options.d.ts:85
Defaults for this invocation, deep-merged over the process-wide ones.
Overriding one field of a group keeps the rest of it, so steering a single run does not drop configuration set by setDefaults.
Inherited from
LeafCallOptions.defaults
enableCaching?
optionalenableCaching?:boolean
Defined in: core/dist/types/baleybot-call-options.d.ts:96
Chat-style prompt cache shorthand. Same as cacheControl: true /
cache: { scope: 'chat' }: stamp the last always-loaded tool, the
system block, and the last four conversation messages, then drop
message stamps first so the request never exceeds Anthropic's
four-breakpoint cap (last-tool + system survive). Unique trailing
turns still get written at 1.25× — prefer cache
{ scope: 'prefix' } when the tools+system prefix is stable and
the turns are not.
Inherited from
LeafCallOptions.enableCaching
execution?
optionalexecution?:ExecutionContext
Defined in: core/dist/types/types.d.ts:598
Scoped invocation context. Propagate it unchanged when calling children.
extraVars?
optionalextraVars?:Record<string,unknown>
Defined in: core/dist/types/baleybot-call-options.d.ts:228
Extra variable bindings injected at process-time (used by BAL map/for iterators).
Inherited from
LeafCallOptions.extraVars
fallbackModels?
optionalfallbackModels?: readonly (string|ModelConfig|AISDKLanguageModel)[]
Defined in: core/dist/types/baleybot-call-options.d.ts:283
Models to continue on when a model call fails (overrides
BaleybotConfig.fallbackModels for this call; [] disables failover).
The next model resumes from the completed work — nothing is replayed.
Inherited from
LeafCallOptions.fallbackModels
headers?
optionalheaders?:Record<string,string|undefined>
Defined in: core/dist/types/baleybot-call-options.d.ts:248
Extra HTTP headers for this call's model requests (AI SDK headers), on
top of the model config's config.headers. E.g. a per-request trace id or
a gateway routing header. Applies to every step of the call.
Inherited from
LeafCallOptions.headers
hooks?
optionalhooks?:ProcessHooks
Defined in: core/dist/types/types.d.ts:662
Per-step lifecycle hooks. Awaitable — the runner awaits each hook before proceeding, so persistence can land before the next step runs.
Every composite fires the boundary hooks — onStepStart and one
terminal: graph() per node, pipeline() per step, loop/map/filter
per iteration, gate/router/tryCatch for the branch actually taken,
and parallel() for fanOut, each branch, and the merge.
onStepEvent is narrower — today only graph() intercepts a child's
stream and forwards it. Passing hooks to a pipeline() gets you its step
boundaries but no per-token events; subscribeToAll() on the step is the
way to watch those in the meantime.
A composite fires boundaries for the children it runs; a leaf never fires for itself. That is what makes nesting work without a double-fire guard — if a bot reported its own boundary and the graph containing it reported one on its behalf, every bot in a graph would appear twice.
The consequence worth knowing: bot.process(input, { hooks }) on a lone
bot fires nothing, because nothing composed it. Use subscribeToAll(),
which every Processable supports, to observe a single processable —
hooks describe composition, and a lone bot has none.
Nested composites qualify their children's ids via NodeContext.path,
so [...path, nodeId] is unique across arbitrary nesting where bare
nodeId is not.
onStepEvent is fed from the same subscribeToAll contract every
Processable implements; there is no separate event-emission path.
See ProcessHooks in ./core/hooks.ts for the full callback shape and
ordering contract.
hooksAreFatal?
optionalhooksAreFatal?:boolean
Defined in: core/dist/types/types.d.ts:668
If true, a throwing hook rejects the run. Default (false) logs the error and continues execution — observability should not be able to break a pipeline by accident.
interruptResponses?
optionalinterruptResponses?:InterruptResponse[]
Defined in: core/dist/types/baleybot-call-options.d.ts:173
Resume answers for mid-execute() askHuman pauses (baleybots-owned).
Separate from approvalResponses — those are AI SDK native tool gates
before execute. Interrupt responses replay the tool with answers injected so
await askHuman(...) resolves.
Inherited from
LeafCallOptions.interruptResponses
isFallbackError?
optionalisFallbackError?: (error) =>boolean
Defined in: core/dist/types/baleybot-call-options.d.ts:285
Decide which failures move to the next model for this call.
Parameters
error
unknown
Returns
boolean
Inherited from
LeafCallOptions.isFallbackError
maxTokens?
optionalmaxTokens?:number
Defined in: core/dist/types/baleybot-call-options.d.ts:234
Override maxTokens for this call only. Takes precedence over construction-time maxTokens.
Inherited from
LeafCallOptions.maxTokens
model?
optionalmodel?:string|ModelConfig
Defined in: core/dist/types/baleybot-call-options.d.ts:230
Override the model for this call only. Takes precedence over construction-time model. The per-call providerOptions/cacheControl below still apply.
Inherited from
LeafCallOptions.model
modelMessages?
optionalmodelMessages?:ModelMessage[]
Defined in: core/dist/types/baleybot-call-options.d.ts:212
The conversation as AI SDK ModelMessages, sent to the model as they
are, system messages included. It is the whole conversation: it replaces
conversationHistory and the bot's history for the request, and the
input is not appended to it (pass the latest user message in it; the input
still names the turn). The bot's own instructions still go first.
Named apart from ToolExecutionOptions.messages (the calling turn's
Baleybots messages): a tool that forwards its options to a child must not
hand that turn to the child as the child's conversation.
Inherited from
LeafCallOptions.modelMessages
modelToolCallId?
optionalmodelToolCallId?:string
Defined in: core/dist/types/baleybot-call-options.d.ts:226
The id the model gave this call, as tool hooks, stream events and a step's
content name it. In a durable loop toolCallId is the call's stable id
instead, so a host that joins what a tool did to what the step reports
(a retry budget, a receipt) keys on this. Outside a durable loop the two
are the same.
Inherited from
LeafCallOptions.modelToolCallId
onApprovalRequired?
optionalonApprovalRequired?: (botName,toolCall,toolDefinition) =>Promise<ToolApprovalResult>
Defined in: core/dist/types/baleybot-call-options.d.ts:143
Request approval for individual tool calls
Called when a tool has requiresApproval: true or returns true from
its requiresApproval function. This is called per-tool, not per-batch.
Parameters
botName
string
toolCall
ToolCall
toolDefinition
ZodToolDefinition
Returns
Promise<ToolApprovalResult>
Example
const bot = new Baleybot({
name: 'bot',
goal: 'Help with files',
tools: {
deleteFile: defineZodTool({
name: 'delete_file',
description: 'Delete a file',
inputSchema: z.object({ path: z.string() }),
requiresApproval: true, // Always require approval
execute: async ({ path }) => { ... },
}),
},
});
await bot.process('Delete temp.txt', {
onApprovalRequired: async (botName, toolCall, toolDef) => {
// Show approval UI
const approved = await showApprovalDialog(toolCall);
return approved
? { approved: true }
: { approved: false, reason: 'User cancelled' };
},
});
Inherited from
LeafCallOptions.onApprovalRequired
onComplete?
optionalonComplete?: (botName,result) =>void
Defined in: core/dist/types/types.d.ts:625
Parameters
botName
string
result
unknown
Returns
void
onError?
optionalonError?: (botName,error) =>void
Defined in: core/dist/types/types.d.ts:626
Parameters
botName
string
error
Error
Returns
void
onInterruptRequired?
optionalonInterruptRequired?: (botName,request) =>Promise<InterruptAnswer| {cancelled:true;reason?:string; }>
Defined in: core/dist/types/baleybot-call-options.d.ts:179
In-process handler for askHuman (Alert.showAlert-style).
When omitted, askHuman emits interrupt_request and throws InterruptSignal
so the turn can pause for an edge resume.
Parameters
botName
string
request
InterruptRequest
Returns
Promise<InterruptAnswer | { cancelled: true; reason?: string; }>
Inherited from
LeafCallOptions.onInterruptRequired
onLanguageModelCallEnd?
optionalonLanguageModelCallEnd?: (event) =>unknown
Defined in: core/dist/types/baleybot-call-options.d.ts:341
AI SDK onLanguageModelCallEnd: each model call's content, finish reason
and usage, before any tool of that call runs (AI SDK awaits it). Thin
passthrough. In a checkpointed run the step's tool calls are journaled
first, then this runs; a step answered from the journal reports its
recorded call again.
Parameters
event
LanguageModelCallEndEvent<ToolSet>
Returns
unknown
Inherited from
LeafCallOptions.onLanguageModelCallEnd
onStart?
optionalonStart?: (botName) =>void
Defined in: core/dist/types/types.d.ts:601
Parameters
botName
string
Returns
void
onStepEnd?
optionalonStepEnd?:GenerateTextOnStepEndCallback<ToolSet>
Defined in: core/dist/types/baleybot-call-options.d.ts:333
Override AI SDK onStepEnd for this call only. Thin passthrough.
Inherited from
LeafCallOptions.onStepEnd
onToken?
optionalonToken?: ((botName,event) =>void) |TokenHandlers
Defined in: core/dist/types/types.d.ts:624
The run's events as they happen, while process() still resolves to the
final result. Either one callback for every event, or TokenHandlers
with a narrowed handler per event type.
Example
const result = await bot.process(input, {
onToken: {
onTextDelta(botName, event) {
process.stdout.write(event.content);
},
onToolExecutionStream(botName, event) {
const nested = event.nestedEvent;
if (nested.type === 'text_delta') {
process.stdout.write(nested.content);
}
}
}
});
prepareStep?
optionalprepareStep?:PrepareStepFunction<ToolSet>
Defined in: core/dist/types/baleybot-call-options.d.ts:327
Override the configured AI SDK step hook for this call; keep selection state request-scoped.
Inherited from
LeafCallOptions.prepareStep
providerOptions?
optionalproviderOptions?:Record<string,Record<string,unknown>>
Defined in: core/dist/types/baleybot-call-options.d.ts:242
Override provider-specific options for this call only. Takes precedence over construction-time model.config.providerOptions.
Inherited from
LeafCallOptions.providerOptions
repairToolCall?
optionalrepairToolCall?:ToolCallRepairFunction<ToolSet>
Defined in: core/dist/types/baleybot-call-options.d.ts:343
Override AI SDK experimental_repairToolCall for this call only. Thin passthrough.
Inherited from
LeafCallOptions.repairToolCall
resumeHistory?
optionalresumeHistory?:StoredHistoryV2
Defined in: core/dist/types/baleybot-call-options.d.ts:185
Restore canonical segments before this invocation (including pending interrupts). Baleybot restores this itself; custom Processables can use conversationHistory.
Inherited from
LeafCallOptions.resumeHistory
runtimeContext?
optionalruntimeContext?:unknown
Defined in: core/dist/types/baleybot-call-options.d.ts:345
Override AI SDK runtimeContext for this call only. Thin passthrough.
Inherited from
LeafCallOptions.runtimeContext
signal?
optionalsignal?:AbortSignal
Defined in: core/dist/types/types.d.ts:600
skillState?
optionalskillState?:SkillState
Defined in: core/dist/types/baleybot-call-options.d.ts:277
Restore loaded-skill state before this call (a saved
Baleybot.getSkillState()). For a per-request bot that continues a
conversation; read getSkillState() after the call to save it again.
Inherited from
LeafCallOptions.skillState
steer?
optionalsteer?:SteerSource
Defined in: core/dist/types/baleybot-call-options.d.ts:314
Words that arrive while this call is running, merged before the next
model step (see createSteerQueue). A steer_merged event reports each
merge; record it with the conversation.
Inherited from
LeafCallOptions.steer
stopSequences?
optionalstopSequences?:string[]
Defined in: core/dist/types/baleybot-call-options.d.ts:238
AI SDK stopSequences for every model call of this call. Thin passthrough.
Inherited from
LeafCallOptions.stopSequences
stopWhen?
optionalstopWhen?:StopCondition
Defined in: core/dist/types/baleybot-call-options.d.ts:240
Override stopWhen for this call only. Takes precedence over construction-time stopWhen.
Inherited from
LeafCallOptions.stopWhen
temperature?
optionaltemperature?:number
Defined in: core/dist/types/baleybot-call-options.d.ts:232
Override temperature for this call only (0–2). Takes precedence over construction-time temperature.
Inherited from
LeafCallOptions.temperature
toolCallId?
optionaltoolCallId?:string
Defined in: core/dist/types/baleybot-call-options.d.ts:218
Tool call ID, set by the tool adapter when it runs a Processable tool. Used by tools that emit streaming events (a subagent, say) to identify which tool call the events belong to for correct UI routing.
Inherited from
LeafCallOptions.toolCallId
toolHooks?
optionaltoolHooks?: readonlyToolHook[]
Defined in: core/dist/types/baleybot-call-options.d.ts:320
Tool hooks for this call only, run inside the bot's own
(BaleybotConfig.toolHooks). Composites forward options, so these reach
every tool any bot in the call executes.
Inherited from
LeafCallOptions.toolHooks
toolOrder?
optionaltoolOrder?: readonlystring[]
Defined in: core/dist/types/baleybot-call-options.d.ts:331
Override AI SDK toolOrder for this call only. Thin passthrough.
Inherited from
LeafCallOptions.toolOrder
toolSearch?
optionaltoolSearch?:false|ToolSearchOptions
Defined in: core/dist/types/baleybot-call-options.d.ts:325
Override the bot's toolSearch for this call (a full options object), or
false to send every tool directly.
Inherited from
LeafCallOptions.toolSearch
topP?
optionaltopP?:number
Defined in: core/dist/types/baleybot-call-options.d.ts:236
AI SDK topP (nucleus sampling) for every model call of this call. Thin passthrough.
Inherited from
LeafCallOptions.topP
verbose?
optionalverbose?:boolean
Defined in: core/dist/types/types.d.ts:599
yieldAfterMs?
optionalyieldAfterMs?:number
Defined in: core/dist/types/baleybot-call-options.d.ts:300
With checkpointSteps: stop at the first step boundary after this many
milliseconds, progress saved, by throwing ExecutionYieldedError. Call
again with the same execution to continue (a serverless function that
must end before its time limit).
Inherited from
LeafCallOptions.yieldAfterMs
yieldWhen?
optionalyieldWhen?: (context) =>boolean|Promise<boolean>
Defined in: core/dist/types/baleybot-call-options.d.ts:302
With checkpointSteps: stop at a step boundary, progress saved, when this says so.
Parameters
context
YieldContext
Returns
boolean | Promise<boolean>
Inherited from
LeafCallOptions.yieldWhen