Interface: LeafCallOptions
Defined in: packages/core/src/types.ts:686
Typed pass-through for leaf-specific call options.
Empty here on purpose. A leaf layer that takes its own per-call options
(Baleybot's BaleybotCallOptions: model, sampling, tools, caching,
durability knobs) adds them by augmenting this interface, so
pipeline.process(input, { temperature }) type-checks and reaches every bot
the pipeline runs, while the kernel never names a model knob. Composites
forward these untouched: they spread the options they were given into each
child call and read only the kernel members below.
Extends
Extended by
Properties
activeSkills?
optionalactiveSkills?: readonlystring[]
Defined in: packages/core/src/baleybot-call-options.ts:315
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
BaleybotCallOptions.activeSkills
activeTools?
optionalactiveTools?: readonlystring[]
Defined in: packages/core/src/baleybot-call-options.ts:385
Override AI SDK activeTools for this call only (restrict callable tools). Thin passthrough.
Inherited from
BaleybotCallOptions.activeTools
additionalTools?
optionaladditionalTools?:Tools
Defined in: packages/core/src/baleybot-call-options.ts:305
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
BaleybotCallOptions.additionalTools
approvalResponses?
optionalapprovalResponses?:ApprovalResponse[]
Defined in: packages/core/src/baleybot-call-options.ts:188
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
BaleybotCallOptions.approvalResponses
cache?
optionalcache?:CacheControlOption
Defined in: packages/core/src/baleybot-call-options.ts:126
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
cacheControl?
optionalcacheControl?:CacheControlOption
Defined in: packages/core/src/baleybot-call-options.ts:414
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
BaleybotCallOptions.cacheControl
checkpointSteps?
optionalcheckpointSteps?:boolean
Defined in: packages/core/src/baleybot-call-options.ts:341
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
BaleybotCallOptions.checkpointSteps
compaction?
optionalcompaction?:StepCompaction
Defined in: packages/core/src/baleybot-call-options.ts:359
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
BaleybotCallOptions.compaction
conversationHistory?
optionalconversationHistory?:object[]
Defined in: packages/core/src/baleybot-call-options.ts:217
Conversation history for multi-turn conversations (uses OpenAI ChatMessage format from providers)
content
content:
string|MessageContentBlock[]
role
role:
"user"|"system"|"assistant"|"tool"
tool_call_id?
optionaltool_call_id?:string
tool_calls?
optionaltool_calls?:object[]
Inherited from
BaleybotCallOptions.conversationHistory
defaults?
optionaldefaults?:DefaultsPatch
Defined in: packages/core/src/baleybot-call-options.ts:100
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
enableCaching?
optionalenableCaching?:boolean
Defined in: packages/core/src/baleybot-call-options.ts:112
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
BaleybotCallOptions.enableCaching
extraVars?
optionalextraVars?:Record<string,unknown>
Defined in: packages/core/src/baleybot-call-options.ts:262
Extra variable bindings injected at process-time (used by BAL map/for iterators).
Inherited from
fallbackModels?
optionalfallbackModels?: readonly (string|LanguageModelLike|ModelConfig)[]
Defined in: packages/core/src/baleybot-call-options.ts:329
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
BaleybotCallOptions.fallbackModels
headers?
optionalheaders?:Record<string,string|undefined>
Defined in: packages/core/src/baleybot-call-options.ts:290
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
interruptResponses?
optionalinterruptResponses?:InterruptResponse[]
Defined in: packages/core/src/baleybot-call-options.ts:197
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
BaleybotCallOptions.interruptResponses
isFallbackError?
optionalisFallbackError?: (error) =>boolean
Defined in: packages/core/src/baleybot-call-options.ts:332
Decide which failures move to the next model for this call.
Parameters
error
unknown
Returns
boolean
Inherited from
BaleybotCallOptions.isFallbackError
maxTokens?
optionalmaxTokens?:number
Defined in: packages/core/src/baleybot-call-options.ts:271
Override maxTokens for this call only. Takes precedence over construction-time maxTokens.
Inherited from
model?
optionalmodel?:string|ModelConfig
Defined in: packages/core/src/baleybot-call-options.ts:265
Override the model for this call only. Takes precedence over construction-time model. The per-call providerOptions/cacheControl below still apply.
Inherited from
modelMessages?
optionalmodelMessages?:ModelMessage[]
Defined in: packages/core/src/baleybot-call-options.ts:243
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
BaleybotCallOptions.modelMessages
modelToolCallId?
optionalmodelToolCallId?:string
Defined in: packages/core/src/baleybot-call-options.ts:259
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
BaleybotCallOptions.modelToolCallId
onApprovalRequired?
optionalonApprovalRequired?: (botName,toolCall,toolDefinition) =>Promise<ToolApprovalResult>
Defined in: packages/core/src/baleybot-call-options.ts:161
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
toolDefinition
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
BaleybotCallOptions.onApprovalRequired
onInterruptRequired?
optionalonInterruptRequired?: (botName,request) =>Promise<InterruptAnswer| {cancelled:true;reason?:string; }>
Defined in: packages/core/src/baleybot-call-options.ts:204
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
Returns
Promise<InterruptAnswer | { cancelled: true; reason?: string; }>
Inherited from
BaleybotCallOptions.onInterruptRequired
onLanguageModelCallEnd?
optionalonLanguageModelCallEnd?: (event) =>unknown
Defined in: packages/core/src/baleybot-call-options.ts:400
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
BaleybotCallOptions.onLanguageModelCallEnd
onStepEnd?
optionalonStepEnd?:GenerateTextOnStepEndCallback<ToolSet>
Defined in: packages/core/src/baleybot-call-options.ts:391
Override AI SDK onStepEnd for this call only. Thin passthrough.
Inherited from
prepareStep?
optionalprepareStep?:PrepareStepFunction<ToolSet>
Defined in: packages/core/src/baleybot-call-options.ts:382
Override the configured AI SDK step hook for this call; keep selection state request-scoped.
Inherited from
BaleybotCallOptions.prepareStep
providerOptions?
optionalproviderOptions?:Record<string,Record<string,unknown>>
Defined in: packages/core/src/baleybot-call-options.ts:283
Override provider-specific options for this call only. Takes precedence over construction-time model.config.providerOptions.
Inherited from
BaleybotCallOptions.providerOptions
repairToolCall?
optionalrepairToolCall?:ToolCallRepairFunction<ToolSet>
Defined in: packages/core/src/baleybot-call-options.ts:403
Override AI SDK experimental_repairToolCall for this call only. Thin passthrough.
Inherited from
BaleybotCallOptions.repairToolCall
resumeHistory?
optionalresumeHistory?:StoredHistoryV2
Defined in: packages/core/src/baleybot-call-options.ts:214
Restore canonical segments before this invocation (including pending interrupts). Baleybot restores this itself; custom Processables can use conversationHistory.
Inherited from
BaleybotCallOptions.resumeHistory
runtimeContext?
optionalruntimeContext?:unknown
Defined in: packages/core/src/baleybot-call-options.ts:406
Override AI SDK runtimeContext for this call only. Thin passthrough.
Inherited from
BaleybotCallOptions.runtimeContext
skillState?
optionalskillState?:SkillState
Defined in: packages/core/src/baleybot-call-options.ts:322
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
BaleybotCallOptions.skillState
steer?
optionalsteer?:SteerSource
Defined in: packages/core/src/baleybot-call-options.ts:366
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
stopSequences?
optionalstopSequences?:string[]
Defined in: packages/core/src/baleybot-call-options.ts:277
AI SDK stopSequences for every model call of this call. Thin passthrough.
Inherited from
BaleybotCallOptions.stopSequences
stopWhen?
optionalstopWhen?:StopCondition
Defined in: packages/core/src/baleybot-call-options.ts:280
Override stopWhen for this call only. Takes precedence over construction-time stopWhen.
Inherited from
temperature?
optionaltemperature?:number
Defined in: packages/core/src/baleybot-call-options.ts:268
Override temperature for this call only (0–2). Takes precedence over construction-time temperature.
Inherited from
BaleybotCallOptions.temperature
toolCallId?
optionaltoolCallId?:string
Defined in: packages/core/src/baleybot-call-options.ts:250
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
BaleybotCallOptions.toolCallId
toolHooks?
optionaltoolHooks?: readonlyToolHook[]
Defined in: packages/core/src/baleybot-call-options.ts:373
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
toolOrder?
optionaltoolOrder?: readonlystring[]
Defined in: packages/core/src/baleybot-call-options.ts:388
Override AI SDK toolOrder for this call only. Thin passthrough.
Inherited from
toolSearch?
optionaltoolSearch?:false|ToolSearchOptions
Defined in: packages/core/src/baleybot-call-options.ts:379
Override the bot's toolSearch for this call (a full options object), or
false to send every tool directly.
Inherited from
BaleybotCallOptions.toolSearch
topP?
optionaltopP?:number
Defined in: packages/core/src/baleybot-call-options.ts:274
AI SDK topP (nucleus sampling) for every model call of this call. Thin passthrough.
Inherited from
yieldAfterMs?
optionalyieldAfterMs?:number
Defined in: packages/core/src/baleybot-call-options.ts:349
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
BaleybotCallOptions.yieldAfterMs
yieldWhen?
optionalyieldWhen?: (context) =>boolean|Promise<boolean>
Defined in: packages/core/src/baleybot-call-options.ts:352
With checkpointSteps: stop at a step boundary, progress saved, when this says so.
Parameters
context
Returns
boolean | Promise<boolean>