Skip to main content

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?​

optional activeSkills?: readonly string[]

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?​

optional activeTools?: readonly string[]

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?​

optional additionalTools?: 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?​

optional approvalResponses?: 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?​

optional cache?: 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 4
  • false — 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?​

optional cacheControl?: 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?​

optional checkpointSteps?: 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?​

optional compaction?: 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?​

optional conversationHistory?: 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?​

optional tool_call_id?: string

tool_calls?​

optional tool_calls?: object[]

Inherited from​

LeafCallOptions.conversationHistory


defaults?​

optional defaults?: 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?​

optional enableCaching?: 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?​

optional execution?: ExecutionContext

Defined in: core/dist/types/types.d.ts:598

Scoped invocation context. Propagate it unchanged when calling children.


extraVars?​

optional extraVars?: 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?​

optional fallbackModels?: 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?​

optional headers?: 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?​

optional hooks?: 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?​

optional hooksAreFatal?: 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?​

optional interruptResponses?: 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?​

optional isFallbackError?: (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?​

optional maxTokens?: 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?​

optional model?: 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?​

optional modelMessages?: 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?​

optional modelToolCallId?: 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?​

optional onApprovalRequired?: (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?​

optional onComplete?: (botName, result) => void

Defined in: core/dist/types/types.d.ts:625

Parameters​

botName​

string

result​

unknown

Returns​

void


onError?​

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

Defined in: core/dist/types/types.d.ts:626

Parameters​

botName​

string

error​

Error

Returns​

void


onInterruptRequired?​

optional onInterruptRequired?: (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?​

optional onLanguageModelCallEnd?: (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?​

optional onStart?: (botName) => void

Defined in: core/dist/types/types.d.ts:601

Parameters​

botName​

string

Returns​

void


onStepEnd?​

optional onStepEnd?: 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?​

optional onToken?: ((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?​

optional prepareStep?: 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?​

optional providerOptions?: 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?​

optional repairToolCall?: 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?​

optional resumeHistory?: 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?​

optional runtimeContext?: 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?​

optional signal?: AbortSignal

Defined in: core/dist/types/types.d.ts:600


skillState?​

optional skillState?: 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?​

optional steer?: 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?​

optional stopSequences?: 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?​

optional stopWhen?: 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?​

optional temperature?: 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?​

optional toolCallId?: 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?​

optional toolHooks?: readonly ToolHook[]

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?​

optional toolOrder?: readonly string[]

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?​

optional toolSearch?: 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?​

optional topP?: 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?​

optional verbose?: boolean

Defined in: core/dist/types/types.d.ts:599


yieldAfterMs?​

optional yieldAfterMs?: 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?​

optional yieldWhen?: (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