@falai/agent 0.9.2 → 1.0.0

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

@@ -12,6 +12,138 @@ Step transitions handle:
 - **Route Completion**: Detect when routes reach their end
 - **Loop Prevention**: Avoid infinite traversal in complex flows
 
+## Stopping Conditions in Batch Execution
+
+When executing multiple steps in a batch, the engine stops for specific reasons indicated by the `stoppedReason` field in the response.
+
+### StoppedReason Values
+
+| Reason | Description | Behavior |
+|--------|-------------|----------|
+| `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 |
+| `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 |
+| `finalize_error` | Error in finalize hook | Non-fatal, logged and execution continues |
+
+### Needs-Input Stopping
+
+The most common stopping condition. A step needs input when:
+
+```typescript
+// Step needs input if requires fields are missing
+const step1 = {
+  prompt: "Confirm your booking",
+  requires: ["hotel", "date"], // Both must be present
+};
+
+// Step needs input if collecting and no collect fields have data
+const step2 = {
+  prompt: "What's your preference?",
+  collect: ["preference", "notes"], // Needs input if BOTH are missing
+};
+```
+
+### End-Route Stopping
+
+Batch stops when reaching the END_ROUTE marker:
+
+```typescript
+const finalStep = confirmStep.nextStep({
+  prompt: "Booking confirmed! Anything else?",
+}).endRoute(); // Creates END_ROUTE transition
+
+// Response will have:
+// stoppedReason: "end_route"
+// isRouteComplete: true
+```
+
+### Route-Complete Stopping
+
+When all steps have been processed without hitting END_ROUTE:
+
+```typescript
+// If the last step has no transitions and doesn't need input
+const response = await agent.respond("Complete my booking");
+
+// Response will have:
+// stoppedReason: "route_complete"
+// isRouteComplete: true
+```
+
+### Transitions Within Batched Execution
+
+During batch execution, transitions work as follows:
+
+1. **Linear transitions** - Steps connected via `nextStep()` are evaluated sequentially
+2. **SkipIf evaluation** - Each step's `skipIf` is checked before inclusion
+3. **Needs-input check** - If a step needs input, batch stops there
+4. **END_ROUTE detection** - Batch stops when reaching route end
+
+```typescript
+// Example: Steps A → B → C → END_ROUTE
+// If user provides data for A and B but not C:
+
+const response = await agent.respond("Data for A and B");
+
+// Batch includes: [A, B]
+// Stops at: C (needs_input)
+// Next call will continue from C
+```
+
+### Error Stopping Conditions
+
+Errors during batch execution have different behaviors:
+
+```typescript
+// Prepare hook error - stops immediately
+const stepWithPrepare = {
+  prompt: "Processing...",
+  prepare: async (context, data) => {
+    if (!data.valid) throw new Error("Invalid data");
+  },
+};
+// stoppedReason: "prepare_error"
+// Session state: last successful state preserved
+
+// LLM error - stops with preserved state
+// stoppedReason: "llm_error"
+// Session state: preserved from before LLM call
+
+// Validation error - continues but reports error
+// stoppedReason: "validation_error"
+// Collected data: partial data preserved
+
+// Finalize hook error - logged, continues
+// stoppedReason: original reason (not changed)
+// Error: included in response for logging
+```
+
+### Checking Stop Reason in Response
+
+```typescript
+const response = await agent.respond("Book a hotel");
+
+switch (response.stoppedReason) {
+  case 'needs_input':
+    console.log("Waiting for user input");
+    break;
+  case 'end_route':
+  case 'route_complete':
+    console.log("Route finished:", response.isRouteComplete);
+    break;
+  case 'prepare_error':
+  case 'llm_error':
+    console.error("Error occurred:", response.error);
+    break;
+  case 'validation_error':
+    console.warn("Validation issues:", response.error);
+    break;
+}
+```
+
 ## Conditional Skipping
 
 ### SkipIf Logic

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

@@ -145,6 +145,115 @@ 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.
+
+### How Steps Are Batched
+
+The execution engine walks through Steps sequentially and includes them in a batch until encountering a Step that needs user input:
+
+```typescript
+// Route with 3 steps
+const route = agent.createRoute({
+  title: "Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  initialStep: {
+    prompt: "Which hotel?",
+    collect: ["hotel"],
+    skipIf: (data) => !!data.hotel,
+  },
+});
+
+const askDate = route.initialStep.nextStep({
+  prompt: "What date?",
+  collect: ["date"],
+  skipIf: (data) => !!data.date,
+});
+
+const askGuests = askDate.nextStep({
+  prompt: "How many guests?",
+  collect: ["guests"],
+  skipIf: (data) => data.guests !== undefined,
+});
+```
+
+When a user says "Book Grand Hotel for 2 people on Friday":
+1. Pre-extraction captures: `{ hotel: "Grand Hotel", date: "Friday", guests: 2 }`
+2. All steps have their data satisfied (skipIf evaluates to true)
+3. Route completes in a single LLM call
+
+### The `requires` Field in Batch Context
+
+The `requires` field specifies data prerequisites that must be present before a Step can execute:
+
+```typescript
+const confirmStep = askGuests.nextStep({
+  prompt: "Confirm booking for {{guests}} guests at {{hotel}} on {{date}}?",
+  requires: ["hotel", "date", "guests"], // All must be present
+  collect: ["confirmed"],
+});
+```
+
+**Batch behavior:**
+- If any `requires` field is missing from session data (after pre-extraction), the Step **needs input**
+- The batch stops at this Step, and the LLM generates a response to collect the missing data
+
+### The `collect` Field in Batch Context
+
+The `collect` field specifies which data fields the Step should extract from the conversation:
+
+```typescript
+const contactStep = {
+  prompt: "What's your email and phone?",
+  collect: ["email", "phone"], // Extract both from response
+};
+```
+
+**Batch behavior:**
+- If a Step has `collect` fields and **none** of those fields have data in the session, the Step **needs input**
+- If **any** collect field already has data, the Step doesn't need input and can be included in the batch
+
+### SkipIf Evaluation During Batch Determination
+
+The `skipIf` condition is evaluated for each Step during batch determination:
+
+```typescript
+const premiumStep = {
+  prompt: "Would you like premium features?",
+  collect: ["wantsPremium"],
+  skipIf: (data) => data.userTier === "free", // Skip for free users
+};
+```
+
+**Evaluation rules:**
+1. If `skipIf` evaluates to `true` → Step is skipped, continue to next Step
+2. If `skipIf` evaluates to `false` → Step is evaluated for needs-input
+3. If `skipIf` throws an error → Step is treated as non-skippable (safer to execute than skip)
+
+### Batch Execution Example
+
+```typescript
+// User provides partial info
+const response1 = await agent.respond("I want to book the Grand Hotel");
+
+// Response shows which steps executed
+console.log(response1.executedSteps);
+// [{ id: "ask-hotel", routeId: "booking" }]
+
+console.log(response1.stoppedReason);
+// "needs_input" - stopped at ask-date step
+
+// User provides remaining info
+const response2 = await agent.respond("2 people on Friday");
+
+console.log(response2.executedSteps);
+// [{ id: "ask-date", routeId: "booking" }, { id: "ask-guests", routeId: "booking" }]
+
+console.log(response2.stoppedReason);
+// "route_complete"
+```
+
 ## Best Practices
 
 - Keep step prompts clear and focused
@@ -152,3 +261,6 @@ const dataStep = previousStep.nextStep({
 - Leverage schema validation for data integrity
 - Implement error handling in lifecycle hooks
 - Consider user experience in step sequencing
+- Design steps to maximize batching by using `skipIf` conditions
+- Use `requires` to enforce data dependencies between steps
+- Keep `collect` fields focused on what each step actually needs

package/docs/core/error-handling.md

@@ -11,6 +11,199 @@ The framework handles errors across multiple layers:
 - **Session Data Synchronization** - Consistent error handling for agent-session data operations
 - **Tool Execution Errors** - Graceful handling of tool failures
 - **Validation Errors** - Schema and data validation error recovery
+- **Batch Execution Errors** - Error handling during multi-step batch execution
+
+## Batch Execution Error Handling
+
+When executing multiple steps in a batch, errors are handled according to their category and severity.
+
+### Error Categories
+
+| Error Type | Severity | Behavior |
+|------------|----------|----------|
+| `pre_extraction` | Warning | Log warning, continue with empty extraction |
+| `skipif_evaluation` | Warning | Treat step as non-skippable, include in batch |
+| `prepare_hook` | Fatal | Stop batch execution, return error response |
+| `llm_call` | Fatal | Stop batch, preserve last successful session state |
+| `data_validation` | Non-fatal | Include errors in response, preserve partial data |
+| `finalize_hook` | Non-fatal | Log error, continue with remaining hooks |
+
+### Pre-Extraction Errors
+
+Failures during data extraction from user message:
+
+```typescript
+// Pre-extraction is an optimization; failure shouldn't block execution
+try {
+  const preExtracted = await preExtractData(message, route);
+  session = mergeCollected(session, preExtracted);
+} catch (error) {
+  // Log warning but continue
+  console.warn("Pre-extraction failed:", error.message);
+  // Continue with empty extraction result
+}
+```
+
+### SkipIf Evaluation Errors
+
+Exceptions thrown by skipIf conditions:
+
+```typescript
+// Safer to execute than skip when condition is indeterminate
+let shouldSkip = false;
+try {
+  shouldSkip = await step.evaluateSkipIf(context);
+} catch (error) {
+  console.warn(`skipIf error for step ${step.id}, treating as non-skippable`);
+  shouldSkip = false; // Include step in batch
+}
+```
+
+### Prepare Hook Errors
+
+Failures in step prepare hooks stop batch execution:
+
+```typescript
+const response = await agent.respond("Process my request");
+
+if (response.stoppedReason === 'prepare_error') {
+  console.error("Prepare hook failed:", response.error);
+  // {
+  //   type: 'prepare_hook',
+  //   message: 'Validation failed in prepare hook',
+  //   stepId: 'validate-step',
+  //   details: { ... }
+  // }
+  
+  // Session state is preserved from before the failed hook
+  console.log(response.session); // Last successful state
+}
+```
+
+### LLM Call Errors
+
+Provider failures, timeouts, and rate limits:
+
+```typescript
+const response = await agent.respond("Generate response");
+
+if (response.stoppedReason === 'llm_error') {
+  console.error("LLM call failed:", response.error);
+  // {
+  //   type: 'llm_call',
+  //   message: 'Rate limit exceeded',
+  //   details: { ... }
+  // }
+  
+  // Session preserved from before LLM call
+  // Can retry with same session
+}
+```
+
+### Data Validation Errors
+
+Schema validation failures for collected data:
+
+```typescript
+const response = await agent.respond("Book for 100 guests");
+
+if (response.stoppedReason === 'validation_error') {
+  console.warn("Validation failed:", response.error);
+  // {
+  //   type: 'data_validation',
+  //   message: 'Validation failed for 1 field(s): guests',
+  //   details: [
+  //     { field: 'guests', value: 100, message: 'Exceeds maximum of 10' }
+  //   ]
+  // }
+  
+  // Valid partial data is still preserved
+  console.log(response.session.data); // Contains valid fields
+}
+```
+
+### Finalize Hook Errors
+
+Failures in finalize hooks are logged but don't stop execution:
+
+```typescript
+// Finalize hooks are for cleanup; one failure shouldn't block others
+const response = await agent.respond("Complete booking");
+
+// Even if finalize hooks fail, response is returned
+// Errors are logged and included in response.error if present
+if (response.error?.type === 'finalize_hook') {
+  console.warn("Some finalize hooks failed:", response.error.details);
+}
+```
+
+### Partial Progress Preservation
+
+Errors preserve partial progress:
+
+```typescript
+// Batch: [step1, step2, step3]
+// step2's prepare hook fails
+
+const response = await agent.respond("Process all steps");
+
+// step1 completed successfully
+// step2 failed during prepare
+// step3 never executed
+
+console.log(response.executedSteps);
+// [{ id: "step1", routeId: "route" }]
+
+console.log(response.stoppedReason);
+// "prepare_error"
+
+// Session contains data from step1
+console.log(response.session.data);
+```
+
+### Error Response Structure
+
+```typescript
+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;
+}
+```
+
+### Handling Batch Errors
+
+```typescript
+const response = await agent.respond(message);
+
+// Check for errors
+if (response.error) {
+  switch (response.error.type) {
+    case 'prepare_hook':
+      // Fatal - batch stopped
+      await handlePrepareError(response.error);
+      break;
+    case 'llm_call':
+      // Fatal - can retry
+      await retryWithBackoff(() => agent.respond(message));
+      break;
+    case 'data_validation':
+      // Non-fatal - ask user to correct
+      await promptForCorrection(response.error.details);
+      break;
+    case 'finalize_hook':
+      // Non-fatal - log and continue
+      console.warn("Finalize error:", response.error);
+      break;
+  }
+}
+```
 
 ## Streaming Error Propagation
 

package/docs/core/routing/intelligent-routing.md

@@ -29,6 +29,124 @@ Within an active route, the routing engine:
 3. **AI Decision**: When multiple candidates exist, uses AI to select the optimal step
 4. **Handles Completion**: Detects route completion and manages transitions
 
+## Enhanced Condition System
+
+### ConditionTemplate for Routes and Steps
+
+The routing system now supports the powerful `ConditionTemplate` type for both route activation and step control:
+
+```typescript
+// Route with mixed condition types
+agent.createRoute({
+  title: "Premium Support",
+  when: [
+    "User needs premium or priority support", // AI context
+    (ctx) => ctx.context?.accountTier === 'premium' // Programmatic check
+  ],
+  skipIf: [
+    "Support system is under maintenance", // AI context
+    (ctx) => ctx.context?.maintenanceMode === true // Programmatic check
+  ],
+  steps: [
+    {
+      id: "priority_greeting",
+      when: "User should receive priority treatment", // AI context only
+      prompt: "Welcome to premium support! How can I assist you today?",
+      collect: ["issueType"]
+    },
+    {
+      id: "technical_help",
+      when: [
+        "User needs technical assistance", // AI context
+        (ctx) => ctx.data?.issueType === 'technical' // Programmatic check
+      ],
+      skipIf: (ctx) => ctx.data?.issueResolved === true, // Function-only skipIf
+      prompt: "Let me help you with your technical issue",
+      collect: ["issueDescription"]
+    }
+  ]
+});
+```
+
+### Condition Evaluation Logic
+
+**Route `when` conditions (AND logic):**
+- All function conditions must return `true`
+- String conditions provide AI context for route scoring
+- Arrays require all functions to pass
+
+**Route `skipIf` conditions (OR logic):**
+- Any function returning `true` excludes the route
+- String conditions provide AI context about exclusion reasons
+- Arrays skip if any function returns `true`
+
+**Step `when` conditions (AND logic):**
+- All function conditions must return `true` for step to be eligible
+- String conditions help AI understand step purpose
+- Arrays require all functions to pass
+
+**Step `skipIf` conditions (OR logic):**
+- Any function returning `true` skips the step
+- String conditions provide AI context about why step is skipped
+- Arrays skip if any function returns `true`
+
+### Hybrid Evaluation Process
+
+The routing engine now performs a two-phase evaluation:
+
+1. **Programmatic Phase**: Execute all function conditions for boolean results
+2. **AI Context Phase**: Include string conditions in AI prompts for intelligent decision-making
+
+```typescript
+// Example evaluation flow:
+const routeCondition = [
+  "User wants to upgrade their account", // → AI context
+  (ctx) => ctx.context?.accountTier !== 'enterprise' // → Must be true
+];
+
+// Programmatic: Check if user can upgrade (not already enterprise)
+// AI Context: "User wants to upgrade their account" helps AI understand intent
+// Result: Route eligible if function passes AND AI scores it highly
+```
+
+### Context-Aware Routing
+
+Conditions can access comprehensive context:
+
+```typescript
+interface RoutingContext {
+  userId: string;
+  accountTier: 'free' | 'premium' | 'enterprise';
+  supportHistory: SupportTicket[];
+  currentTime: Date;
+}
+
+interface AgentData {
+  customerName?: string;
+  issueType?: string;
+  priority?: 'low' | 'medium' | 'high';
+  previousAttempts?: number;
+}
+
+// Route with context-aware conditions
+agent.createRoute({
+  title: "Escalation Support",
+  when: [
+    "User needs escalated support or is frustrated", // AI context
+    (ctx) => ctx.data?.previousAttempts > 2, // Data check
+    (ctx) => ctx.context?.supportHistory.length > 5 // Context check
+  ],
+  skipIf: [
+    "Issue has been resolved recently", // AI context
+    (ctx) => {
+      const lastTicket = ctx.context?.supportHistory[0];
+      return lastTicket?.status === 'resolved' && 
+             (Date.now() - lastTicket.resolvedAt.getTime()) < 24 * 60 * 60 * 1000;
+    }
+  ]
+});
+```
+
 ## Key Features
 
 ### Intelligent Route Scoring