@falai/agent 1.1.1 → 1.1.2

package/src/core/BatchExecutor.ts

@@ -335,8 +335,11 @@ export class BatchExecutor<TContext = unknown, TData = unknown> {
           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);
+
+          // Also log to console for developer visibility (but silence in test suites to prevent fast-check spam)
+          if (process.env.NODE_ENV !== 'test') {
+            console.warn(warning);
+          }
         }
 
         logger.debug(`[BatchExecutor] Step ${step.id} needs input, stopping batch. Missing requires: [${missingRequires.join(', ')}], Collect fields: [${collectFields.join(', ')}]`);

package/src/core/BatchPromptBuilder.ts

@@ -66,7 +66,7 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
    */
   async buildBatchPrompt(params: BuildBatchPromptParams<TContext, TData>): Promise<BatchPromptResult> {
     const { steps, route, history, context, session, agentOptions } = params;
-    
+
     // Create template context for rendering
     const templateContext = createTemplateContext<TContext, TData>({
       context,
@@ -74,7 +74,7 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
       session,
       history,
     });
-    
+
     // Collect all collect fields from all steps
     const collectFields: string[] = [];
     for (const step of steps) {
@@ -87,13 +87,13 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
         }
       }
     }
-    
+
     // Build the combined prompt using PromptComposer for consistency
     const composer = new PromptComposer<TContext, TData>(templateContext);
-    
+
     // Add agent meta information
     await composer.addAgentMeta(agentOptions);
-    
+
     // Add route-specific identity/personality if available
     if (route.identity) {
       const identity = await render(route.identity, templateContext);
@@ -101,25 +101,25 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
         await composer.addInstruction(`**Route Identity:** ${identity}`);
       }
     }
-    
+
     if (route.personality) {
       const personality = await render(route.personality, templateContext);
       if (personality) {
         await composer.addInstruction(`**Route Personality:** ${personality}`);
       }
     }
-    
+
     // Add knowledge base if available
     await composer.addKnowledgeBase(agentOptions.knowledgeBase, route.getKnowledgeBase());
-    
+
     // Add glossary terms
     const allTerms = [...(agentOptions.terms || []), ...route.getTerms()];
     await composer.addGlossary(allTerms);
-    
+
     // Add guidelines
     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) {
@@ -128,7 +128,7 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
         await composer.addInstruction(`Rules:\n- ${renderedRules.join('\n- ')}`);
       }
     }
-    
+
     // Add combined prohibitions (agent + route)
     const allProhibitions = [...(agentOptions.prohibitions || []), ...route.getProhibitions()];
     if (allProhibitions.length > 0) {
@@ -137,13 +137,13 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
         await composer.addInstruction(`Prohibitions:\n- ${renderedProhibitions.join('\n- ')}`);
       }
     }
-    
+
     // Add interaction history
     await composer.addInteractionHistory(history, 'Recent conversation context:');
-    
+
     // Build the step sections
     const stepSections = await this.buildStepSections(steps, templateContext);
-    
+
     // Add the conversation flow section
     if (steps.length > 1) {
       await composer.addInstruction(
@@ -157,27 +157,27 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
         stepSections
       );
     }
-    
+
     // Add data collection section if there are fields to collect
     if (collectFields.length > 0) {
       const collectionSection = this.buildDataCollectionSection(collectFields, agentOptions);
       await composer.addInstruction(collectionSection);
     }
-    
+
     // Add response format instructions
     const responseFormat = this.buildResponseFormatSection(collectFields);
     await composer.addInstruction(responseFormat);
-    
+
     // Build the final prompt
     const prompt = await composer.build();
-    
+
     return {
       prompt,
       collectFields,
       stepCount: steps.length,
     };
   }
-  
+
   /**
    * Build the step sections of the prompt
    * 
@@ -190,15 +190,15 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
     templateContext: ReturnType<typeof createTemplateContext<TContext, TData>>
   ): Promise<string> {
     const sections: string[] = [];
-    
+
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
       const stepNumber = i + 1;
-      
+
       // Build step header
       const description = step.description || `Step ${stepNumber}`;
       let section = `### Step ${stepNumber}: ${description}\n`;
-      
+
       // Render and add step prompt if available
       if (step.prompt) {
         const renderedPrompt = await render(step.prompt, templateContext);
@@ -206,19 +206,19 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
           section += `\n${renderedPrompt}\n`;
         }
       }
-      
+
       // Add collect fields for this step if any
       if (step.collect && step.collect.length > 0) {
         const collectList = step.collect.map(f => `\`${String(f)}\``).join(', ');
         section += `\n**Collect:** ${collectList}\n`;
       }
-      
+
       sections.push(section);
     }
-    
+
     return sections.join('\n');
   }
-  
+
   /**
    * Build the data collection section of the prompt
    * 
@@ -236,36 +236,36 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
       'Extract the following information from your response:',
       ''
     ];
-    
+
     // Get schema information if available
     const schema = agentOptions.schema;
-    
+
     for (const field of collectFields) {
       let fieldDescription = field;
-      
+
       // Try to get field type/description from schema
       if (schema?.properties && schema.properties[field]) {
         const fieldSchema = schema.properties[field] as Record<string, unknown>;
         const rawType = fieldSchema.type;
         const rawDescription = fieldSchema.description;
-        
+
         // Safely convert to string, handling objects and primitives
         const type = typeof rawType === 'string' ? rawType : 'string';
         const description = typeof rawDescription === 'string' ? rawDescription : '';
-        
+
         if (description) {
           fieldDescription = `${field} (${type}): ${description}`;
         } else {
           fieldDescription = `${field} (${type})`;
         }
       }
-      
+
       lines.push(`- ${fieldDescription}`);
     }
-    
+
     return lines.join('\n');
   }
-  
+
   /**
    * Build the response format section of the prompt
    * 
@@ -277,17 +277,20 @@ export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
       '## Response Format',
       '',
       'Return JSON with:',
-      '- `message`: Your response to the user'
+      '- `message`: A natural, conversational response directed at the user. This MUST read like a human conversation.',
+      '',
+      'CRITICAL: The `message` field must NEVER contain field names, JSON keys, raw data values, or technical information.',
+      'Data goes in the separate JSON fields below, NOT in the message text.',
     ];
-    
+
     if (collectFields.length > 0) {
       lines.push('');
-      lines.push('Include the following collected fields as top-level properties:');
+      lines.push('Include the following collected fields as top-level properties (separate from message):');
       for (const field of collectFields) {
         lines.push(`- \`${field}\``);
       }
     }
-    
+
     return lines.join('\n');
   }
 }

package/src/core/ResponseEngine.ts

@@ -44,48 +44,48 @@ 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: "Natural, conversational response directed at the user. Must NOT contain field names, raw data, or internal information." },
+      },
+      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
-      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)}`,
-            };
+    // 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>
   ): Promise<string> {
@@ -155,11 +155,11 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
 
     await pc.addInteractionHistory(history);
     await pc.addLastMessage(lastMessage);
-    
+
     // Add data collection instructions - include ALL route fields, not just current step
     // 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)));
     }
@@ -173,7 +173,7 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
     if (allRouteFields.size > 0) {
       const stepCollectFields = new Set(currentStep?.collect?.map(f => String(f)) || []);
       const fieldDescriptions: string[] = [];
-      
+
       for (const field of allRouteFields) {
         if (agentSchema?.properties) {
           const fieldSchema = agentSchema.properties[field];
@@ -181,22 +181,22 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
             const fieldName = field;
             const fieldDesc = fieldSchema.description || fieldName;
             const fieldType = Array.isArray(fieldSchema.type) ? fieldSchema.type[0] : fieldSchema.type;
-            
+
             let fieldInfo = `  • ${fieldName} (${fieldType})`;
-            
+
             // Add enum values if present
             if (fieldSchema.enum && Array.isArray(fieldSchema.enum)) {
               fieldInfo += ` [${fieldSchema.enum.join(' | ')}]`;
             }
-            
+
             // Add description
             fieldInfo += `: ${fieldDesc}`;
-            
+
             // Mark if this is the current step's focus
             if (stepCollectFields.has(field)) {
               fieldInfo += ` ← FOCUS FOR THIS STEP`;
             }
-            
+
             fieldDescriptions.push(fieldInfo);
           }
         } else {
@@ -208,7 +208,7 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
           fieldDescriptions.push(fieldInfo);
         }
       }
-      
+
       if (fieldDescriptions.length > 0) {
         const instruction = [
           `## Data Collection Rules`,
@@ -231,22 +231,22 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
           `- preferredDate: "next Tuesday"`,
           `- preferredTime: "2 PM"`,
         ].join('\n');
-        
+
         await pc.addInstruction(instruction);
       }
     }
-    
+
     // Add response format instructions with explicit JSON structure
     // Generate example JSON based on actual schema fields
     const exampleFields: string[] = ['  "message": "your response to the user"'];
-    
+
     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;
           let exampleValue = '"value if extracted"';
-          
+
           // Generate type-appropriate example
           if (fieldSchema.enum && Array.isArray(fieldSchema.enum) && fieldSchema.enum.length > 0) {
             exampleValue = `"${fieldSchema.enum[0]}"`;
@@ -257,7 +257,7 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
           } else if (fieldType === 'boolean') {
             exampleValue = 'true';
           }
-          
+
           exampleFields.push(`  "${field}": ${exampleValue}`);
         }
       } else {
@@ -265,7 +265,7 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
         exampleFields.push(`  "${field}": "extracted value"`);
       }
     }
-    
+
     await pc.addInstruction(
       [
         `## Response Format`,
@@ -277,14 +277,17 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
         ``,
         `CRITICAL RULES:`,
         `- Return ONLY the JSON object, no other text`,
-        `- The "message" field is REQUIRED and must contain your response to the user`,
-        `- Include ALL extracted data fields as top-level properties`,
+        `- The "message" field is REQUIRED and must contain a natural, conversational response directed at the user`,
+        `- The "message" MUST read like a human conversation - warm, natural, and contextual`,
+        `- NEVER include field names, JSON keys, schema properties, raw data values, or technical/internal information in the "message"`,
+        `- NEVER echo back data in the format "fieldName: value" in the "message" - data goes in the JSON fields, not the message`,
+        `- Include ALL extracted data fields as separate top-level JSON properties (NOT inside the message text)`,
         `- Only include data fields that were actually mentioned by the user`,
         `- Do not wrap the JSON in markdown code blocks`,
         `- Do not add any explanatory text before or after the JSON`,
       ].join('\n')
     );
-    
+
     return pc.build();
   }