@falai/agent 1.0.0 → 1.0.2

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

@@ -2,6 +2,76 @@
 
 This guide covers the behavioral changes from single-step to multi-step execution and provides migration guidance for existing routes.
 
+## Breaking Changes in v1.0.0
+
+### History API Simplified
+
+The `createMessageEvent` and `EventSource` exports have been replaced with simpler helper functions:
+
+**Before (v0.x):**
+```typescript
+import { createMessageEvent, EventSource } from "@falai/agent";
+
+const history = [
+  createMessageEvent(EventSource.CUSTOMER, "Hello"),
+  createMessageEvent(EventSource.AI_AGENT, "Hi there!"),
+];
+```
+
+**After (v1.0.0):**
+```typescript
+import { userMessage, assistantMessage } from "@falai/agent";
+
+const history = [
+  userMessage("Hello"),
+  assistantMessage("Hi there!"),
+];
+```
+
+The history is now a simple array of objects with `role` and `content` properties:
+
+```typescript
+// Available helper functions
+import { 
+  userMessage,      // (content, name?) => { role: "user", content, name? }
+  assistantMessage, // (content, toolCalls?) => { role: "assistant", content, tool_calls? }
+  toolMessage,      // (toolCallId, name, content) => { role: "tool", ... }
+  systemMessage,    // (content) => { role: "system", content }
+} from "@falai/agent";
+
+// Or create history items directly
+const history = [
+  { role: "user", content: "Hello" },
+  { role: "assistant", content: "Hi there!" },
+];
+```
+
+### StepOptions: `instructions` → `prompt`
+
+The `instructions` property in `StepOptions` has been renamed to `prompt`:
+
+**Before:**
+```typescript
+steps: [
+  {
+    id: "greeting",
+    instructions: "Greet the user warmly",
+  }
+]
+```
+
+**After:**
+```typescript
+steps: [
+  {
+    id: "greeting",
+    prompt: "Greet the user warmly",
+  }
+]
+```
+
+---
+
 ## Overview
 
 Multi-step execution is a **major behavioral change** that allows multiple consecutive steps to execute in a single LLM call. While the public API shape remains compatible, the execution semantics differ from the previous single-step model.

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.0",
+  "version": "1.0.2",
   "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

@@ -67,6 +67,8 @@ export class Agent<TContext = any, TData = any> {
   private guidelines: Guideline<TContext, TData>[] = [];
   private tools: Tool<TContext, TData>[] = [];
   private routes: Route<TContext, TData>[] = [];
+  private agentRules: Template<TContext, TData>[] = [];
+  private agentProhibitions: Template<TContext, TData>[] = [];
   private context: TContext | undefined;
   private persistenceManager: PersistenceManager<TData> | undefined;
   private routingEngine: RoutingEngine<TContext, TData>;
@@ -124,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
@@ -185,6 +185,14 @@ export class Agent<TContext = any, TData = any> {
       });
     }
 
+    // Initialize agent-level rules and prohibitions
+    if (options.rules) {
+      this.agentRules = [...options.rules];
+    }
+    if (options.prohibitions) {
+      this.agentProhibitions = [...options.prohibitions];
+    }
+
     if (options.routes) {
       options.routes.forEach((routeOptions) => {
         this.createRoute(routeOptions);
@@ -677,6 +685,20 @@ export class Agent<TContext = any, TData = any> {
     return [...this.guidelines];
   }
 
+  /**
+   * Get agent-level rules
+   */
+  getRules(): Template<TContext, TData>[] {
+    return [...this.agentRules];
+  }
+
+  /**
+   * Get agent-level prohibitions
+   */
+  getProhibitions(): Template<TContext, TData>[] {
+    return [...this.agentProhibitions];
+  }
+
   /**
    * Evaluate and match active guidelines based on their conditions
    * Returns guidelines that should be active given the current context

package/src/core/BatchExecutor.ts

@@ -326,6 +326,16 @@ export class BatchExecutor<TContext = unknown, TData = unknown> {
           field => (sessionData as Record<string, unknown>)[String(field)] === undefined
         ) || [];
         const collectFields = step.collect || [];
+
+        // Warn about missing required fields from previous steps
+        if (missingRequires.length > 0) {
+          const warning = `[Agent] Step "${step.description || step.id}" requires data [${missingRequires.join(', ')}] that was not collected by previous steps. ` +
+            `Ensure earlier steps collect these fields before this step can proceed.`;
+          logger.warn(warning);
+          // Also log to console for developer visibility
+          console.warn(warning);
+        }
+
         logger.debug(`[BatchExecutor] Step ${step.id} needs input, stopping batch. Missing requires: [${missingRequires.join(', ')}], Collect fields: [${collectFields.join(', ')}]`);
         
         // Emit batch_stop event (Requirement 11.3)

package/src/core/BatchPromptBuilder.ts

@@ -12,7 +12,7 @@ import type { AgentOptions } from '../types/agent';
 import type { SessionState } from '../types/session';
 import type { Event } from '../types/history';
 import type { Route } from './Route';
-import { render, createTemplateContext } from '../utils/template';
+import { render, renderMany, createTemplateContext } from '../utils/template';
 import { PromptComposer } from './PromptComposer';
 
 /**
@@ -120,6 +120,24 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
     const allGuidelines = [...(agentOptions.guidelines || []), ...route.getGuidelines()];
     await composer.addGuidelines(allGuidelines);
     
+    // Add combined rules (agent + route)
+    const allRules = [...(agentOptions.rules || []), ...route.getRules()];
+    if (allRules.length > 0) {
+      const renderedRules = await renderMany(allRules, templateContext);
+      if (renderedRules.length > 0) {
+        await composer.addInstruction(`Rules:\n- ${renderedRules.join('\n- ')}`);
+      }
+    }
+    
+    // Add combined prohibitions (agent + route)
+    const allProhibitions = [...(agentOptions.prohibitions || []), ...route.getProhibitions()];
+    if (allProhibitions.length > 0) {
+      const renderedProhibitions = await renderMany(allProhibitions, templateContext);
+      if (renderedProhibitions.length > 0) {
+        await composer.addInstruction(`Prohibitions:\n- ${renderedProhibitions.join('\n- ')}`);
+      }
+    }
+    
     // Add interaction history
     await composer.addInteractionHistory(history, 'Recent conversation context:');
     

package/src/core/ResponseEngine.ts

@@ -44,36 +44,47 @@ export interface BuildFallbackPromptParams<TContext = unknown, TData = unknown>
 
 export class ResponseEngine<TContext = unknown, TData = unknown> {
   responseSchemaForRoute(
-    route: Route<TContext, TData>,
-    currentStep?: Step<TContext, TData>,
-    agentSchema?: StructuredSchema
-  ): StructuredSchema {
-    const base: StructuredSchema = {
-      type: "object",
-      properties: {
-        message: { type: "string", description: "Final user-facing message" },
-      },
-      required: ["message"],
-      additionalProperties: false,
-    };
+      route: Route<TContext, TData>,
+      currentStep?: Step<TContext, TData>,
+      agentSchema?: StructuredSchema
+    ): StructuredSchema {
+      const base: StructuredSchema = {
+        type: "object",
+        properties: {
+          message: { type: "string", description: "Final user-facing message" },
+        },
+        required: ["message"],
+        additionalProperties: false,
+      };
 
-    // Add data field only if route has responseOutputSchema
-    if (route.responseOutputSchema) {
-      base.properties!.data = route.responseOutputSchema;
-    }
+      // Add data field only if route has responseOutputSchema
+      if (route.responseOutputSchema) {
+        base.properties!.data = route.responseOutputSchema;
+      }
 
-    // Add collect fields from current step using agent-level schema
-    if (currentStep?.collect && agentSchema?.properties) {
-      for (const field of currentStep.collect) {
-        const fieldSchema = agentSchema.properties[field as string];
-        if (fieldSchema) {
-          base.properties![field as string] = fieldSchema;
+      // Add collect fields from current step
+      if (currentStep?.collect) {
+        if (agentSchema?.properties) {
+          // Use agent schema definitions for collect fields
+          for (const field of currentStep.collect) {
+            const fieldSchema = agentSchema.properties[field as string];
+            if (fieldSchema) {
+              base.properties![field as string] = fieldSchema;
+            }
+          }
+        } else {
+          // No agent schema - generate dynamic schema from collect fields
+          for (const field of currentStep.collect) {
+            base.properties![field as string] = {
+              type: "string",
+              description: `Collected value for ${String(field)}`,
+            };
+          }
         }
       }
-    }
 
-    return base;
-  }
+      return base;
+    }
 
   async buildResponsePrompt(
     params: BuildResponsePromptParams<TContext, TData>
@@ -146,30 +157,25 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
     await pc.addLastMessage(lastMessage);
     
     // Add data collection instructions - include ALL route fields, not just current step
-    if (agentSchema?.properties) {
-      // Collect all fields from route's required and optional fields
-      const allRouteFields = new Set<string>();
-      
-      // Add route required fields
-      if (route.requiredFields) {
-        route.requiredFields.forEach(field => allRouteFields.add(String(field)));
-      }
-      
-      // Add route optional fields
-      if (route.optionalFields) {
-        route.optionalFields.forEach(field => allRouteFields.add(String(field)));
-      }
-      
-      // Add current step's collect fields (in case they're not in route fields)
-      if (currentStep?.collect) {
-        currentStep.collect.forEach(field => allRouteFields.add(String(field)));
-      }
+    // Collect all fields from route's required and optional fields
+    const allRouteFields = new Set<string>();
+    
+    if (route.requiredFields) {
+      route.requiredFields.forEach(field => allRouteFields.add(String(field)));
+    }
+    if (route.optionalFields) {
+      route.optionalFields.forEach(field => allRouteFields.add(String(field)));
+    }
+    if (currentStep?.collect) {
+      currentStep.collect.forEach(field => allRouteFields.add(String(field)));
+    }
+
+    if (allRouteFields.size > 0) {
+      const stepCollectFields = new Set(currentStep?.collect?.map(f => String(f)) || []);
+      const fieldDescriptions: string[] = [];
       
-      if (allRouteFields.size > 0) {
-        const stepCollectFields = new Set(currentStep?.collect?.map(f => String(f)) || []);
-        const fieldDescriptions: string[] = [];
-        
-        for (const field of allRouteFields) {
+      for (const field of allRouteFields) {
+        if (agentSchema?.properties) {
           const fieldSchema = agentSchema.properties[field];
           if (fieldSchema) {
             const fieldName = field;
@@ -193,33 +199,40 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
             
             fieldDescriptions.push(fieldInfo);
           }
+        } else {
+          // No agent schema - generate dynamic description from field name
+          let fieldInfo = `  • ${field} (string): ${field}`;
+          if (stepCollectFields.has(field)) {
+            fieldInfo += ` ← FOCUS FOR THIS STEP`;
+          }
+          fieldDescriptions.push(fieldInfo);
         }
+      }
+      
+      if (fieldDescriptions.length > 0) {
+        const instruction = [
+          `## Data Collection Rules`,
+          ``,
+          `CRITICAL: You MUST extract ALL relevant information from the user's message, not just what this step asks for.`,
+          ``,
+          `Available fields to extract:`,
+          ...fieldDescriptions,
+          ``,
+          `**How to collect data:**`,
+          `1. Read the user's message carefully`,
+          `2. Extract EVERY piece of information that matches ANY field above`,
+          `3. Users often provide multiple details at once (e.g., "I need a checkup next Tuesday at 2 PM")`,
+          `4. Include ALL extracted fields in your JSON response as top-level properties`,
+          `5. Field names must match EXACTLY as shown above`,
+          `6. Only include fields that the user actually mentioned`,
+          ``,
+          `**Example:** If user says "I need a checkup next Tuesday at 2 PM", extract:`,
+          `- appointmentType: "checkup"`,
+          `- preferredDate: "next Tuesday"`,
+          `- preferredTime: "2 PM"`,
+        ].join('\n');
         
-        if (fieldDescriptions.length > 0) {
-          const instruction = [
-            `## Data Collection Rules`,
-            ``,
-            `CRITICAL: You MUST extract ALL relevant information from the user's message, not just what this step asks for.`,
-            ``,
-            `Available fields to extract:`,
-            ...fieldDescriptions,
-            ``,
-            `**How to collect data:**`,
-            `1. Read the user's message carefully`,
-            `2. Extract EVERY piece of information that matches ANY field above`,
-            `3. Users often provide multiple details at once (e.g., "I need a checkup next Tuesday at 2 PM")`,
-            `4. Include ALL extracted fields in your JSON response as top-level properties`,
-            `5. Field names must match EXACTLY as shown above`,
-            `6. Only include fields that the user actually mentioned`,
-            ``,
-            `**Example:** If user says "I need a checkup next Tuesday at 2 PM", extract:`,
-            `- appointmentType: "checkup"`,
-            `- preferredDate: "next Tuesday"`,
-            `- preferredTime: "2 PM"`,
-          ].join('\n');
-          
-          await pc.addInstruction(instruction);
-        }
+        await pc.addInstruction(instruction);
       }
     }
     
@@ -227,24 +240,8 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
     // Generate example JSON based on actual schema fields
     const exampleFields: string[] = ['  "message": "your response to the user"'];
     
-    if (agentSchema?.properties) {
-      // Collect all fields from route's required and optional fields
-      const allRouteFields = new Set<string>();
-      
-      if (route.requiredFields) {
-        route.requiredFields.forEach(field => allRouteFields.add(String(field)));
-      }
-      
-      if (route.optionalFields) {
-        route.optionalFields.forEach(field => allRouteFields.add(String(field)));
-      }
-      
-      if (currentStep?.collect) {
-        currentStep.collect.forEach(field => allRouteFields.add(String(field)));
-      }
-      
-      // Generate example values for each field
-      for (const field of allRouteFields) {
+    for (const field of allRouteFields) {
+      if (agentSchema?.properties) {
         const fieldSchema = agentSchema.properties[field];
         if (fieldSchema) {
           const fieldType = Array.isArray(fieldSchema.type) ? fieldSchema.type[0] : fieldSchema.type;
@@ -263,6 +260,9 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
           
           exampleFields.push(`  "${field}": ${exampleValue}`);
         }
+      } else {
+        // No agent schema - use string as default
+        exampleFields.push(`  "${field}": "extracted value"`);
       }
     }
     

package/src/core/ResponseModal.ts

@@ -1028,29 +1028,36 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
      * @private
      */
     private buildBatchResponseSchema(collectFields: string[]): Record<string, unknown> {
-        const properties: Record<string, unknown> = {
-            message: {
-                type: "string",
-                description: "Your response to the user",
-            },
-        };
+            const properties: Record<string, unknown> = {
+                message: {
+                    type: "string",
+                    description: "Your response to the user",
+                },
+            };
+
+            const agentSchema = this.agent.getSchema();
+
+            // Add collect fields to schema, using agent schema definitions when available
+            for (const field of collectFields) {
+                if (agentSchema?.properties && agentSchema.properties[field]) {
+                    properties[field] = agentSchema.properties[field];
+                } else {
+                    // Dynamic fallback when no agent schema is defined
+                    properties[field] = {
+                        type: "string",
+                        description: `Collected value for ${field}`,
+                    };
+                }
+            }
 
-        // Add collect fields to schema
-        for (const field of collectFields) {
-            properties[field] = {
-                type: "string",
-                description: `Collected value for ${field}`,
+            return {
+                type: "object",
+                properties,
+                required: ["message"],
+                additionalProperties: true,
             };
         }
 
-        return {
-            type: "object",
-            properties,
-            required: ["message"],
-            additionalProperties: true,
-        };
-    }
-
     /**
      * Collect available tools from all steps in the batch
      * @private
@@ -1424,8 +1431,34 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         }
 
         // Update session with next step
-        session = enterStep(session, nextStep.id, nextStep.description);
-        logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+        // If the next step has requires fields that are missing, stay at the previous step
+        if (nextStep.requires && nextStep.requires.length > 0) {
+            const sessionData = session.data || {};
+            const missingRequires = nextStep.requires.filter(
+                field => (sessionData as Record<string, unknown>)[String(field)] === undefined
+            );
+            if (missingRequires.length > 0) {
+                const warning = `[Agent] Cannot advance to step "${nextStep.description || nextStep.id}": ` +
+                    `missing required fields [${missingRequires.join(', ')}]. Staying at current step.`;
+                logger.warn(warning);
+                console.warn(warning);
+                // Stay at the current step - don't enter the next one
+                const currentStepId = session.currentStep?.id;
+                if (currentStepId) {
+                    const currentStepInstance = selectedRoute.getStep(currentStepId);
+                    if (currentStepInstance) {
+                        nextStep = currentStepInstance;
+                        logger.debug(`[ResponseModal] Staying at current step: ${nextStep.id} due to missing requires`);
+                    }
+                }
+            } else {
+                session = enterStep(session, nextStep.id, nextStep.description);
+                logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+            }
+        } else {
+            session = enterStep(session, nextStep.id, nextStep.description);
+            logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+        }
 
         // Build response schema for this route (with collect fields from step)
         const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep, this.agent.getSchema());
@@ -1434,8 +1467,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         const responsePrompt = await this.responseEngine.buildResponsePrompt({
             route: selectedRoute,
             currentStep: nextStep,
-            rules: selectedRoute.getRules(),
-            prohibitions: selectedRoute.getProhibitions(),
+            rules: [...this.agent.getRules(), ...selectedRoute.getRules()],
+            prohibitions: [...this.agent.getProhibitions(), ...selectedRoute.getProhibitions()],
             directives: responseDirectives,
             history: historyEvents, // Use Event[] for buildResponsePrompt
             lastMessage: lastMessageText, // Use string for buildResponsePrompt
@@ -1544,16 +1577,41 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         }
 
         // Update session with next step
-        session = enterStep(session, nextStep.id, nextStep.description);
-        logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+        // If the next step has requires fields that are missing, stay at the previous step
+        if (nextStep.requires && nextStep.requires.length > 0) {
+            const sessionData = session.data || {};
+            const missingRequires = nextStep.requires.filter(
+                field => (sessionData as Record<string, unknown>)[String(field)] === undefined
+            );
+            if (missingRequires.length > 0) {
+                const warning = `[Agent] Cannot advance to step "${nextStep.description || nextStep.id}": ` +
+                    `missing required fields [${missingRequires.join(', ')}]. Staying at current step.`;
+                logger.warn(warning);
+                console.warn(warning);
+                const currentStepId = session.currentStep?.id;
+                if (currentStepId) {
+                    const currentStepInstance = selectedRoute.getStep(currentStepId);
+                    if (currentStepInstance) {
+                        nextStep = currentStepInstance;
+                        logger.debug(`[ResponseModal] Staying at current step: ${nextStep.id} due to missing requires`);
+                    }
+                }
+            } else {
+                session = enterStep(session, nextStep.id, nextStep.description);
+                logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+            }
+        } else {
+            session = enterStep(session, nextStep.id, nextStep.description);
+            logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+        }
 
         // Build response schema and prompt (same as non-streaming)
         const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep, this.agent.getSchema());
         const responsePrompt = await this.responseEngine.buildResponsePrompt({
             route: selectedRoute,
             currentStep: nextStep,
-            rules: selectedRoute.getRules(),
-            prohibitions: selectedRoute.getProhibitions(),
+            rules: [...this.agent.getRules(), ...selectedRoute.getRules()],
+            prohibitions: [...this.agent.getProhibitions(), ...selectedRoute.getProhibitions()],
             directives: responseDirectives,
             history: historyEvents, // Use Event[] for buildResponsePrompt
             lastMessage: lastMessageText, // Use string for buildResponsePrompt