Skip to main content

Interface: ProcessOptions

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

Extended by​

Properties​

activeTools?​

optional activeTools?: readonly string[]

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

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

approvalResponses?​

optional approvalResponses?: object[]

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

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.

approvalId​

approvalId: string

approved​

approved: boolean

reason?​

optional reason?: string

Example​

await bot.process('Delete temp.txt', {
  conversationHistory: priorMessages,
  approvalResponses: [{ approvalId, approved: true }],
});

cacheControl?​

optional cacheControl?: boolean

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

Override prompt-cache-control for this call only. Takes precedence over construction-time model.cacheControl and the enableCaching shorthand above.

conversationHistory?​

optional conversationHistory?: object[]

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

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[]

enableCaching?​

optional enableCaching?: boolean

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

Enable prompt caching for multi-agent pipelines. When true, each agent's system message gets cache control markers, allowing shared document context to be cached across parallel agent calls.

Especially beneficial for extraction pipelines where multiple agents process the same document simultaneously — cached reads cost only 10% (Anthropic) or 50% (OpenAI) of normal input price.

extraVars?​

optional extraVars?: Record<string, unknown>

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

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

hooks?​

optional hooks?: ProcessHooks

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

Per-step lifecycle hooks. Awaitable — the runner awaits each hook before proceeding, so persistence can land before the next step runs.

Currently only honored by graph()-built Processables, which fire hooks per node with that node's nodeId/nodeLabel. A lone Baleybot or a pipeline() chain does not read this option — step-boundary semantics (what counts as "a step", what NodeContext means) don't generalize cleanly to a single-step invocation or a plain sequential chain, so this stays graph-scoped rather than half-implemented elsewhere. Use subscribeToAll() (universally supported) for cross-Processable event observation instead.

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.

hooksAreFatal?​

optional hooksAreFatal?: boolean

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

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.

maxTokens?​

optional maxTokens?: number

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

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

model?​

optional model?: string | ModelConfig

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

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.

onApprovalRequired?​

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

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

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' };
  },
});

onComplete?​

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

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

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

onError?​

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

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

Parameters​

botName​

string

error​

Error

Returns​

void

onStart?​

optional onStart?: (botName) => void

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

Parameters​

botName​

string

Returns​

void

onStepEnd?​

optional onStepEnd?: GenerateTextOnStepEndCallback<ToolSet, Context>

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

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

onToken?​

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

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

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}`);
  }
}

providerOptions?​

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

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

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

repairToolCall?​

optional repairToolCall?: ToolCallRepairFunction<ToolSet>

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

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

runtimeContext?​

optional runtimeContext?: unknown

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

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

signal?​

optional signal?: AbortSignal

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

AbortSignal to cancel the request

stopWhen?​

optional stopWhen?: StopCondition

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

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

temperature?​

optional temperature?: number

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

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

toolCallId?​

optional toolCallId?: string

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

Tool call ID - set by executeTools when invoking a tool. Used by tools that emit streaming events (like spawn_agent) to identify which tool call the events belong to for correct UI routing.

toolOrder?​

optional toolOrder?: readonly string[]

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

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

verbose?​

optional verbose?: boolean

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

Enable verbose logging for debugging