@falai/agent 1.0.2 → 1.1.0

package/docs/api/overview.md

@@ -761,6 +761,9 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
   rules?: Template<TContext, TData>[];
   prohibitions?: Template<TContext, TData>[];
   
+  // NEW: Control multi-step batching
+  maxStepsPerBatch?: number; // Default: 1 (single-step). Set higher or Infinity to batch.
+  
   hooks?: ContextLifecycleHooks<TContext, TData>;
   debug?: boolean;
   session?: SessionState;
@@ -935,13 +938,14 @@ Types for multi-step batch execution:
  * 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)
+  | 'needs_input'        // Step requires uncollected data
+  | 'end_route'          // Reached END_ROUTE
+  | 'route_complete'     // All Steps processed
+  | 'max_steps_reached'  // Batch hit the maxStepsPerBatch limit
+  | '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

package/docs/architecture/multi-step-execution.md

@@ -6,6 +6,28 @@
 
 The core insight is simple: **if a Step's data requirements are already satisfied, there's no reason to pause and wait for user input**. By detecting which Steps can execute together and combining them into a single batch, we reduce LLM calls while improving conversation UX.
 
+> **Note:** Multi-step batching is **opt-in**. By default, `maxStepsPerBatch` is `1`, meaning steps execute one at a time (classic behavior). Set `maxStepsPerBatch` to a higher value or `Infinity` to enable batching.
+
+## Configuration
+
+Control batching behavior with the `maxStepsPerBatch` option on the agent:
+
+```typescript
+const agent = new Agent({
+  name: "Assistant",
+  provider: provider,
+  // Default: 1 (single-step execution)
+  // Set higher to enable batching
+  maxStepsPerBatch: Infinity, // No limit — batch all eligible steps
+});
+```
+
+| Value | Behavior |
+|-------|----------|
+| `1` (default) | Steps execute one at a time |
+| `N` (e.g. `3`) | Up to N steps per batch |
+| `Infinity` | No limit — all eligible steps batch together |
+
 ## Design Priorities
 
 1. **Conversation UX** - Reduce unnecessary back-and-forth
@@ -23,7 +45,9 @@ flowchart TD
     D -->|Yes| E[Evaluate Step]
     E --> F{Needs Input?}
     F -->|No| G[Add to Batch]
-    G --> D
+    G --> G2{maxStepsPerBatch reached?}
+    G2 -->|No| D
+    G2 -->|Yes| H[Stop Batch]
     F -->|Yes| H[Stop Batch]
     D -->|No| H
     H --> I[Execute Prepare Hooks]
@@ -67,8 +91,10 @@ For each Step starting from current position:
   c. If skipIf is true → skip Step, continue to next
   d. If skipIf throws error → treat as non-skippable
   e. Evaluate needsInput(step, sessionDataAfterPreExtraction)
-  f. If needsInput is false → include Step in batch, continue to next
+  f. If needsInput is false → include Step in batch
   g. If needsInput is true → stop with 'needs_input'
+  h. Check if batch size reached maxStepsPerBatch → stop with 'max_steps_reached'
+  i. Continue to next Step
 ```
 
 ### Phase 3: Hook Execution (Prepare)
@@ -170,6 +196,13 @@ Combines multiple Step prompts into a single coherent prompt:
 ## Example: Multi-Step Batch
 
 ```typescript
+// Enable batching to process multiple steps at once
+const agent = new Agent({
+  name: "Booking Agent",
+  provider: provider,
+  maxStepsPerBatch: Infinity, // Enable full batching
+});
+
 // User provides all booking info at once
 const response = await agent.respond(
   "I want to book the Grand Hotel for 2 people next Friday"
@@ -202,7 +235,8 @@ Enable debug mode to see batch execution decisions:
 const agent = new Agent({
   name: "Assistant",
   provider: provider,
-  debug: true  // Enable detailed logging
+  debug: true,             // Enable detailed logging
+  maxStepsPerBatch: 5,     // Allow up to 5 steps per batch
 });
 ```
 

package/docs/core/conversation-flows/data-collection.md

@@ -17,7 +17,7 @@ The agent-level data collection system provides:
 
 ## Data Collection Across Batched Steps
 
-When multiple steps execute in a single batch, data collection works across all steps simultaneously.
+When multiple steps execute in a single batch (requires `maxStepsPerBatch` > 1), data collection works across all steps simultaneously.
 
 ### How Batch Data Collection Works
 

package/docs/core/conversation-flows/step-transitions.md

@@ -23,6 +23,7 @@ When executing multiple steps in a batch, the engine stops for specific reasons
 | `needs_input` | Step requires data not yet available | Batch stops, LLM generates response to collect data |
 | `end_route` | Reached END_ROUTE marker | Route is complete, no more steps to execute |
 | `route_complete` | All steps in route processed | Route finished successfully |
+| `max_steps_reached` | Batch hit the `maxStepsPerBatch` limit | Batch stops, remaining steps execute in subsequent calls |
 | `prepare_error` | Error in prepare hook | Batch stops, error returned with last successful state |
 | `llm_error` | Error during LLM call | Batch stops, session state preserved |
 | `validation_error` | Data validation failed | Batch continues, errors included in response |
@@ -130,6 +131,9 @@ switch (response.stoppedReason) {
   case 'needs_input':
     console.log("Waiting for user input");
     break;
+  case 'max_steps_reached':
+    console.log("Batch limit reached, more steps pending");
+    break;
   case 'end_route':
   case 'route_complete':
     console.log("Route finished:", response.isRouteComplete);

package/docs/core/conversation-flows/steps.md

@@ -147,7 +147,9 @@ const dataStep = previousStep.nextStep({
 
 ## Multi-Step Batch Execution
 
-Steps can execute together in a single LLM call when their data requirements are already satisfied. This reduces unnecessary back-and-forth and minimizes LLM costs.
+Steps can execute together in a single LLM call when their data requirements are already satisfied and `maxStepsPerBatch` is set higher than `1`. This reduces unnecessary back-and-forth and minimizes LLM costs.
+
+> **Note:** By default, `maxStepsPerBatch` is `1` (single-step execution). Set it to a higher value or `Infinity` on the agent to enable batching.
 
 ### How Steps Are Batched
 

package/docs/guides/migration/README.md

@@ -6,6 +6,8 @@ This directory contains migration guides for major changes and updates to the `@
 
 ### [Multi-Step Execution Migration Guide](./multi-step-execution.md)
 
+**v1.1.0 - Breaking Change** - `maxStepsPerBatch` now defaults to `1` (single-step execution). Set `maxStepsPerBatch: Infinity` to restore v1.0.x batching behavior.
+
 **v1.0.0 - Major Release** - Guide for understanding and migrating to multi-step batch execution.
 
 **Breaking Changes:**

package/docs/guides/migration/multi-step-execution.md

@@ -103,9 +103,14 @@ const response3 = await agent.respond("2 people");
 
 ### After: Multi-Step Execution
 
-Now, multiple steps can execute in a single call when data requirements are satisfied:
+Now, multiple steps can execute in a single call when data requirements are satisfied and `maxStepsPerBatch` is set higher than `1`:
 
 ```typescript
+const agent = new Agent({
+  // ...
+  maxStepsPerBatch: Infinity, // Enable batching
+});
+
 // Turn 1
 const response = await agent.respond("Book Grand Hotel for 2 on Friday");
 // Pre-extraction captures: { hotel: "Grand Hotel", date: "Friday", guests: 2 }
@@ -115,6 +120,8 @@ const response = await agent.respond("Book Grand Hotel for 2 on Friday");
 // Total: 1 LLM call
 ```
 
+> **Note:** By default, `maxStepsPerBatch` is `1`, which preserves the classic single-step behavior. You must explicitly opt in to batching.
+
 ## What Changed
 
 | Aspect | Before | After |
@@ -326,9 +333,20 @@ const step2 = { skipIf: (d) => !!d.email }; // Skipped if email exists
 // - Both steps skipped, route may complete immediately
 ```
 
-## Opting Out of Batching
+## Controlling Batching with `maxStepsPerBatch`
+
+As of v1.1.0, batching is **off by default** (`maxStepsPerBatch: 1`). To enable multi-step batching, set the option on your agent:
+
+```typescript
+const agent = new Agent({
+  name: "Assistant",
+  provider: provider,
+  maxStepsPerBatch: Infinity, // Batch all eligible steps (v1.0.x behavior)
+  // maxStepsPerBatch: 3,     // Or cap at 3 steps per batch
+});
+```
 
-If you need single-step behavior for specific steps, use `requires` to create dependencies:
+If you need single-step behavior for specific steps while batching is enabled, use `requires` to create dependencies:
 
 ```typescript
 // Force step2 to wait for step1's data
@@ -363,11 +381,13 @@ const agent = new Agent({
 
 ## Summary
 
-1. **Multiple steps can now execute together** - reducing LLM calls
-2. **Pre-extraction happens before batch determination** - maximizing batching
-3. **New response fields** - `executedSteps`, `stoppedReason`, `error`
-4. **Hook execution order changed** - all prepare, then LLM, then all finalize
-5. **SkipIf affects batching** - evaluated during batch determination
-6. **Partial progress preserved** - on errors, completed steps are retained
+1. **`maxStepsPerBatch` defaults to `1`** - single-step execution by default (v1.1.0 breaking change)
+2. **Set `maxStepsPerBatch: Infinity`** to restore v1.0.x batching behavior
+3. **Multiple steps can execute together** when batching is enabled, reducing LLM calls
+4. **Pre-extraction happens before batch determination** - maximizing batching
+5. **New response fields** - `executedSteps`, `stoppedReason`, `error`
+6. **Hook execution order changed** - all prepare, then LLM, then all finalize
+7. **SkipIf affects batching** - evaluated during batch determination
+8. **Partial progress preserved** - on errors, completed steps are retained
 
 The changes improve efficiency and UX while maintaining API compatibility. Most existing code will work without changes, but reviewing hook dependencies and test expectations is recommended.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/BatchExecutor.ts

@@ -108,6 +108,12 @@ export interface DetermineBatchParams<TContext, TData> {
   sessionData: Partial<TData>;
   /** Agent context for condition evaluation */
   context: TContext;
+  /**
+   * Maximum number of steps to include in this batch.
+   * When reached, the batch stops with 'max_steps_reached'.
+   * Defaults to 1 (single-step execution).
+   */
+  maxSteps?: number;
 }
 
 /**
@@ -222,7 +228,7 @@ export class BatchExecutor<TContext = unknown, TData = unknown> {
    * **Validates: Requirements 1.1, 1.4, 1.5, 7.1, 7.2, 7.3**
    */
   async determineBatch(params: DetermineBatchParams<TContext, TData>): Promise<BatchResult<TContext, TData>> {
-    const { route, currentStep, sessionData, context } = params;
+    const { route, currentStep, sessionData, context, maxSteps = 1 } = params;
     const startTime = Date.now();
     
     const batchSteps: StepOptions<TContext, TData>[] = [];
@@ -361,6 +367,21 @@ export class BatchExecutor<TContext = unknown, TData = unknown> {
         batchSize: batchSteps.length,
       });
       
+      // Check if we've reached the max steps limit
+      if (batchSteps.length >= maxSteps) {
+        stoppedReason = 'max_steps_reached';
+        
+        logger.debug(`[BatchExecutor] Reached maxStepsPerBatch limit (${maxSteps}), stopping batch`);
+        
+        this.emitBatchEvent('batch_stop', {
+          stepId: step.id,
+          reason: `Reached maxStepsPerBatch limit (${maxSteps})`,
+          stoppedReason: 'max_steps_reached',
+          batchSize: batchSteps.length,
+        });
+        break;
+      }
+      
       // Move to next step in the sequence
       const transitions = step.getTransitions();
       if (transitions.length === 0) {

package/src/core/ResponseModal.ts

@@ -575,6 +575,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     currentStep,
                     sessionData: updatedSession.data || {},
                     context: params.context,
+                    maxSteps: this.agent.getAgentOptions().maxStepsPerBatch,
                 });
 
                 batchSteps = batchResult.steps;

package/src/types/agent.ts

@@ -121,6 +121,17 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
    * @default 15
    */
   routeSwitchMargin?: number;
+  /**
+   * Maximum number of steps to execute in a single batch.
+   * Controls how many consecutive steps can run together in one LLM call.
+   *
+   * - `1` (default): Steps execute one at a time (classic behavior)
+   * - `Infinity`: No limit — all eligible steps batch together
+   * - Any positive integer: Cap the batch to that many steps
+   *
+   * @default 1
+   */
+  maxStepsPerBatch?: number;
 }
 
 /**

package/src/types/route.ts

@@ -12,13 +12,14 @@ import { Template, ConditionTemplate } from "./template";
  * Used to indicate the stopping condition for multi-step execution
  */
 export 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, logged)
+  | 'needs_input'        // Step requires uncollected data
+  | 'end_route'          // Reached END_ROUTE
+  | 'route_complete'     // All Steps processed
+  | 'max_steps_reached'  // Batch hit the maxStepsPerBatch limit
+  | '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, logged)
 
 /**
  * Event types for batch execution observability