Skip to main content

Interface: ToolExecutionOptions

Defined in: packages/core/src/utils/tools.ts:50

Tool execution context (AI SDK v6 pattern)

Extended options passed to tool functions during execution. Includes the original ProcessOptions plus tool-specific context.

Example​

const myTool = defineZodTool({
  name: 'my_tool',
  description: 'A tool with context',
  inputSchema: z.object({ data: z.string() }),
  execute: async (params, options) => {
    console.log('Tool call ID:', options?.toolCallId);
    console.log('Message history:', options?.messages?.length);
    return { processed: params.data };
  },
});

Extends​

Properties​

abortSignal?​

optional abortSignal?: AbortSignal

Defined in: packages/core/src/utils/tools.ts:56

Abort signal for cancellation

activeTools?​

optional activeTools?: readonly string[]

Defined in: packages/core/src/types.ts:1179

Override AI SDK activeTools for this call only (restrict callable tools). Thin passthrough.

Inherited from​

ProcessOptions.activeTools

additionalTools?​

optional additionalTools?: Record<string, Processable<unknown, unknown> | ToolDefinition<(...args) => unknown> | ZodToolDefinition<any, any>>

Defined in: packages/core/src/types.ts:1173

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

optional approvalResponses?: ApprovalResponse[]

Defined in: packages/core/src/types.ts:1104

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

cache?​

optional cache?: CacheControlOption

Defined in: packages/core/src/types.ts:965

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​

ProcessOptions.cache

cacheControl?​

optional cacheControl?: CacheControlOption

Defined in: packages/core/src/types.ts:1194

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​

ProcessOptions.cacheControl

conversationHistory?​

optional conversationHistory?: object[]

Defined in: packages/core/src/types.ts:1126

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​

ProcessOptions.conversationHistory

defaults?​

optional defaults?: DefaultsPatch

Defined in: packages/core/src/types.ts:933

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​

ProcessOptions.defaults

enableCaching?​

optional enableCaching?: boolean

Defined in: packages/core/src/types.ts:951

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​

ProcessOptions.enableCaching

execution?​

optional execution?: ExecutionContext

Defined in: packages/core/src/types.ts:925

Scoped invocation context. Propagate it unchanged when calling children.

Inherited from​

ProcessOptions.execution

extraVars?​

optional extraVars?: Record<string, unknown>

Defined in: packages/core/src/types.ts:1147

Extra variable bindings injected at process-time (used by BAL map/for iterators).

Inherited from​

ProcessOptions.extraVars

hooks?​

optional hooks?: ProcessHooks

Defined in: packages/core/src/types.ts:1232

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 rides on the same categorized subscribeToAll contract every Processable implements — there is no separate event-emission path, just this graph-specific ordering/batching layer on top of it.

See ProcessHooks in ./graph/types.ts for the full callback shape and ordering contract.

Inherited from​

ProcessOptions.hooks

hooksAreFatal?​

optional hooksAreFatal?: boolean

Defined in: packages/core/src/types.ts:1239

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​

ProcessOptions.hooksAreFatal

interruptResponses?​

optional interruptResponses?: InterruptResponse[]

Defined in: packages/core/src/types.ts:1112

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

maxTokens?​

optional maxTokens?: number

Defined in: packages/core/src/types.ts:1154

Override maxTokens for this call only. Takes precedence over construction-time maxTokens.

Inherited from​

ProcessOptions.maxTokens

messages?​

optional messages?: ChatMessage[]

Defined in: packages/core/src/utils/tools.ts:54

Current message history (for context-aware tools)

model?​

optional model?: string | ModelConfig

Defined in: packages/core/src/types.ts:1150

Override the model for this call only. Takes precedence over construction-time model. Independent of providerOptions/cacheControl below — overriding the model no longer drops them.

Inherited from​

ProcessOptions.model

onApprovalRequired?​

optional onApprovalRequired?: (botName, toolCall, toolDefinition) => Promise<ToolApprovalResult>

Defined in: packages/core/src/types.ts:1078

Request approval for individual tool calls (v6 pattern)

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<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, unknown>

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

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

Defined in: packages/core/src/types.ts:1043

Called when processing completes with final result

Note: You can also get the final result from process() return value. This callback is provided for convenience when you need both streaming and completion notification.

Parameters​

botName​

string

result​

unknown

Returns​

void

Inherited from​

ProcessOptions.onComplete

onError?​

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

Defined in: packages/core/src/types.ts:1044

Parameters​

botName​

string

error​

Error

Returns​

void

Inherited from​

ProcessOptions.onError

onInterruptRequired?​

optional onInterruptRequired?: (botName, request) => Promise<InterruptAnswer | { cancelled: true; reason?: string; }>

Defined in: packages/core/src/types.ts:1118

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​

ProcessOptions.onInterruptRequired

onStart?​

optional onStart?: (botName) => void

Defined in: packages/core/src/types.ts:967

Parameters​

botName​

string

Returns​

void

Inherited from​

ProcessOptions.onStart

onStepEnd?​

optional onStepEnd?: GenerateTextOnStepEndCallback<ToolSet, Context>

Defined in: packages/core/src/types.ts:1183

Override AI SDK onStepEnd for this call only. Thin passthrough.

Inherited from​

ProcessOptions.onStepEnd

onToken?​

optional onToken?: ((botName, event) => void) | TokenHandlers

Defined in: packages/core/src/types.ts:1036

Streaming event handlers - receive events in real-time during execution

You can use BOTH streaming events AND final results together:

  • Streaming events: Provide onToken handlers to receive real-time updates via callbacks
  • Final result: Also available when process() Promise resolves (see return value)

Accepts either:

  • A callback function that receives all events
  • An object with specific handlers for each event type (recommended for type safety)

Examples​

Using both streaming AND final result (recommended)

// Stream events in real-time AND get final result
const result = await bot.process(input, {
  onToken: {
    // Real-time streaming events
    onTextDelta(botName, event) {
      process.stdout.write(event.content);  // Stream as it generates
    },
    onToolExecutionStart(botName, event) {
      console.log(`🔧 ${event.toolName} starting...`);  // Real-time tool status
    },
    onToolExecutionOutput(botName, event) {
      console.log(`✅ Tool result:`, event.result);  // Final tool result event
    },
    onToolExecutionStream(botName, event) {
      // Nested streaming from child bots
      const nested = event.nestedEvent;
      if (nested.type === 'text_delta') {
        process.stdout.write(nested.content);  // Child bot streaming
      }
    }
  }
});

// Final result available when Promise resolves
console.log('Final response:', result);  // Complete parsed response

Streaming-only (ignore final result)

await bot.process(input, {
  onToken: (botName, event) => {
    if (event.type === 'text_delta') {
      process.stdout.write(event.content);
    }
  }
});
// Don't await or use return value if you only care about streaming

Final-only (ignore streaming)

const result = await bot.process(input);
// No onToken = no streaming, just wait for final result
console.log('Response:', result);

Function approach

onToken(botName, event) {
  if (event.type === 'tool_execution_start') {
    console.log(`Starting ${event.toolName}`);
  }
}

Inherited from​

ProcessOptions.onToken

prepareStep?​

optional prepareStep?: PrepareStepFunction<ToolSet, Context>

Defined in: packages/core/src/types.ts:1176

Override the configured AI SDK step hook for this call; keep selection state request-scoped.

Inherited from​

ProcessOptions.prepareStep

providerOptions?​

optional providerOptions?: Record<string, Record<string, unknown>>

Defined in: packages/core/src/types.ts:1158

Override provider-specific options for this call only. Takes precedence over construction-time model.config.providerOptions.

Inherited from​

ProcessOptions.providerOptions

repairToolCall?​

optional repairToolCall?: ToolCallRepairFunction<ToolSet>

Defined in: packages/core/src/types.ts:1185

Override AI SDK experimental_repairToolCall for this call only. Thin passthrough.

Inherited from​

ProcessOptions.repairToolCall

runtimeContext?​

optional runtimeContext?: unknown

Defined in: packages/core/src/types.ts:1187

Override AI SDK runtimeContext for this call only. Thin passthrough.

Inherited from​

ProcessOptions.runtimeContext

signal?​

optional signal?: AbortSignal

Defined in: packages/core/src/types.ts:939

AbortSignal to cancel the request

Inherited from​

ProcessOptions.signal

stopWhen?​

optional stopWhen?: StopCondition

Defined in: packages/core/src/types.ts:1156

Override stopWhen for this call only. Takes precedence over construction-time stopWhen.

Inherited from​

ProcessOptions.stopWhen

temperature?​

optional temperature?: number

Defined in: packages/core/src/types.ts:1152

Override temperature for this call only (0–2). Takes precedence over construction-time temperature.

Inherited from​

ProcessOptions.temperature

toolCallId​

toolCallId: string

Defined in: packages/core/src/utils/tools.ts:52

Unique ID of this tool call

Overrides​

ProcessOptions.toolCallId

toolOrder?​

optional toolOrder?: readonly string[]

Defined in: packages/core/src/types.ts:1181

Override AI SDK toolOrder for this call only. Thin passthrough.

Inherited from​

ProcessOptions.toolOrder

verbose?​

optional verbose?: boolean

Defined in: packages/core/src/types.ts:936

Enable verbose logging for debugging

Inherited from​

ProcessOptions.verbose