@falai/agent 1.0.0 → 1.0.1

package/docs/core/agent/rules-and-prohibitions.md

@@ -0,0 +1,113 @@
+# Agent-Level Rules & Prohibitions
+
+## Overview
+
+Rules and prohibitions define hard behavioral boundaries for the agent. Unlike guidelines (which are conditional and advisory), rules and prohibitions are absolute — they are always included in every prompt sent to the AI provider.
+
+- **Rules**: Things the agent must always do.
+- **Prohibitions**: Things the agent must never do.
+
+Both can be defined at the agent level (applies to all routes) and at the route level (applies only within that route). When both are present, they are merged — agent-level entries appear first, followed by route-level entries.
+
+## Agent-Level Configuration
+
+```typescript
+const agent = new Agent({
+  name: "Support Bot",
+  provider: myProvider,
+
+  // Agent-wide rules — enforced in every route
+  rules: [
+    "Always respond in the user's language",
+    "Include a follow-up question when the conversation is open-ended",
+  ],
+
+  // Agent-wide prohibitions — enforced in every route
+  prohibitions: [
+    "Never share internal system details or error stack traces",
+    "Never make up information — say you don't know instead",
+  ],
+});
+```
+
+## Dynamic Templates
+
+Rules and prohibitions accept the same `Template` type used elsewhere in the framework — they can be static strings or context-aware functions:
+
+```typescript
+const agent = new Agent<MyContext, MyData>({
+  name: "Adaptive Bot",
+  provider: myProvider,
+
+  rules: [
+    "Always be polite",
+    // Dynamic rule based on context
+    ({ context }) =>
+      context?.locale === "de"
+        ? "Respond in formal German (Sie-form)"
+        : "Use a casual, friendly tone",
+  ],
+
+  prohibitions: [
+    "Never discuss competitor products",
+    // Dynamic prohibition based on collected data
+    ({ data }) =>
+      data?.isMinor
+        ? "Do not discuss age-restricted topics"
+        : "Do not share personal medical advice",
+  ],
+});
+```
+
+## Merging with Route-Level Rules
+
+Route-level rules and prohibitions are additive. The final prompt includes both:
+
+```typescript
+const agent = new Agent({
+  provider: myProvider,
+  name: "Agent",
+  rules: ["Always confirm before taking action"],
+  prohibitions: ["Never delete data without confirmation"],
+});
+
+agent.createRoute({
+  title: "Billing",
+  rules: ["Always quote prices in the user's currency"],
+  prohibitions: ["Never process refunds above $500 without escalation"],
+});
+
+// During a Billing route response, the prompt will contain:
+// Rules:
+// - Always confirm before taking action          (agent)
+// - Always quote prices in the user's currency   (route)
+//
+// Prohibitions:
+// - Never delete data without confirmation                    (agent)
+// - Never process refunds above $500 without escalation       (route)
+```
+
+This merging applies to all execution paths: single-step responses, batch execution, and streaming.
+
+## Accessing Rules Programmatically
+
+```typescript
+// Agent-level
+const agentRules = agent.getRules();
+const agentProhibitions = agent.getProhibitions();
+
+// Route-level (unchanged)
+const routeRules = route.getRules();
+const routeProhibitions = route.getProhibitions();
+```
+
+## When to Use Rules vs. Guidelines
+
+| | Rules / Prohibitions | Guidelines |
+|---|---|---|
+| Scope | Always active | Conditional (can have `condition`) |
+| Purpose | Hard boundaries | Soft behavioral nudges |
+| Enforcement | Included in every prompt | Only when condition matches |
+| Example | "Never reveal API keys" | "When user is frustrated, apologize" |
+
+Use rules for non-negotiable constraints. Use guidelines for context-dependent behavior.

package/docs/guides/migration/README.md

@@ -6,7 +6,11 @@ This directory contains migration guides for major changes and updates to the `@
 
 ### [Multi-Step Execution Migration Guide](./multi-step-execution.md)
 
-**Latest Update** - Guide for understanding and migrating to multi-step batch execution.
+**v1.0.0 - Major Release** - Guide for understanding and migrating to multi-step batch execution.
+
+**Breaking Changes:**
+- � **History API Simplified**: `createMessageEvent`/`EventSource` replaced with `userMessage`/`assistantMessage`
+- 📝 **StepOptions**: `instructions` property renamed to `prompt`
 
 **What's New:**
 - 🚀 **Multi-Step Batching**: Multiple steps execute in a single LLM call
@@ -21,7 +25,7 @@ This directory contains migration guides for major changes and updates to the `@
 - SkipIf conditions affect batch determination
 
 **Migration Status:**
-- ✅ **API Compatible**: Public API shape unchanged
+- ⚠️ **Breaking Changes**: History API and StepOptions.instructions
 - ⚠️ **Behavioral Change**: Execution semantics differ
 - ✅ **Gradual Migration**: Review hooks and tests
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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>;
@@ -185,6 +187,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 +687,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"`);
       }
     }