@falai/agent 3.4.5 → 4.0.0-alpha.2

package/src/core/ResponseEngine.ts

@@ -1,338 +0,0 @@
-import type {
-  Event,
-  StructuredSchema,
-  SessionState,
-  AgentOptions,
-  Term,
-  Template,
-  ScopedInstructions,
-  AppliedInstruction,
-} from "../types/index.js";
-import type { Flow } from "./Flow.js";
-import type { Step } from "./Step.js";
-import { PromptComposer } from "./PromptComposer.js";
-import { PromptSectionCache } from "./PromptSectionCache.js";
-import { createTemplateContext, render } from "../utils/template.js";
-
-export interface BuildResponsePromptParams<
-  TContext = unknown,
-  TData = unknown
-> {
-  flow: Flow<TContext, TData>;
-  currentStep: Step<TContext, TData>;
-  rules: Template<TContext, TData>[];
-  prohibitions: Template<TContext, TData>[];
-  directives: string[] | undefined;
-  history: Event[];
-  agentOptions?: AgentOptions<TContext, TData>;
-  // Scoped instructions (agent, flow, step)
-  instructions?: ScopedInstructions<TContext, TData>;
-  combinedTerms?: Term<TContext, TData>[];
-  context?: TContext;
-  session?: SessionState<TData>;
-  // NEW: Agent-level schema for data validation
-  agentSchema?: StructuredSchema;
-  /**
-   * Per-turn transient appendage from merged Directive.appendPrompt arrays.
-   * Appended to the system prompt after all other sections.
-   * Fresh every turn, never cached, never persisted.
-   */
-  transientAppendage?: string[];
-}
-
-export interface BuildFallbackPromptParams<TContext = unknown, TData = unknown> {
-  agentOptions: AgentOptions<TContext, TData>;
-  terms: Term<TContext, TData>[];
-  instructions?: ScopedInstructions<TContext, TData>;
-  context?: TContext;
-  session?: SessionState<TData>;
-}
-
-export interface PromptBuilderResult {
-  prompt: string;
-  appliedInstructions: AppliedInstruction[];
-}
-
-export class ResponseEngine<TContext = unknown, TData = unknown> {
-  constructor(private readonly promptSectionCache?: PromptSectionCache) { }
-
-  responseSchemaForFlow(
-    flow: Flow<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 flow has responseOutputSchema
-    if (flow.responseOutputSchema) {
-      base.properties!.data = flow.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)}`,
-          };
-        }
-      }
-    }
-
-    return base;
-  }
-
-  async buildResponsePrompt(
-    params: BuildResponsePromptParams<TContext, TData>
-  ): Promise<PromptBuilderResult> {
-    const {
-      flow,
-      currentStep,
-      rules,
-      prohibitions,
-      directives,
-      history,
-      agentOptions,
-      instructions,
-      combinedTerms,
-      context,
-      session,
-      agentSchema,
-      transientAppendage,
-    } = params;
-    const templateContext = createTemplateContext({ context, session, history });
-    const pc = new PromptComposer(templateContext, this.promptSectionCache);
-
-    // Create combined agent options — flow no longer overrides persona
-    const effectiveAgentOptions = agentOptions;
-
-    if (effectiveAgentOptions) {
-      await pc.addAgentMeta(effectiveAgentOptions);
-    }
-    await pc.addInstruction(
-      `Flow: ${flow.title}${flow.description ? ` — ${flow.description}` : ""
-      }`
-    );
-    if (currentStep.prompt) {
-      await pc.addInstruction(
-        `Guideline for your response (adapt to the conversation):\n${await render(
-          currentStep.prompt,
-          templateContext
-        )}`
-      );
-    }
-    if (rules.length)
-      await pc.addInstruction(`Rules:\n- ${rules.join("\n- ")}`);
-    if (prohibitions.length)
-      await pc.addInstruction(`Prohibitions:\n- ${prohibitions.join("\n- ")}`);
-    await pc.addDirectives(directives);
-    await pc.addKnowledgeBase(
-      agentOptions?.knowledgeBase,
-      flow.knowledgeBase
-    );
-
-    // Add scoped instructions (agent + flow + step)
-    if (instructions) {
-      await pc.addInstructions(instructions);
-    }
-
-    // Add combined terms (agent + flow)
-    if (combinedTerms && combinedTerms.length > 0) {
-      await pc.addGlossary(combinedTerms);
-    }
-
-    // Add data collection instructions - include ALL flow fields, not just current step
-    // Collect all fields from flow's required and optional fields
-    const allFlowFields = new Set<string>();
-
-    if (flow.requiredFields) {
-      flow.requiredFields.forEach(field => allFlowFields.add(String(field)));
-    }
-    if (flow.optionalFields) {
-      flow.optionalFields.forEach(field => allFlowFields.add(String(field)));
-    }
-    if (currentStep?.collect) {
-      currentStep.collect.forEach(field => allFlowFields.add(String(field)));
-    }
-
-    if (allFlowFields.size > 0) {
-      const stepCollectFields = new Set(currentStep?.collect?.map(f => String(f)) || []);
-      const fieldDescriptions: string[] = [];
-
-      // Values already in session data (pre-extraction this turn, or earlier
-      // turns). The routing prompt shows them; the response prompt must too,
-      // or the model follows a "ask for X" guideline for an X it already has.
-      const sessionData = (session?.data ?? {}) as Record<string, unknown>;
-      const isKnown = (field: string): boolean => {
-        const value = sessionData[field];
-        return value !== undefined && value !== null && value !== '';
-      };
-      const fieldMarkers = (field: string): string => {
-        let markers = '';
-        if (stepCollectFields.has(field)) markers += ` ← FOCUS FOR THIS STEP`;
-        if (isKnown(field)) markers += ` ← ALREADY KNOWN: ${JSON.stringify(sessionData[field])}`;
-        return markers;
-      };
-
-      for (const field of allFlowFields) {
-        if (agentSchema?.properties) {
-          const fieldSchema = agentSchema.properties[field];
-          if (fieldSchema) {
-            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}`;
-            fieldInfo += fieldMarkers(field);
-
-            fieldDescriptions.push(fieldInfo);
-          }
-        } else {
-          // No agent schema - generate dynamic description from field name
-          fieldDescriptions.push(`  • ${field} (string): ${field}${fieldMarkers(field)}`);
-        }
-      }
-
-      if (fieldDescriptions.length > 0) {
-        const stepSatisfied =
-          stepCollectFields.size > 0 && [...stepCollectFields].every(isKnown);
-        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,
-          ``,
-          `**Already-known fields:**`,
-          `- A field marked ALREADY KNOWN is settled. NEVER ask the user for it again, even when the guideline above says to ask: acknowledge it and move on to what the step still needs.`,
-          `- The same applies to a field the user's latest message already answers: extract it, do not ask for it.`,
-          ...(stepSatisfied
-            ? [
-              `- Every FOCUS field of this step is already known, so this step's questions are done. Respond to what the user said and move the conversation forward.`,
-            ]
-            : []),
-          ``,
-          `**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);
-      }
-    }
-
-    // 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 allFlowFields) {
-      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]}"`;
-          } else if (fieldType === 'string') {
-            exampleValue = '"extracted value"';
-          } else if (fieldType === 'number' || fieldType === 'integer') {
-            exampleValue = '0';
-          } else if (fieldType === 'boolean') {
-            exampleValue = 'true';
-          }
-
-          exampleFields.push(`  "${field}": ${exampleValue}`);
-        }
-      } else {
-        // No agent schema - use string as default
-        exampleFields.push(`  "${field}": "extracted value"`);
-      }
-    }
-
-    await pc.addInstruction(
-      [
-        `## Response Format`,
-        ``,
-        `You MUST return ONLY valid JSON in this exact format:`,
-        `{`,
-        ...exampleFields.map((f, i) => i < exampleFields.length - 1 ? `${f},` : f),
-        `}`,
-        ``,
-        `CRITICAL RULES:`,
-        `- Return ONLY the JSON object, no other text`,
-        `- 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')
-    );
-
-    const prompt = await pc.build({ transientAppendage });
-    return {
-      prompt,
-      appliedInstructions: pc.lastAppliedInstructions ?? [],
-    };
-  }
-
-  async buildFallbackPrompt(
-    params: BuildFallbackPromptParams<TContext, TData>
-  ): Promise<PromptBuilderResult> {
-    const { agentOptions, terms, instructions, context, session } =
-      params;
-    const templateContext = createTemplateContext({ context, session });
-    const pc = new PromptComposer(templateContext, this.promptSectionCache);
-
-    await pc.addAgentMeta(agentOptions);
-    await pc.addGlossary(terms);
-    if (instructions) {
-      await pc.addInstructions(instructions);
-    }
-    await pc.addKnowledgeBase(agentOptions.knowledgeBase);
-    const prompt = await pc.build();
-    return {
-      prompt,
-      appliedInstructions: pc.lastAppliedInstructions ?? [],
-    };
-  }
-}

package/src/core/ResponseGenerationError.ts

@@ -1,53 +0,0 @@
-/**
- * Error type for response-generation failures, shared by the response
- * coordinator and its collaborators.
- */
-
-/**
- * Error details for response generation failures
- */
-interface ResponseGenerationErrorDetails {
-    originalError?: unknown;
-    params?: Record<string, unknown>;
-    phase?: string;
-    context?: Record<string, unknown>;
-}
-
-/**
- * Error class for response generation failures
- */
-export class ResponseGenerationError extends Error {
-    constructor(
-        message: string,
-        public readonly details?: ResponseGenerationErrorDetails
-    ) {
-        // Native `cause` chain: `err.cause` is the original error, so
-        // consumers can reach ProviderError.code etc. without string matching.
-        super(message, { cause: details?.originalError });
-        this.name = 'ResponseGenerationError';
-    }
-
-    /**
-     * Create a ResponseGenerationError from an unknown error
-     */
-    static fromError(
-        error: unknown,
-        phase: string,
-        params?: Record<string, unknown>,
-        context?: Record<string, unknown>
-    ): ResponseGenerationError {
-        const message = error instanceof Error ? error.message : String(error);
-        return new ResponseGenerationError(
-            `[ResponseGenerationError] Response generation failed in ${phase}: ${message}. ` +
-            `Check provider configuration and the ${phase} phase handler.`,
-            { originalError: error, params, phase, context }
-        );
-    }
-
-    /**
-     * Check if an error is a ResponseGenerationError
-     */
-    static isResponseGenerationError(error: unknown): error is ResponseGenerationError {
-        return error instanceof ResponseGenerationError;
-    }
-}