@falai/agent 1.0.2 → 1.1.1

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/SessionManager.ts

@@ -10,6 +10,7 @@ import type { History, HistoryItem } from "../types/history";
 import { PersistenceManager } from "./PersistenceManager";
 import type { PersistenceAdapter } from "../types/persistence";
 import type { Agent } from "./Agent";
+import { createSession } from "../utils";
 
 /**
  * SessionManager handles session lifecycle and conversation history
@@ -93,20 +94,10 @@ export class SessionManager<TData = unknown> {
    * Create a new session with optional custom ID
    */
   private async create(sessionId?: string): Promise<SessionState<TData>> {
-    const id =
-      sessionId ||
-      `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-
-    const session: SessionState<TData> = {
-      id,
-      data: {} as Partial<TData>, // Agent-level data structure
-      routeHistory: [],
+    const session = createSession<TData>({
+      id: sessionId,
       history: [], // Session manages its own history
-      metadata: {
-        createdAt: new Date(),
-        lastUpdatedAt: new Date(),
-      },
-    };
+    });
 
     this.currentSession = session;
 

package/src/index.ts

@@ -9,11 +9,11 @@ export { Agent } from "./core/Agent";
 export { Route } from "./core/Route";
 export { Step } from "./core/Step";
 export { ResponseModal } from "./core/ResponseModal";
-export type { 
-  ResponseModalOptions, 
-  RespondParams, 
-  StreamOptions, 
-  GenerateOptions 
+export type {
+  ResponseModalOptions,
+  RespondParams,
+  StreamOptions,
+  GenerateOptions
 } from "./core/ResponseModal";
 export { adaptEvent, convertHistoryToEvents } from "./core/Events";
 export { PersistenceManager } from "./core/PersistenceManager";
@@ -73,11 +73,11 @@ export { END_ROUTE, END_ROUTE_ID } from "./constants";
 // Utils
 export { generateRouteId, generateStepId, generateToolId } from "./utils/id";
 export { formatKnowledgeBase } from "./utils/template";
-export { 
-  ConditionEvaluator, 
-  createConditionEvaluator, 
-  extractAIContextStrings, 
-  hasProgrammaticConditions 
+export {
+  ConditionEvaluator,
+  createConditionEvaluator,
+  extractAIContextStrings,
+  hasProgrammaticConditions
 } from "./utils/condition";
 export {
   normalizeHistory,
@@ -163,4 +163,4 @@ export type {
   BatchExecutionError,
 } from "./types";
 export { CompositionMode, EventKind, MessageRole } from "./types";
-export { createSession, enterRoute, enterStep, mergeCollected } from "./utils";
+export { createSession, createSessionId, enterRoute, enterStep, mergeCollected } from "./utils";

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

package/src/utils/session.ts

@@ -4,19 +4,57 @@ import type { CollectedStateData } from "../types/persistence";
 
 /**
  * Helper to create a new session
+ *
+ * Overload 1: Create with optional sessionId and metadata
  * @param sessionId - Optional session ID (e.g., from database)
  * @param metadata - Optional metadata to attach
+ *
+ * Overload 2: Create from a partial session state (merged with defaults)
+ * @param state - Partial session state to merge with defaults
  */
 export function createSession<TData = Record<string, unknown>>(
   sessionId?: string,
   metadata?: SessionState<TData>["metadata"]
+): SessionState<TData>;
+export function createSession<TData = Record<string, unknown>>(
+  state: Partial<SessionState<TData>>
+): SessionState<TData>;
+export function createSession<TData = Record<string, unknown>>(
+  sessionIdOrState?: string | Partial<SessionState<TData>>,
+  metadata?: SessionState<TData>["metadata"]
 ): SessionState<TData> {
+  // Overload 2: partial state object
+  if (typeof sessionIdOrState === "object" && sessionIdOrState !== null) {
+    const state = sessionIdOrState;
+    const now = new Date();
+    const id =
+      state.id ||
+      `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+    return {
+      id,
+      data: state.data ?? ({} as Partial<TData>),
+      routeHistory: state.routeHistory ?? [],
+      currentRoute: state.currentRoute,
+      currentStep: state.currentStep,
+      pendingTransition: state.pendingTransition,
+      history: state.history,
+      metadata: {
+        createdAt: now,
+        lastUpdatedAt: now,
+        ...state.metadata,
+      },
+    };
+  }
+
+  // Overload 1: sessionId + metadata
   const id =
-    sessionId || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    sessionIdOrState ||
+    `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 
   return {
     id,
-    data: {} as Partial<TData>, // Agent-level data structure
+    data: {} as Partial<TData>,
     routeHistory: [],
     metadata: {
       ...metadata,
@@ -184,17 +222,17 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
     id: sessionId,
     currentRoute: data.currentRoute
       ? {
-          id: data.currentRoute,
-          title: collectedData.currentRouteTitle || data.currentRoute,
-          enteredAt: new Date(),
-        }
+        id: data.currentRoute,
+        title: collectedData.currentRouteTitle || data.currentRoute,
+        enteredAt: new Date(),
+      }
       : undefined,
     currentStep: data.currentStep
       ? {
-          id: data.currentStep,
-          description: collectedData.currentStepDescription || undefined,
-          enteredAt: new Date(),
-        }
+        id: data.currentStep,
+        description: collectedData.currentStepDescription || undefined,
+        enteredAt: new Date(),
+      }
       : undefined,
     data: collectedData.data || {},
     routeHistory: collectedData.routeHistory || [],