@falai/agent 2.2.3 → 2.4.1

package/src/core/FlowRouter.ts

@@ -67,6 +67,7 @@ export interface BuildStepSelectionPromptParams<
   context?: TContext;
   session?: SessionState<TData>;
   stepConditionContext?: string[]; // AI context strings from step conditions
+  stepExclusionContext?: string[]; // AI exclusion strings from step conditions
 }
 
 export interface BuildRoutingPromptParams<TContext = unknown, TData = unknown> {
@@ -384,9 +385,11 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
 
     // Collect AI context strings from step conditions
     const stepConditionContext: string[] = [];
+    const stepExclusionContext: string[] = [];
     for (const candidate of candidates) {
       const whenResult = await candidate.step.evaluateWhen(templateContext);
       stepConditionContext.push(...whenResult.aiContextStrings);
+      stepExclusionContext.push(...whenResult.aiExclusionStrings);
     }
 
     // Check if any candidate is a completion marker (isFlowComplete = true)
@@ -403,6 +406,7 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
       context,
       session: updatedSession,
       stepConditionContext,
+      stepExclusionContext,
       includeCompletion: hasCompletionOption,
     });
 
@@ -1100,6 +1104,7 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
       context,
       session,
       stepConditionContext,
+      stepExclusionContext,
       includeCompletion = false,
     } = params;
     const templateContext = createTemplateContext({ context, session, history });
@@ -1152,8 +1157,9 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
         const whenResult = await candidate.step.evaluateWhen(templateContext);
         if (whenResult.aiContextStrings.length > 0) {
           parts.push(`   When any condition matches: ${whenResult.aiContextStrings.join(" OR ")}`);
-        } else if (typeof candidate.step.when === 'string') {
-          parts.push(`   When this step should be completed: ${candidate.step.when}`);
+        }
+        if (whenResult.aiExclusionStrings.length > 0) {
+          parts.push(`   Do not choose when any condition matches: ${whenResult.aiExclusionStrings.join(" OR ")}`);
         }
       }
 
@@ -1185,6 +1191,18 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
       );
     }
 
+    if (stepExclusionContext && stepExclusionContext.length > 0) {
+      await pc.addInstruction(
+        [
+          "",
+          "Additional step exclusion context:",
+          ...stepExclusionContext.map(ctx => `- ${ctx}`),
+          "",
+          "Avoid selecting steps when their exclusion context matches.",
+        ].join("\n")
+      );
+    }
+
     // Add decision prompt
     const decisionRules = [
       "Task: Decide which step to transition to based on:",
@@ -1424,6 +1442,7 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
           "Available steps in active route (choose one to transition to):",
         ];
         const activeStepConditionContext: string[] = [];
+        const activeStepExclusionContext: string[] = [];
 
         for (const step of activeFlowSteps) {
           const idx = activeFlowSteps.indexOf(step);
@@ -1438,8 +1457,10 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
             if (whenResult.aiContextStrings.length > 0) {
               stepInfo.push(`   When any condition matches: ${whenResult.aiContextStrings.join(" OR ")}`);
               activeStepConditionContext.push(...whenResult.aiContextStrings);
-            } else if (typeof step.when === 'string') {
-              stepInfo.push(`   When this step should be completed: ${step.when}`);
+            }
+            if (whenResult.aiExclusionStrings.length > 0) {
+              stepInfo.push(`   Do not choose when any condition matches: ${whenResult.aiExclusionStrings.join(" OR ")}`);
+              activeStepExclusionContext.push(...whenResult.aiExclusionStrings);
             }
           }
 
@@ -1472,6 +1493,17 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
             ].join("\n")
           );
         }
+        if (activeStepExclusionContext.length > 0) {
+          await pc.addInstruction(
+            [
+              "",
+              "Additional step exclusion context:",
+              ...activeStepExclusionContext.map(ctx => `- ${ctx}`),
+              "",
+              "Avoid selecting steps when their exclusion context matches.",
+            ].join("\n")
+          );
+        }
       }
     }
 

package/src/core/PersistenceManager.ts

@@ -18,7 +18,8 @@ import type {
   PersistenceAdapter,
   CollectedStateData,
 } from "../types";
-import { createSession, sessionStepToData, sessionDataToStep } from "../utils";
+import { createSession, sessionStepToData, sessionDataToStep, logger } from "../utils";
+import { SessionConflictError } from "../types/errors";
 import { convertMessagesToHistory } from "./Events";
 
 /**
@@ -29,6 +30,8 @@ export class PersistenceManager<TData = Record<string, unknown>> {
   private config: PersistenceConfig<TData>;
   private sessionRepository: SessionRepository<TData>;
   private messageRepository: MessageRepository;
+  /** Per-session in-process save queue; see saveSessionState. */
+  private saveQueues = new Map<string, Promise<SessionData<TData> | null>>();
 
   constructor(config: PersistenceConfig<TData>) {
     this.config = {
@@ -233,6 +236,28 @@ export class PersistenceManager<TData = Record<string, unknown>> {
   async saveSessionState(
     sessionId: string,
     sessionStep: SessionState<TData>
+  ): Promise<SessionData<TData> | null> {
+    // Serialize same-process saves per session: concurrent saves of the same
+    // in-memory session would otherwise race the version compare-and-swap and
+    // spuriously conflict with each other. Cross-process conflicts (two
+    // independently loaded copies) still throw SessionConflictError.
+    const previous = this.saveQueues.get(sessionId) ?? Promise.resolve();
+    const run = previous
+      .catch(() => undefined)
+      .then(() => this.doSaveSessionState(sessionId, sessionStep));
+    this.saveQueues.set(sessionId, run);
+    try {
+      return await run;
+    } finally {
+      if (this.saveQueues.get(sessionId) === run) {
+        this.saveQueues.delete(sessionId);
+      }
+    }
+  }
+
+  private async doSaveSessionState(
+    sessionId: string,
+    sessionStep: SessionState<TData>
   ): Promise<SessionData<TData> | null> {
     // Validate input parameters
     if (!sessionId || typeof sessionId !== 'string') {
@@ -256,21 +281,31 @@ export class PersistenceManager<TData = Record<string, unknown>> {
       throw new Error(`Failed to convert session step to persistence data: ${errorMessage}`);
     }
 
+    // Stamp the configured schema version so loads can detect stale state
+    if (this.config.schemaVersion !== undefined) {
+      persistenceData.collectedData.schemaVersion = this.config.schemaVersion;
+    }
+
     try {
       // First try to find existing session
       const existingSession = await this.sessionRepository.findById(sessionId);
 
+      let saved: SessionData<TData> | null;
       if (existingSession) {
-        // Update existing session
-        return await this.sessionRepository.update(sessionId, {
-          currentFlow: persistenceData.currentFlow,
-          currentStep: persistenceData.currentStep,
-          collectedData: persistenceData.collectedData,
-          lastMessageAt: new Date(),
-        });
+        // Compare-and-swap on the session's version: a concurrent writer
+        // bumped it since we loaded, the adapter throws SessionConflictError
+        saved = await this.sessionRepository.update(
+          sessionId,
+          {
+            currentFlow: persistenceData.currentFlow,
+            currentStep: persistenceData.currentStep,
+            collectedData: persistenceData.collectedData,
+            lastMessageAt: new Date(),
+          },
+          { expectedVersion: sessionStep.version }
+        );
       } else {
-        // Create new session if it doesn't exist
-        return await this.sessionRepository.create({
+        saved = await this.sessionRepository.create({
           id: sessionId,
           userId: persistenceData.collectedData.metadata?.userId
             ? JSON.stringify(persistenceData.collectedData.metadata?.userId)
@@ -280,9 +315,21 @@ export class PersistenceManager<TData = Record<string, unknown>> {
           currentStep: persistenceData.currentStep,
           collectedData: persistenceData.collectedData,
           messageCount: 0,
+          version: 1,
         });
       }
+
+      // Propagate the new version so the next save of this in-memory session
+      // passes the compare-and-swap
+      if (saved?.version !== undefined) {
+        sessionStep.version = saved.version;
+      }
+
+      return saved;
     } catch (error) {
+      if (error instanceof SessionConflictError) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(`Failed to save session state to persistence: ${errorMessage}`);
     }
@@ -301,6 +348,28 @@ export class PersistenceManager<TData = Record<string, unknown>> {
       return null;
     }
 
+    // Upgrade state written under an older user schema before reconstructing
+    if (
+      this.config.schemaVersion !== undefined &&
+      sessionData.collectedData &&
+      sessionData.collectedData.schemaVersion !== this.config.schemaVersion
+    ) {
+      const fromVersion = sessionData.collectedData.schemaVersion;
+      if (this.config.migrateSession) {
+        sessionData.collectedData = await this.config.migrateSession(
+          sessionData.collectedData,
+          fromVersion
+        );
+        sessionData.collectedData.schemaVersion = this.config.schemaVersion;
+      } else {
+        logger.warn(
+          `[PersistenceManager] Session "${sessionId}" was written with schemaVersion ` +
+          `${fromVersion ?? 'none'} but the agent is configured with ${this.config.schemaVersion}, ` +
+          `and no migrateSession is configured. Loading state as-is.`
+        );
+      }
+    }
+
     // Reconstruct SessionState from SessionData
     const sessionState = sessionDataToStep<TData>(sessionId, sessionData);
 

package/src/core/PromptComposer.ts

@@ -4,6 +4,7 @@ import { render, renderMany, formatKnowledgeBase, createTemplateContext } from "
 import { TemplateContext } from "../types/template";
 import { PromptSectionCache } from "./PromptSectionCache";
 import { logger } from "../utils";
+import { splitWhenConditions } from "../utils/condition";
 
 export class PromptComposer<TContext = unknown, TData = unknown> {
   private parts: string[] = [];
@@ -209,10 +210,18 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
         if (!text) continue;
 
         const whenContextStrings = g.when
-          ? (Array.isArray(g.when) ? g.when : [g.when])
-          : [];
-        const condition = whenContextStrings.length > 0
-          ? ` (apply only when: ${whenContextStrings.join(" OR ")})`
+          ? splitWhenConditions(g.when)
+          : { positive: [], negative: [] };
+        const conditionParts = [
+          whenContextStrings.positive.length > 0
+            ? `apply only when: ${whenContextStrings.positive.join(" OR ")}`
+            : undefined,
+          whenContextStrings.negative.length > 0
+            ? `do not apply when: ${whenContextStrings.negative.join(" OR ")}`
+            : undefined,
+        ].filter((part): part is string => part !== undefined);
+        const condition = conditionParts.length > 0
+          ? ` (${conditionParts.join("; ")})`
           : "";
 
         lines.push(`- ${kindPrefix(g.kind)} ${caption} ${text}${condition}`);
@@ -333,14 +342,18 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
 
     const compute = (): string | null => {
       const renderedFlows = flows.map((r, i) => {
-        // v2: `when` is string | string[] (AI-evaluated). Extract directly.
-        const whenContextStrings: string[] = r.when
-          ? (Array.isArray(r.when) ? r.when : [r.when])
-          : [];
-        const conditions =
-          whenContextStrings.length > 0
-            ? `\n\n  **Triggered when:** ${whenContextStrings.join(" OR ")}`
-            : "";
+        // v2: `when` is string | string[] (AI-evaluated). Split into positives and exclusions.
+        const whenContextStrings = r.when
+          ? splitWhenConditions(r.when)
+          : { positive: [], negative: [] };
+        const conditionParts: string[] = [];
+        if (whenContextStrings.positive.length > 0) {
+          conditionParts.push(`\n\n  **Triggered when:** ${whenContextStrings.positive.join(" OR ")}`);
+        }
+        if (whenContextStrings.negative.length > 0) {
+          conditionParts.push(`\n\n  **Do not trigger when:** ${whenContextStrings.negative.join(" OR ")}`);
+        }
+        const conditions = conditionParts.join("");
         const desc = r.description
           ? `\n\n  **Description:** ${r.description}`
           : "";

package/src/core/ResponseGenerationError.ts

@@ -0,0 +1,56 @@
+/**
+ * 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
+    ) {
+        super(message);
+        this.name = 'ResponseGenerationError';
+
+        // Preserve stack trace from original error if available
+        if (details?.originalError instanceof Error && details.originalError.stack) {
+            this.stack = `${this.stack}\nCaused by: ${details.originalError.stack}`;
+        }
+    }
+
+    /**
+     * 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;
+    }
+}