@falai/agent 1.0.1 → 1.1.0

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/docs/guides/migration/response-modal-refactor.md

@@ -513,6 +513,6 @@ The modern `stream()` API is the recommended approach for new streaming implemen
 ---
 
 **Need Help?** 
-- Check the [examples](../../examples/) directory for complete working examples
+- Check the [examples](../../../examples/) directory for complete working examples
 - Review the [API documentation](../../api/) for detailed method signatures
-- Look at the [streaming examples](../../examples/advanced-patterns/streaming-responses.ts) for side-by-side comparisons
+- Look at the [streaming examples](../../../examples/advanced-patterns/streaming-responses.ts) for side-by-side comparisons

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "1.0.1",
+  "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/Agent.ts

@@ -126,9 +126,7 @@ export class Agent<TContext = any, TData = any> {
 
     // Initialize routing engine
     this.routingEngine = new RoutingEngine<TContext, TData>({
-      maxCandidates: 5,
-      allowRouteSwitch: true,
-      switchThreshold: 70,
+      routeSwitchMargin: options.routeSwitchMargin,
     });
 
     // Initialize ResponseModal for handling all response generation

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/core/RoutingEngine.ts

@@ -2,7 +2,6 @@ import type {
   Event,
   AgentOptions,
   StructuredSchema,
-  RoutingDecision,
   SessionState,
   AiProvider,
   TemplateContext,
@@ -36,9 +35,12 @@ export interface RoutingDecisionOutput {
 }
 
 export interface RoutingEngineOptions {
-  allowRouteSwitch?: boolean;
-  switchThreshold?: number; // 0-100
-  maxCandidates?: number;
+  /**
+   * Score margin the best alternative route must exceed the current route's score
+   * by before the agent switches routes. Prevents flip-flopping on marginal differences.
+   * @default 15
+   */
+  routeSwitchMargin?: number;
 }
 
 export interface BuildStepSelectionPromptParams<
@@ -746,7 +748,8 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       const optimalRoute = this.selectOptimalRoute(
         eligibleRoutes,
         updatedSession.data || {},
-        routingResult.structured.routes
+        routingResult.structured.routes,
+        updatedSession.currentRoute?.id
       );
 
       // If no optimal route found, check why
@@ -908,42 +911,68 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
    * @returns Route that should be prioritized for continuation
    */
   selectOptimalRoute(
-    routes: Route<TContext, TData>[],
-    data: Partial<TData>,
-    routeScores: Record<string, number>
-  ): Route<TContext, TData> | undefined {
-    const completionStatus = this.getRouteCompletionStatus(routes, data);
-
-    // Create weighted scores combining AI intent scores with completion progress
-    const weightedScores: Array<{ route: Route<TContext, TData>; score: number }> = [];
+      routes: Route<TContext, TData>[],
+      data: Partial<TData>,
+      routeScores: Record<string, number>,
+      currentRouteId?: string
+    ): Route<TContext, TData> | undefined {
+      const completionStatus = this.getRouteCompletionStatus(routes, data);
+      const switchMargin = this.options?.routeSwitchMargin ?? 15;
+
+      // Create weighted scores combining AI intent scores with completion progress
+      const weightedScores: Array<{ route: Route<TContext, TData>; score: number }> = [];
+
+      for (const route of routes) {
+        const aiScore = routeScores[route.id] || 0;
+        const completionProgress = completionStatus.get(route.id) || 0;
+
+        // ALWAYS skip fully completed routes to prevent re-entering finished tasks
+        if (completionProgress >= 1.0) {
+          logger.debug(
+            `[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`
+          );
+          continue;
+        }
 
-    for (const route of routes) {
-      const aiScore = routeScores[route.id] || 0;
-      const completionProgress = completionStatus.get(route.id) || 0;
+        // Boost partially complete routes that match user intent
+        let weightedScore = aiScore;
+        if (completionProgress > 0 && completionProgress < 1.0) {
+          weightedScore += (completionProgress * 20); // Up to 20 point boost
+        }
 
-      // ALWAYS skip fully completed routes to prevent re-entering finished tasks
-      // Users should not be forced back into completed routes
-      if (completionProgress >= 1.0) {
-        logger.debug(
-          `[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`
-        );
-        continue;
+        weightedScores.push({ route, score: weightedScore });
       }
 
-      // Boost partially complete routes that match user intent
-      let weightedScore = aiScore;
-      if (completionProgress > 0 && completionProgress < 1.0) {
-        // Boost score for partially complete routes
-        weightedScore += (completionProgress * 20); // Up to 20 point boost
-      }
+      // Sort by weighted score descending
+      weightedScores.sort((a, b) => b.score - a.score);
 
-      weightedScores.push({ route, score: weightedScore });
-    }
+      if (weightedScores.length === 0) {
+        return undefined;
+      }
 
-    // Sort by weighted score and return the best option
-    weightedScores.sort((a, b) => b.score - a.score);
+      // Apply sticky routing: if there's a current route, only switch if the
+      // best alternative exceeds the current route's score by the configured margin
+      if (currentRouteId) {
+        const currentEntry = weightedScores.find(e => e.route.id === currentRouteId);
+        const bestEntry = weightedScores[0];
+
+        if (currentEntry && bestEntry.route.id !== currentRouteId) {
+          if (bestEntry.score < currentEntry.score + switchMargin) {
+            logger.debug(
+              `[RoutingEngine] Staying on current route: ${currentEntry.route.title} ` +
+              `(current: ${currentEntry.score}, best alternative: ${bestEntry.score}, ` +
+              `margin required: ${switchMargin})`
+            );
+            return currentEntry.route;
+          }
+          logger.debug(
+            `[RoutingEngine] Switching route: ${currentEntry.route.title} → ${bestEntry.route.title} ` +
+            `(current: ${currentEntry.score}, alternative: ${bestEntry.score}, ` +
+            `margin: ${switchMargin})`
+          );
+        }
+      }
 
-    if (weightedScores.length > 0) {
       logger.debug(
         `[RoutingEngine] Selected optimal route: ${weightedScores[0].route.title} ` +
         `(AI: ${routeScores[weightedScores[0].route.id]}, ` +
@@ -953,9 +982,6 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       return weightedScores[0].route;
     }
 
-    return undefined;
-  }
-
   /**
    * Build prompt for step selection within a single route
    * @private
@@ -1380,17 +1406,4 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     return pc.build();
   }
 
-  decideRouteFromScores(output: RoutingDecision): {
-    routeId: string;
-    maxScore: number;
-  } {
-    // Optionally limit candidates and apply switching threshold
-    const entries = Object.entries(output.routes).sort((a, b) => b[1] - a[1]);
-    const limited = this.options?.maxCandidates
-      ? entries.slice(0, this.options.maxCandidates)
-      : entries;
-    const [topId, topScore] = limited[0] || ["", 0];
-    // switchThreshold is enforced by caller when a current route exists
-    return { routeId: topId, maxScore: topScore };
-  }
 }

package/src/types/agent.ts

@@ -114,6 +114,24 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
   schema?: StructuredSchema;
   /** Initial data to pre-populate when creating the agent */
   initialData?: Partial<TData>;
+  /**
+   * Margin (0-100) the best alternative route must exceed the current route's score
+   * by before the agent switches. Higher values make the agent "stickier" to the
+   * current route. Set to 0 to switch whenever any route scores higher.
+   * @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

package/src/types/routing.ts

@@ -8,11 +8,6 @@ export interface RoutingDecision {
   contextUpdate?: Record<string, unknown>;
 }
 
-export interface RoutingDecisionWithRoute extends RoutingDecision {
-  selectedRouteId: string;
-  maxScore: number;
-}
-
 export interface RoutingSchemaOptions {
   extrasSchema?: StructuredSchema;
 }