@falai/agent 0.1.0-alpha2 → 0.1.0-alpha3

package/src/index.ts

@@ -19,6 +19,8 @@ export { adaptEvent, convertHistoryToEvents } from "./core/Events";
 export { PersistenceManager } from "./core/PersistenceManager";
 export { SessionManager } from "./core/SessionManager";
 export { ToolManager, ToolCreationError, ToolExecutionError } from "./core/ToolManager";
+export { BatchExecutor, needsInput, type NeedsInputStep, type DetermineBatchParams } from "./core/BatchExecutor";
+export { BatchPromptBuilder, type BuildBatchPromptParams, type BatchPromptResult } from "./core/BatchPromptBuilder";
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider";

package/src/types/agent.ts

@@ -4,7 +4,7 @@
 
 import type { AgentStructuredResponse, AiProvider } from "./ai";
 import type { Tool } from "./tool";
-import type { RouteOptions } from "./route";
+import type { RouteOptions, StepRef, StoppedReason } from "./route";
 import type { PersistenceConfig } from "./persistence";
 import type { SessionState } from "./session";
 import type { StructuredSchema } from "./schema";
@@ -157,6 +157,10 @@ export interface AgentResponse<TData = Record<string, unknown>> {
   session?: SessionState<TData>;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   isRouteComplete?: boolean;
+  /** Steps executed in this response (for multi-step execution) */
+  executedSteps?: StepRef[];
+  /** Why execution stopped (for multi-step execution) */
+  stoppedReason?: StoppedReason;
 }
 
 export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
@@ -166,6 +170,10 @@ export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
   session?: SessionState<TData>;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   isRouteComplete?: boolean;
+  /** Steps executed in this response (for multi-step execution) */
+  executedSteps?: StepRef[];
+  /** Why execution stopped (for multi-step execution) */
+  stoppedReason?: StoppedReason;
   metadata?: {
     model?: string;
     tokensUsed?: number;

package/src/types/route.ts

@@ -7,6 +7,77 @@ import type { StructuredSchema } from "./schema";
 import type { Guideline, Term } from "./agent";
 import { Template, ConditionTemplate } from "./template";
 
+/**
+ * Reason why batch execution stopped
+ * 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)
+
+/**
+ * Event types for batch execution observability
+ */
+export type BatchExecutionEventType = 
+  | 'batch_start' 
+  | 'step_included' 
+  | 'step_skipped' 
+  | 'batch_stop' 
+  | 'batch_complete';
+
+/**
+ * Event emitted during batch execution for debugging and observability
+ * 
+ * **Validates: Requirements 11.3**
+ */
+export interface BatchExecutionEvent {
+  /** Type of batch execution event */
+  type: BatchExecutionEventType;
+  /** Timestamp when the event occurred */
+  timestamp: Date;
+  /** Event-specific details */
+  details: {
+    /** Step ID related to this event (for step_included, step_skipped) */
+    stepId?: string;
+    /** Reason for the event (e.g., why step was skipped or batch stopped) */
+    reason?: string;
+    /** Current batch size (for batch_start, batch_complete) */
+    batchSize?: number;
+    /** Stopped reason (for batch_stop, batch_complete) */
+    stoppedReason?: StoppedReason;
+    /** Phase timing information (for batch_complete) */
+    timing?: BatchExecutionTiming;
+  };
+}
+
+/**
+ * Timing information for batch execution phases
+ */
+export 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;
+}
+
+/**
+ * Callback type for batch execution event listeners
+ */
+export type BatchExecutionEventListener = (event: BatchExecutionEvent) => void;
+
 /**
  * Reference to a route
  */
@@ -25,6 +96,54 @@ export interface StepRef {
   routeId: string;
 }
 
+/**
+ * Result of batch determination - which steps can execute together
+ * @template TContext - Type of context data
+ * @template TData - Type of collected data
+ */
+export 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>;
+}
+
+/**
+ * Error details for batch execution failures
+ */
+export 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;
+}
+
+/**
+ * Result of executing a batch of steps
+ * @template TData - Type of collected data
+ */
+export interface BatchExecutionResult<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session: import('./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;
+}
+
 /**
  * Route lifecycle hooks for managing route-specific data and behavior
  */