Interface: ExecutionStartOptions
Defined in: packages/core/src/runtime/executor.ts:87
What every call of every Processable carries: cancellation, callbacks, composition hooks.
Extends
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
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
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
ProcessOptions.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
ProcessOptions.approvalResponses
attempts?
optionalattempts?:"run"|"place"
Defined in: packages/core/src/runtime/executor.ts:111
Who counts the run's attempts and infrastructure failures. Default
'run': the run counts them in its journal and stops as
retry-exhausted at the policy's limits. A place that decides re-drives
on its own schedule (a Durable Object) passes 'place' and counts them
itself; the run then keeps no count and never stops itself for retries.
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
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
ProcessOptions.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
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
ProcessOptions.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
durability?
optionaldurability?:"strict"|"lenient"
Defined in: packages/core/src/runtime/executor.ts:103
'strict' rejects unversioned opaque code at start. Default 'lenient'.
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
execution?
optionalexecution?:ExecutionContext
Defined in: packages/core/src/types.ts:691
Scoped invocation context. Propagate it unchanged when calling children.
Inherited from
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
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
hooks?
optionalhooks?:ProcessHooks
Defined in: packages/core/src/types.ts:762
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.
Inherited from
hooksAreFatal?
optionalhooksAreFatal?:boolean
Defined in: packages/core/src/types.ts:769
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.
Inherited from
index?
optionalindex?:RunIndex
Defined in: packages/core/src/runtime/executor.ts:99
Where the place records, heartbeats and settles the run.
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
ProcessOptions.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
ProcessOptions.isFallbackError
journal?
optionaljournal?:ExecutionJournal
Defined in: packages/core/src/runtime/executor.ts:93
Where the local place records step answers. Without one, a run is as durable as its process.
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
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
ProcessOptions.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
ProcessOptions.onApprovalRequired
onComplete?
optionalonComplete?: (botName,result) =>void
Defined in: packages/core/src/types.ts:723
Parameters
botName
string
result
unknown
Returns
void
Inherited from
onError?
optionalonError?: (botName,error) =>void
Defined in: packages/core/src/types.ts:725
Parameters
botName
string
error
Error
Returns
void
Inherited from
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
ProcessOptions.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
ProcessOptions.onLanguageModelCallEnd
onStart?
optionalonStart?: (botName) =>void
Defined in: packages/core/src/types.ts:697
Parameters
botName
string
Returns
void
Inherited from
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
onToken?
optionalonToken?:TokenHandlers| ((botName,event) =>void)
Defined in: packages/core/src/types.ts:721
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);
}
}
}
});
Inherited from
policy?
optionalpolicy?:RunPolicy
Defined in: packages/core/src/runtime/executor.ts:97
Overrides fields of the place's default policy.
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
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
ProcessOptions.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
requestId?
optionalrequestId?:string
Defined in: packages/core/src/runtime/executor.ts:89
Stable admission key, reused when retrying the same input.
requires?
optionalrequires?: readonly keyofExecutionCapabilities[]
Defined in: packages/core/src/runtime/executor.ts:101
Guarantees the caller requires on top of the inferred ones.
resolutions?
optionalresolutions?: readonlyExecutionResolution[]
Defined in: packages/core/src/runtime/executor.ts:95
Answers for pending approvals, applied before the run is driven. Requires a journal.
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
runId?
optionalrunId?:string
Defined in: packages/core/src/runtime/executor.ts:91
The run's id. Starting the same id again attaches to it, or resumes it. Defaults to requestId, then a UUID.
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
signal?
optionalsignal?:AbortSignal
Defined in: packages/core/src/types.ts:695
Inherited from
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
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
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
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
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
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
verbose?
optionalverbose?:boolean
Defined in: packages/core/src/types.ts:693
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
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>