@falai/agent 0.9.2 → 1.0.0

package/dist/utils/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAoB,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAa,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAC9D,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,SAAS,EAC/C,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAClE,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,SAAS,EAClD,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GACvC,OAAO,CAAC,MAAM,EAAE,CAAC,CAKnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,MAAM,CAeR;AAoED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,OAAO,CAsBT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE;IAEnD;;;;OAIG;0BACmB,WAAW,GAAG,MAAM,GAAG,SAAS;IAiBtD;;;OAGG;0BACmB,MAAM,GAAG,SAAS;IAIxC;;;OAGG;+BACwB,MAAM,GAAG,SAAS;IAI7C;;;;OAIG;uBACgB,WAAW,GAAG,MAAM,EAAE;IAezC;;;;;OAKG;kCAC2B,MAAM,GAAG,MAAM,EAAE,kBAAiB,OAAO,GAAW,OAAO;EAe5F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EACvE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GACjE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAMlC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,MAAM,EACd,QAAQ,GAAE,MAAU,GACnB,MAAM,CAgBR"}

package/dist/{src/utils → utils}/template.js

@@ -1,3 +1,4 @@
+import { MessageRole, EventKind } from "../types/history";
 /**
  * Renders a template, which can be a string or a function, using the provided context.
  * This function is asynchronous to support template functions that perform async operations.
@@ -166,6 +167,103 @@ export function renderTemplateObject(obj, context) {
     }
     return obj;
 }
+/**
+ * Creates helper functions for working with history and context in templates.
+ * These helpers make it easier to access message content and perform common operations.
+ *
+ * @param history - The event history array
+ * @returns Object containing helper functions
+ */
+export function createTemplateHelpers(history) {
+    const helpers = {
+        /**
+         * Get the last message from history, optionally filtered by role.
+         * @param role - Optional role to filter by (user, assistant, etc.)
+         * @returns The message content or undefined if not found
+         */
+        getLastMessage(role) {
+            if (!history || history.length === 0)
+                return undefined;
+            // Search backwards through history for the most recent message
+            for (let i = history.length - 1; i >= 0; i--) {
+                const event = history[i];
+                if (event.kind === EventKind.MESSAGE) {
+                    // If no role specified, return the first message found
+                    if (!role || event.source === role) {
+                        const messageData = event.data;
+                        return messageData.message;
+                    }
+                }
+            }
+            return undefined;
+        },
+        /**
+         * Get the last user message from history.
+         * @returns The user message content or undefined if not found
+         */
+        getLastUserMessage() {
+            return helpers.getLastMessage(MessageRole.USER);
+        },
+        /**
+         * Get the last assistant message from history.
+         * @returns The assistant message content or undefined if not found
+         */
+        getLastAssistantMessage() {
+            return helpers.getLastMessage(MessageRole.ASSISTANT);
+        },
+        /**
+         * Get all messages from history, optionally filtered by role.
+         * @param role - Optional role to filter by
+         * @returns Array of message contents
+         */
+        getMessages(role) {
+            if (!history || history.length === 0)
+                return [];
+            const messages = [];
+            for (const event of history) {
+                if (event.kind === EventKind.MESSAGE) {
+                    if (!role || event.source === role) {
+                        const messageData = event.data;
+                        messages.push(messageData.message);
+                    }
+                }
+            }
+            return messages;
+        },
+        /**
+         * Check if the last message contains any of the given keywords.
+         * @param keywords - Keywords to search for
+         * @param caseSensitive - Whether to perform case-sensitive search (default: false)
+         * @returns True if any keyword is found
+         */
+        lastMessageContains(keywords, caseSensitive = false) {
+            const lastMessage = helpers.getLastMessage();
+            if (!lastMessage)
+                return false;
+            const searchText = caseSensitive ? lastMessage : lastMessage.toLowerCase();
+            const keywordArray = Array.isArray(keywords) ? keywords : [keywords];
+            return keywordArray.some(keyword => {
+                const searchKeyword = caseSensitive ? keyword : keyword.toLowerCase();
+                return searchText.includes(searchKeyword);
+            });
+        },
+    };
+    return helpers;
+}
+/**
+ * Creates a complete TemplateContext with helpers included.
+ * This is a convenience function for creating template contexts with all the helper methods.
+ *
+ * @param params - The base template context parameters
+ * @returns Complete TemplateContext with helpers
+ */
+export function createTemplateContext(params) {
+    return {
+        ...params,
+        data: params.data || {},
+        helpers: createTemplateHelpers(params.history),
+    };
+}
 /**
  * Formats a JSON structure into readable markdown format.
  * Handles nested objects, arrays, and primitive values.

package/dist/utils/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"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"}

package/docs/api/README.md

@@ -15,6 +15,106 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
 
 ---
 
+## ConditionTemplate System
+
+### `ConditionTemplate<TContext, TData>`
+
+**NEW:** Enhanced condition type that supports flexible routing logic with both AI context and programmatic evaluation.
+
+```typescript
+type ConditionTemplate<TContext = unknown, TData = unknown> =
+  | string  // AI context only - provides context to AI for routing decisions
+  | ((params: TemplateContext<TContext, TData>) => boolean | Promise<boolean>) // Programmatic evaluation
+  | ConditionTemplate<TContext, TData>[]; // Array of either type
+```
+
+**Key Features:**
+
+- **String conditions**: Provide AI context for routing decisions (e.g., `"user wants to book a flight"`)
+- **Function conditions**: Execute programmatic logic returning boolean (e.g., `(ctx) => ctx.data?.isLoggedIn === true`)
+- **Array conditions**: Combine multiple conditions with logical operators
+- **Hybrid approach**: Mix strings and functions for optimal flexibility
+
+#### Evaluation Logic
+
+**For `when` conditions (AND logic):**
+- **Functions**: All must return `true` for condition to pass
+- **Strings**: Ignored in programmatic evaluation, used for AI context
+- **Arrays**: All functions must return `true`
+
+**For `skipIf` conditions (OR logic):**
+- **Functions**: Any returning `true` causes skip
+- **Strings**: Ignored in programmatic evaluation, used for AI context  
+- **Arrays**: Any function returning `true` causes skip
+
+#### Usage Examples
+
+```typescript
+// String-only condition (AI context)
+when: "User wants to make a reservation"
+
+// Function-only condition (programmatic)
+when: (ctx) => ctx.data?.userType === 'premium'
+
+// Mixed array condition (hybrid approach)
+when: [
+  "User is asking for help", // AI context
+  (ctx) => ctx.data?.isLoggedIn === true // Programmatic check
+]
+
+// Route skipIf with OR logic
+skipIf: [
+  "System is under maintenance", // AI context
+  (ctx) => ctx.data?.maintenanceMode === true // Programmatic check
+]
+```
+
+### `ConditionEvaluator<TContext, TData>`
+
+**NEW:** Utility class for evaluating ConditionTemplate instances with consistent logic across the framework.
+
+#### Constructor
+
+```typescript
+new ConditionEvaluator<TContext, TData>(templateContext: TemplateContext<TContext, TData>)
+```
+
+#### Methods
+
+##### `evaluateCondition(condition, logic?): Promise<ConditionEvaluationResult>`
+
+Evaluates a ConditionTemplate and returns detailed results.
+
+**Parameters:**
+- `condition`: ConditionTemplate to evaluate
+- `logic`: 'AND' | 'OR' - logical operator for arrays (default: 'AND')
+
+**Returns:**
+```typescript
+interface ConditionEvaluationResult {
+  programmaticResult: boolean; // Result of function evaluations only
+  aiContextStrings: string[]; // String values for AI context
+  hasProgrammaticConditions: boolean; // Whether any functions were evaluated
+}
+```
+
+**Example:**
+
+```typescript
+const evaluator = new ConditionEvaluator(templateContext);
+
+const result = await evaluator.evaluateCondition([
+  "User needs premium support", // AI context
+  (ctx) => ctx.data?.userType === 'premium' // Programmatic
+]);
+
+console.log(result.programmaticResult); // true/false from function
+console.log(result.aiContextStrings); // ["User needs premium support"]
+console.log(result.hasProgrammaticConditions); // true
+```
+
+---
+
 ## Core Classes
 
 ### `Agent<TContext, TData>`
@@ -823,7 +923,8 @@ interface RouteOptions<TData = unknown> {
   description?: string;     // Route description
   identity?: string;        // Optional identity prompt defining the agent's role and persona for this route
   personality?: Template;   // Optional personality prompt defining the agent's communication style for this route
-  conditions?: string[];    // Conditions that activate this route
+  when?: ConditionTemplate; // NEW: Conditions that activate this route (replaces conditions)
+  skipIf?: ConditionTemplate; // NEW: Conditions that exclude this route from consideration
   guidelines?: Guideline[]; // Initial guidelines for this route
   terms?: Term[];          // Initial terms for the route's domain glossary
   rules?: string[];         // Absolute rules the agent MUST follow in this route
@@ -935,7 +1036,7 @@ console.log(description);
 // Route: Book Flight
 // ID: route_book_flight
 // Description: N/A
-// Conditions: None
+// When: None
 //
 // Steps:
 //   - step_ask_destination: Ask where to fly
@@ -1003,9 +1104,13 @@ Route title (readonly).
 
 Route description (readonly).
 
-##### `conditions: string[]`
+##### `when?: ConditionTemplate`
+
+**NEW:** Conditions that trigger this route (readonly). Can be a string, function, or array of either.
 
-Conditions that trigger this route (readonly).
+##### `skipIf?: ConditionTemplate`
+
+**NEW:** Conditions that exclude this route from consideration (readonly). Can be a string, function, or array of either.
 
 ##### `initialStep: Step`
 
@@ -1038,14 +1143,14 @@ interface StepOptions<TData = unknown> {
   // NEW: Data extraction fields for this step
   collect?: string[];
 
-  // NEW: Code-based condition to skip this step
-  skipIf?: (data: Partial<TData>) => boolean;
+  // ENHANCED: Flexible condition to determine when this step should be active
+  when?: ConditionTemplate<TContext, TData>;
+
+  // ENHANCED: Flexible condition to skip this step
+  skipIf?: ConditionTemplate<TContext, TData>;
 
   // NEW: Prerequisites that must be met to enter this step
   requires?: string[];
-
-  // Optional: AI-evaluated text condition for this transition
-  condition?: string;
 }
 
 interface Step<TContext = unknown, TData = unknown> {
@@ -1054,7 +1159,8 @@ interface Step<TContext = unknown, TData = unknown> {
   nextStep: (spec: StepOptions<TContext, TData>) => Step<TContext, TData>;
   description?: string; // Step description
   collect?: (keyof TData)[]; // Fields to collect in this step
-  skipIf?: (data: Partial<TData>) => boolean; // Skip condition function
+  when?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition for step activation
+  skipIf?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition to skip step
   requires?: (keyof TData)[]; // Required data prerequisites
 }
 ```
@@ -1230,6 +1336,109 @@ Step description (readonly).
 
 ---
 
+### `StepResult`
+
+Result interface returned by step transition methods that enables fluent chaining of conversation flows. Combines step reference with the ability to chain transitions and create branches.
+
+#### Interface
+
+```typescript
+interface StepResult<TContext = unknown, TData = unknown> extends StepRef {
+  /** Allow chaining transitions */
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  /** Create multiple branches from this step */
+  branch: (
+    branches: BranchSpec<TContext, TData>[]
+  ) => BranchResult<TContext, TData>;
+  /** Shortcut to end the current route */
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
+}
+```
+
+#### Methods
+
+##### `nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>`
+
+Creates a transition from this step and returns a chainable result for building linear flows.
+
+**Example:**
+
+```typescript
+// Linear flow chaining
+const flow = route.initialStep
+  .nextStep({
+    prompt: "Ask for destination",
+    collect: ["destination"]
+  })
+  .nextStep({
+    prompt: "Ask for dates", 
+    collect: ["departureDate", "returnDate"]
+  })
+  .nextStep({
+    prompt: "Confirm booking details"
+  });
+```
+
+##### `branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>`
+
+Creates multiple conditional branches from this step for complex conversation flows.
+
+**Example:**
+
+```typescript
+// Branching flow
+const branches = askIssueType.branch([
+  {
+    name: "technical",
+    step: {
+      prompt: "Let me help with your technical issue",
+      when: "issue type is technical"
+    }
+  },
+  {
+    name: "billing", 
+    step: {
+      prompt: "I'll connect you with billing support",
+      when: "issue type is billing"
+    }
+  }
+]);
+
+// Continue each branch independently
+branches.technical.nextStep({ prompt: "What device are you using?" });
+branches.billing.nextStep({ prompt: "What's your account number?" });
+```
+
+##### `endRoute(options?: Omit<StepOptions<TContext, TData>, "step">): StepResult<TContext, TData>`
+
+Shortcut method to end the current route with optional completion configuration.
+
+**Example:**
+
+```typescript
+// Simple route completion
+askConfirmation.endRoute();
+
+// Route completion with final message
+askConfirmation.endRoute({
+  prompt: "Thank you! Your booking is confirmed."
+});
+```
+
+#### Properties
+
+Inherits all properties from `StepRef`:
+
+##### `id: string`
+
+Step identifier (readonly).
+
+##### `routeId: string`
+
+Route this step belongs to (readonly).
+
+---
+
 ---
 
 ## Tool Execution
@@ -2394,9 +2603,9 @@ interface Term<TContext = unknown> {
 ### `Guideline`
 
 ```typescript
-interface Guideline<TContext = unknown> {
+interface Guideline<TContext = unknown, TData = unknown> {
   id?: string;
-  condition?: Template<TContext>;
+  condition?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition for guideline activation
   action: Template<TContext>;
   enabled?: boolean; // Default: true
   tags?: string[];

package/docs/api/overview.md

@@ -394,9 +394,9 @@ configure(config: Partial<StepOptions<TContext, TData>>): this
 ##### Transitions
 
 ```typescript
-nextStep(spec: StepOptions<TContext, TData>): Step<TContext, TData>
+nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>
 branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>
-endRoute(options?: Omit<StepOptions<TContext, TData>, 'step'>): Step<TContext, TData>
+endRoute(options?: Omit<StepOptions<TContext, TData>, 'step'>): StepResult<TContext, TData>
 ```
 
 ##### Validation
@@ -422,6 +422,55 @@ getRef(): StepRef
 
 ---
 
+### StepResult
+
+Result interface returned by step transition methods that enables fluent chaining of conversation flows.
+
+#### Interface
+
+```typescript
+interface StepResult<TContext = unknown, TData = unknown> extends StepRef {
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  branch: (branches: BranchSpec<TContext, TData>[]) => BranchResult<TContext, TData>;
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
+}
+```
+
+#### Methods
+
+##### Chaining
+
+```typescript
+nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>
+```
+
+Creates a transition and returns a chainable result for building linear flows.
+
+##### Branching
+
+```typescript
+branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>
+```
+
+Creates multiple conditional branches for complex conversation flows.
+
+##### Route Completion
+
+```typescript
+endRoute(options?: Omit<StepOptions<TContext, TData>, "step">): StepResult<TContext, TData>
+```
+
+Shortcut method to end the current route with optional completion configuration.
+
+#### Properties
+
+Inherits from `StepRef`:
+
+- `id: string` - Step identifier
+- `routeId: string` - Route this step belongs to
+
+---
+
 ### RoutingEngine
 
 AI-powered routing system that intelligently selects routes and steps based on conversation context.
@@ -725,7 +774,8 @@ interface RouteOptions<TContext = unknown, TData = unknown> {
   description?: string;
   identity?: Template<TContext, TData>;
   personality?: Template<TContext, TData>;
-  conditions?: Template<TContext, TData>[];
+  when?: ConditionTemplate<TContext, TData>;
+  skipIf?: ConditionTemplate<TContext, TData>;
   rules?: Template<TContext, TData>[];
   prohibitions?: Template<TContext, TData>[];
   
@@ -767,6 +817,31 @@ interface StepOptions<TContext = unknown, TData = unknown> {
   tools?: (string | Tool<TContext, unknown[], unknown, TData>)[];
 }
 
+interface StepResult<TContext = unknown, TData = unknown> extends StepRef {
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  branch: (branches: BranchSpec<TContext, TData>[]) => BranchResult<TContext, TData>;
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
+}
+
+interface BranchResult<TContext = unknown, TData = unknown> {
+  [branchName: string]: StepResult<TContext, TData>;
+}
+
+interface BranchSpec<TContext = unknown, TData = unknown> {
+  name: string;
+  id?: string;
+  step: StepOptions<TContext, TData>;
+}
+
+interface StepRef {
+  id: string;
+  routeId: string;
+}
+
+interface RouteRef {
+  id: string;
+}
+
 // ==============================================================================
 // LIFECYCLE HOOKS: prepare & finalize
 // ==============================================================================
@@ -847,6 +922,130 @@ interface SessionData {
 }
 ```
 
+### Batch Execution Types
+
+Types for multi-step batch execution:
+
+```typescript
+/**
+ * Reason why batch execution stopped
+ */
+type StoppedReason =
+  | 'needs_input'      // Step requires uncollected data
+  | 'end_route'        // Reached END_ROUTE
+  | 'route_complete'   // All Steps processed
+  | 'prepare_error'    // Error in prepare hook
+  | 'llm_error'        // Error during LLM call
+  | 'validation_error' // Error validating collected data
+  | 'finalize_error';  // Error in finalize hook (non-fatal)
+
+/**
+ * Result of batch determination - which steps can execute together
+ */
+interface BatchResult<TContext = unknown, TData = unknown> {
+  /** Steps included in this batch */
+  steps: StepOptions<TContext, TData>[];
+  /** Why the batch stopped */
+  stoppedReason: StoppedReason;
+  /** The Step that caused the stop (if applicable) */
+  stoppedAtStep?: StepOptions<TContext, TData>;
+}
+
+/**
+ * Result of executing a batch of steps
+ */
+interface BatchExecutionResult<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session: SessionState<TData>;
+  /** Steps that were executed */
+  executedSteps: StepRef[];
+  /** Why execution stopped */
+  stoppedReason: StoppedReason;
+  /** Collected data from the batch */
+  collectedData?: Partial<TData>;
+  /** Any errors that occurred */
+  error?: BatchExecutionError;
+}
+
+/**
+ * Error details for batch execution failures
+ */
+interface BatchExecutionError {
+  /** Type of error that occurred */
+  type: 'pre_extraction' | 'skipif_evaluation' | 'prepare_hook' | 
+        'llm_call' | 'data_validation' | 'finalize_hook';
+  /** Error message */
+  message: string;
+  /** Step where error occurred (if applicable) */
+  stepId?: string;
+  /** Additional error details */
+  details?: unknown;
+}
+
+/**
+ * Event emitted during batch execution for debugging
+ */
+interface BatchExecutionEvent {
+  /** Type of batch execution event */
+  type: 'batch_start' | 'step_included' | 'step_skipped' | 'batch_stop' | 'batch_complete';
+  /** Timestamp when the event occurred */
+  timestamp: Date;
+  /** Event-specific details */
+  details: {
+    stepId?: string;
+    reason?: string;
+    batchSize?: number;
+    stoppedReason?: StoppedReason;
+    timing?: BatchExecutionTiming;
+  };
+}
+
+/**
+ * Timing information for batch execution phases
+ */
+interface BatchExecutionTiming {
+  /** Total batch execution time in milliseconds */
+  totalMs: number;
+  /** Time spent in batch determination phase */
+  determinationMs?: number;
+  /** Time spent executing prepare hooks */
+  prepareHooksMs?: number;
+  /** Time spent in LLM call */
+  llmCallMs?: number;
+  /** Time spent collecting data */
+  dataCollectionMs?: number;
+  /** Time spent executing finalize hooks */
+  finalizeHooksMs?: number;
+}
+```
+
+### Enhanced AgentResponse
+
+The AgentResponse interface includes batch execution fields:
+
+```typescript
+interface AgentResponse<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session?: SessionState<TData>;
+  /** Tool calls made during response */
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  /** Whether the route is complete */
+  isRouteComplete?: boolean;
+  
+  // Multi-step execution fields
+  /** Steps executed in this response */
+  executedSteps?: StepRef[];
+  /** Why execution stopped */
+  stoppedReason?: StoppedReason;
+  /** Error information if execution failed */
+  error?: BatchExecutionError;
+}
+```
+
 ### Tool Types
 
 ```typescript