@falai/agent 2.2.3 → 2.4.1

package/src/core/Agent.ts

@@ -23,7 +23,7 @@ import type { Signal } from "../types/signals";
 import { NotImplementedError } from "../types/errors";
 import { SignalProcessor } from "./SignalProcessor";
 import { SignalEvaluator } from "./SignalEvaluator";
-import type { StreamOptions, GenerateOptions, RespondParams } from "./ResponseModal";
+import type { StreamOptions, GenerateOptions, RespondParams, ResponseModalDeps } from "./ResponseModal";
 import {
   mergeCollected,
   enterFlow,
@@ -68,8 +68,8 @@ class FlowConfigurationError extends Error {
 /**
  * Main Agent class with generic context and data support
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export class Agent<TContext = any, TData = any> {
+ 
+export class Agent<TContext = unknown, TData = unknown> implements ResponseModalDeps<TContext, TData> {
   private _terms: Term<TContext, TData>[] = [];
   private _instructions: Instruction<TContext, TData>[] = [];
   private _tools: Tool<TContext, TData>[] = [];
@@ -78,10 +78,15 @@ export class Agent<TContext = any, TData = any> {
   private _persistenceManager: PersistenceManager<TData> | undefined;
   private _routingEngine: FlowRouter<TContext, TData>;
   private _responseModal: ResponseModal<TContext, TData>;
-  private _currentSession?: SessionState<TData>;
   private _knowledgeBase: Record<string, unknown> = {};
   private _schema?: StructuredSchema;
-  private _collectedData: Partial<TData> = {};
+  /**
+   * Staging buffer for data set before any session exists (initialData and
+   * pre-session updateCollectedData calls). Consumed when a session is
+   * created; once a session exists, `session.data` is the single source of
+   * truth and this buffer stays empty.
+   */
+  private _pendingData: Partial<TData> = {};
   private _compactionOptions?: CompactionOptions;
   private _promptSectionCache: PromptSectionCache;
 
@@ -232,13 +237,10 @@ export class Agent<TContext = any, TData = any> {
           );
         }
       }
-      this._collectedData = { ...options.initialData };
-      logger.debug("[Agent] Initial data set:", this._collectedData);
+      this._pendingData = { ...options.initialData };
+      logger.debug("[Agent] Initial data set:", this._pendingData);
     }
 
-    // Initialize current session if provided
-    this._currentSession = options.session;
-
     // Initialize prompt section cache
     this._promptSectionCache = new PromptSectionCache(options.promptCache);
 
@@ -338,25 +340,35 @@ export class Agent<TContext = any, TData = any> {
       logger.debug("[Agent] Compaction options initialized and validated");
     }
 
-    // Initialize session manager with reference to this agent for bidirectional sync
+    // Initialize session manager — the single owner of the live session
     this.session = new SessionManager<TData>(this._persistenceManager, this);
 
+    // Adopt an explicitly provided session
+    if (options.session) {
+      this.session.syncSession(options.session);
+    }
+
     // Store sessionId for later use in getOrCreate calls
     if (options.sessionId) {
       this.session.setDefaultSessionId(options.sessionId);
-      // The session will be loaded on first getOrCreate call
-      this.session.getOrCreate(options.sessionId).then((session) => {
-        // Sync session data to agent collected data
-        if (session.data && Object.keys(session.data).length > 0) {
-          this._collectedData = { ...session.data };
-          logger.debug("[Agent] Synced session data to collected data:", this._collectedData);
-        }
-      }).catch((err) => {
+      // The session will be loaded on first getOrCreate call; session.data
+      // is the source of truth, so no data sync is needed here
+      this.session.getOrCreate(options.sessionId).catch((err) => {
         logger.error("Failed to start session", err);
       });
     }
   }
 
+  /**
+   * Drain the pre-session data staging buffer.
+   * @internal Called by SessionManager when a session is created or loaded.
+   */
+  consumePendingData(): Partial<TData> {
+    const pending = this._pendingData;
+    this._pendingData = {};
+    return pending;
+  }
+
   /**
    * Validate the agent-level schema structure
    * @private
@@ -523,16 +535,19 @@ export class Agent<TContext = any, TData = any> {
   }
 
   /**
-   * Get the current collected data
+   * Get the current collected data.
+   * Reads from the live session when one exists; otherwise from the
+   * pre-session staging buffer.
    */
   getCollectedData(): Partial<TData> {
-    // Ensure agent collected data is synced with session
-    this.syncSessionDataToCollectedData();
-    return { ...this._collectedData };
+    const session = this.session.current;
+    return session ? { ...session.data } : { ...this._pendingData };
   }
 
   /**
-   * Update collected data with validation
+   * Update collected data with validation.
+   * Writes to the live session when one exists; otherwise stages the data
+   * for the session that will be created.
    */
   async updateCollectedData(updates: Partial<TData>): Promise<void> {
     // Validate the updates
@@ -548,31 +563,24 @@ export class Agent<TContext = any, TData = any> {
       logger.warn(`[Agent] Data validation warnings: ${warningMessages}`);
     }
 
-    // Merge updates with current data
-    const previousData = { ...this._collectedData };
-    this._collectedData = {
-      ...this._collectedData,
+    const session = this.session.current;
+    const previousData = session ? { ...session.data } : { ...this._pendingData };
+
+    let newData: Partial<TData> = {
+      ...previousData,
       ...updates
     };
 
     // Trigger agent-level lifecycle hook if configured
     if (this.options.hooks?.onDataUpdate) {
-      this._collectedData = await this.options.hooks.onDataUpdate(
-        this._collectedData,
-        previousData
-      );
+      newData = await this.options.hooks.onDataUpdate(newData, previousData);
     }
 
-    // Update current session if it exists to keep it in sync
-    if (this._currentSession) {
-      this._currentSession = mergeCollected(this._currentSession, this._collectedData);
-    }
-
-    // Also update the session manager's session data (avoid circular call)
-    const sessionManagerSession = this.session.current;
-    if (sessionManagerSession) {
-      sessionManagerSession.data = { ...this._collectedData };
-      sessionManagerSession.metadata!.lastUpdatedAt = new Date();
+    if (session) {
+      session.data = newData;
+      session.metadata!.lastUpdatedAt = new Date();
+    } else {
+      this._pendingData = newData;
     }
 
     logger.debug("[Agent] Collected data updated:", updates);
@@ -743,18 +751,19 @@ export class Agent<TContext = any, TData = any> {
   }
 
   /**
-   * Get the current session (if set)
+   * Get the current session (if set). Delegates to the SessionManager —
+   * the single owner of the live session.
    */
-  get currentSession(): SessionState | undefined {
-    return this._currentSession;
+  get currentSession(): SessionState<TData> | undefined {
+    return this.session.current;
   }
 
   /**
    * Set the current session for convenience methods
    * Set to undefined to clear the current session
    */
-  set currentSession(value: SessionState | undefined) {
-    this._currentSession = value;
+  set currentSession(value: SessionState<TData> | undefined) {
+    this.session.syncSession(value);
     this._promptSectionCache.invalidateAll();
   }
 
@@ -895,8 +904,8 @@ export class Agent<TContext = any, TData = any> {
    * Add a tool to the agent using the unified Tool interface
    * Creates and adds the tool to agent scope in one operation
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  addTool<TResult = any>(
+   
+  addTool<TResult = unknown>(
     tool: Tool<TContext, TData, TResult>
   ): this {
     // Validate tool before adding
@@ -913,8 +922,8 @@ export class Agent<TContext = any, TData = any> {
   /**
    * Register multiple tools at the agent level
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  registerTools<TResult = any>(tools: Tool<TContext, TData, TResult>[]): this {
+   
+  registerTools<TResult = unknown>(tools: Tool<TContext, TData, TResult>[]): this {
     tools.forEach((tool) => {
       // Validate each tool before adding
       if (!tool || !tool.id || !tool.handler) {
@@ -940,9 +949,10 @@ export class Agent<TContext = any, TData = any> {
     } as TContext;
 
     // Trigger flow-specific lifecycle hook if configured and session has current flow
-    if (this._currentSession?.currentFlow) {
+    const activeSession = this.session.current;
+    if (activeSession?.currentFlow) {
       const currentFlow = this._flows.find(
-        (r) => r.id === this._currentSession!.currentFlow?.id
+        (r) => r.id === activeSession.currentFlow?.id
       );
       if (
         currentFlow?.hooks?.onContextUpdate &&
@@ -1001,10 +1011,8 @@ export class Agent<TContext = any, TData = any> {
       ));
     }
 
-    // Update agent's collected data to stay in sync
-    this._collectedData = { ...newCollected };
-
-    // Return updated session
+    // Return updated session — session.data is the single source of truth,
+    // so no agent-side copy is kept
     return mergeCollected(session, newCollected);
   }
 
@@ -1127,33 +1135,10 @@ export class Agent<TContext = any, TData = any> {
   }
 
   /**
-   * Sync session data to agent collected data
-   * @internal Used to keep agent and session data in sync
-   */
-  private syncSessionDataToCollectedData(): void {
-    const sessionData = this.session.getData();
-    if (sessionData && Object.keys(sessionData).length > 0) {
-      this._collectedData = { ...sessionData };
-      logger.debug("[Agent] Synced session data to collected data:", this._collectedData);
-    }
-  }
-
-  /**
-   * Get collected data from current session or agent-level collected data
-   * @returns The collected data from the current session or agent-level data
+   * Get collected data from the current session (or the pre-session staging
+   * buffer when no session exists yet). Alias of getCollectedData().
    */
   getData(): Partial<TData> {
-    // Ensure agent collected data is synced with session
-    this.syncSessionDataToCollectedData();
-
-    // If we have a current session, use session data
-    if (this._currentSession) {
-      // With agent-level data, all flows share the same data structure
-      // No need for flow-specific data access
-      return (this._currentSession.data) || {};
-    }
-
-    // Otherwise, return agent-level collected data
     return this.getCollectedData();
   }
 
@@ -1184,7 +1169,7 @@ export class Agent<TContext = any, TData = any> {
     target: string | Directive<TContext, TData>,
     session?: SessionState<TData>
   ): Promise<SessionState<TData>> {
-    const targetSession = session || this._currentSession;
+    const targetSession = session || this.session.current;
 
     if (!targetSession) {
       throw new Error(
@@ -1239,8 +1224,8 @@ export class Agent<TContext = any, TData = any> {
     };
 
     // Update current session in place if no explicit session was passed
-    if (!session && this._currentSession) {
-      this._currentSession = updatedSession;
+    if (!session && this.session.current) {
+      this.session.syncSession(updatedSession);
     }
 
     logger.debug(

package/src/core/AutoChainExecutor.ts

@@ -21,7 +21,13 @@ import { FlowConfigurationError, Step } from "./Step";
 import { Flow } from "./Flow";
 import { enterStep, mergeCollected, logger } from "../utils";
 import { createTemplateContext } from "../utils/template";
-import type { StoppedReason } from "../types/flow";
+import type {
+    StoppedReason,
+    BranchMap,
+    BranchEntry,
+    BranchPredicateContext,
+} from "../types/flow";
+import { evaluateIfPredicates } from "../utils/condition";
 
 /**
  * The directive-like object that `prepare` may return on auto-steps.
@@ -40,39 +46,6 @@ export interface AutoStepPrepareResult {
     complete?: boolean;
 }
 
-/**
- * A branch predicate context passed to `if` functions.
- */
-interface BranchPredicateContext<TContext, TData> {
-    data: Partial<TData> | undefined;
-    context: TContext;
-    session: SessionState<TData>;
-    history: Event[];
-}
-
-/**
- * A branch `then` target — either a string step/flow id or a directive object.
- */
-type BranchThen = string | { goToStep?: string; goTo?: string } | undefined;
-
-/**
- * A branch entry on a step. Supports code predicates (`if`), AI predicates (`when`),
- * and a target (`then`).
- */
-interface BranchEntry<TContext, TData> {
-    if?: ((ctx: BranchPredicateContext<TContext, TData>) => boolean | Promise<boolean>) | Array<(ctx: BranchPredicateContext<TContext, TData>) => boolean | Promise<boolean>>;
-    when?: string;
-    then?: BranchThen;
-}
-
-/**
- * Structural type for a step that may have branches (accessed via cast).
- */
-interface StepWithBranches<TContext, TData> {
-    branches?: BranchEntry<TContext, TData>[];
-    onEnter?: (context: TContext, data: Partial<TData> | undefined) => Promise<unknown>;
-}
-
 /**
  * Result of running the auto-chain.
  */
@@ -250,10 +223,9 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
             }
 
             // STEP 6: branches resolution (if step has branches)
-            const stepWithBranches = step as unknown as StepWithBranches<TContext, TData>;
-            if (stepWithBranches.branches && Array.isArray(stepWithBranches.branches) && stepWithBranches.branches.length > 0) {
+            if (step.branches && step.branches.length > 0) {
                 const branchTarget = await this.evaluateBranches(
-                    stepWithBranches.branches,
+                    step.branches,
                     session,
                     context,
                     history
@@ -302,7 +274,9 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
         let merged: AutoStepPrepareResult | undefined;
 
         // onEnter (future hook — not yet in StepOptions, but handle if present)
-        const stepWithHooks = step as unknown as StepWithBranches<TContext, TData>;
+        const stepWithHooks = step as Step<TContext, TData> & {
+            onEnter?: (context: TContext, data: Partial<TData> | undefined) => Promise<unknown>;
+        };
         if (typeof stepWithHooks.onEnter === 'function') {
             const onEnterResult = await stepWithHooks.onEnter(context, session.data);
             if (onEnterResult && typeof onEnterResult === 'object') {
@@ -370,7 +344,7 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
      * context (no LLM call). If a branch entry has only `when`, it is skipped.
      */
     private async evaluateBranches(
-        branches: BranchEntry<TContext, TData>[],
+        branches: BranchMap<TContext, TData>,
         session: SessionState<TData>,
         context: TContext,
         history: Event[]
@@ -385,20 +359,12 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
 
             // Code predicate evaluation
             if (entry.if) {
-                const predicates = Array.isArray(entry.if) ? entry.if : [entry.if];
-                const predicateContext: BranchPredicateContext<TContext, TData> = { data: session.data, context, session, history };
-
-                let allPassed = true;
-                for (const predicate of predicates) {
-                    if (typeof predicate === 'function') {
-                        const result = await predicate(predicateContext);
-                        if (!result) {
-                            allPassed = false;
-                            break;
-                        }
-                    }
-                }
-
+                const predicateContext: BranchPredicateContext<TContext, TData> = {
+                    data: session.data, context, session, history,
+                };
+                const allPassed = await evaluateIfPredicates<BranchPredicateContext<TContext, TData>>(
+                    entry.if, predicateContext, "AutoChainExecutor"
+                );
                 if (!allPassed) continue;
 
                 // If entry also has `when`, skip it in auto-step context (no LLM available)
@@ -426,14 +392,18 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
      * Resolve a branch entry's `then` value to a string target.
      * Handles both string targets and Directive objects.
      */
-    private resolveBranchThen(then: BranchThen): string | undefined {
+    private resolveBranchThen(then: BranchEntry<TContext, TData>["then"]): string | undefined {
         if (typeof then === 'string') {
             return then;
         }
-        // Directive object — extract position field
+        // Directive object — extract position field (string or object form)
         if (then && typeof then === 'object') {
-            if (then.goToStep) return then.goToStep;
-            if (then.goTo) return then.goTo;
+            if (then.goToStep) {
+                return typeof then.goToStep === 'string' ? then.goToStep : then.goToStep.step;
+            }
+            if (then.goTo) {
+                return typeof then.goTo === 'string' ? then.goTo : then.goTo.flow;
+            }
         }
         return undefined;
     }

package/src/core/BranchEvaluator.ts

@@ -10,23 +10,23 @@
 
 import type {
     BranchMap,
-    BranchPredicate,
     BranchPredicateContext,
     Directive,
 } from "../types/flow";
 import type { AiProvider } from "../types/ai";
 import type { Event } from "../types/history";
 import { eventsToHistory, logger } from "../utils";
+import { splitWhenConditions, evaluateIfPredicates, type WhenConditionGroups } from "../utils/condition";
 
 /**
  * The AI condition evaluator function signature.
- * Accepts an array of condition strings (OR semantics) and returns
- * whether any condition is satisfied.
+ * Accepts split condition strings and returns whether the condition passes:
+ * (no positives OR any positive is satisfied) AND no exclusion is satisfied.
  *
  * This is the same evaluation mechanism used by `step.when` — condition
  * strings are evaluated by the AI provider against the conversation context.
  */
-export type AiConditionEvaluator = (conditions: string[]) => Promise<boolean>;
+export type AiConditionEvaluator = (conditions: WhenConditionGroups) => Promise<boolean>;
 
 /**
  * Creates an `AiConditionEvaluator` bound to a provider and conversation context.
@@ -50,22 +50,28 @@ export function createAiConditionEvaluator<TContext = unknown>(
     history: Event[],
     context: TContext,
 ): AiConditionEvaluator {
-    return async (conditions: string[]): Promise<boolean> => {
-        if (conditions.length === 0) {
+    return async (conditions: WhenConditionGroups): Promise<boolean> => {
+        if (conditions.positive.length === 0 && conditions.negative.length === 0) {
             return true;
         }
 
-        const conditionText = conditions.length === 1
-            ? conditions[0]
-            : conditions.map((c, i) => `${i + 1}. ${c}`).join("\n");
+        const positiveText = conditions.positive.length === 0
+            ? "None. Treat the positive side as satisfied unless an exclusion matches."
+            : conditions.positive.map((c, i) => `${i + 1}. ${c}`).join("\n");
+        const negativeText = conditions.negative.length === 0
+            ? "None."
+            : conditions.negative.map((c, i) => `${i + 1}. ${c}`).join("\n");
 
         const prompt = [
-            "Evaluate whether the following condition(s) are met based on the conversation so far.",
+            "Evaluate whether the following condition rule passes based on the conversation so far.",
             "",
-            "Condition(s):",
-            conditionText,
+            "Positive condition(s) (OR):",
+            positiveText,
             "",
-            "Return JSON with a single boolean field `result`: true if ANY condition is satisfied, false otherwise.",
+            "Exclusion condition(s) (OR, any match inhibits):",
+            negativeText,
+            "",
+            "Return JSON with a single boolean field `result`: true only when (there are no positive conditions OR ANY positive condition is satisfied) AND NO exclusion condition is satisfied.",
         ].join("\n");
 
         const result = await provider.generateMessage<TContext, { result: boolean }>({
@@ -78,7 +84,7 @@ export function createAiConditionEvaluator<TContext = unknown>(
                     properties: {
                         result: {
                             type: "boolean",
-                            description: "Whether any condition is met based on the conversation context",
+                            description: "Whether the positive/exclusion condition rule passes based on the conversation context",
                         },
                     },
                     required: ["result"],
@@ -122,19 +128,9 @@ export async function evaluateBranches<TContext = unknown, TData = unknown>(
 
             // Code predicate first (free evaluation)
             if (entry.if) {
-                const predicates: BranchPredicate<TContext, TData>[] = Array.isArray(entry.if)
-                    ? entry.if
-                    : [entry.if];
-
-                let ifPassed = true;
-                for (const predicate of predicates) {
-                    const result = await predicate(ctx);
-                    if (!result) {
-                        ifPassed = false;
-                        break;
-                    }
-                }
-
+                const ifPassed = await evaluateIfPredicates<BranchPredicateContext<TContext, TData>>(
+                    entry.if, ctx, "BranchEvaluator"
+                );
                 if (!ifPassed) {
                     continue; // skip this entry; do NOT evaluate `when`
                 }
@@ -142,9 +138,7 @@ export async function evaluateBranches<TContext = unknown, TData = unknown>(
 
             // AI condition (costs tokens — only reached if `if` passed or was absent)
             if (entry.when) {
-                const conditions: string[] = Array.isArray(entry.when)
-                    ? entry.when
-                    : [entry.when];
+                const conditions = splitWhenConditions(entry.when);
 
                 const aiResult = await evaluateAi(conditions);
                 if (!aiResult) {

package/src/core/Flow.ts

@@ -19,6 +19,7 @@ import type { StepResult } from "../types/flow";
 import type { ConditionWhen, ConditionIf } from "../types/flow";
 
 import { generateFlowId, logger } from "../utils";
+import { splitWhenConditions } from "../utils/condition";
 
 import { Step, FlowConfigurationError } from "./Step";
 import { Agent } from './Agent'
@@ -246,7 +247,8 @@ export class Flow<TContext = unknown, TData = unknown> {
   /**
    * Evaluate when/if conditions using the v2 split logic.
    * `if` (code predicate) evaluates first (free); `when` (AI) evaluates only when `if` passes.
-   * `if` predicates use AND semantics. `when` strings use OR semantics.
+   * `if` predicates use AND semantics. Non-`!` `when` strings use OR semantics;
+   * `!` strings are exclusions where any match inhibits activation.
    * When both fields are set, the passing `if` gate and AI match are combined with AND.
    */
   async evaluateWhen(
@@ -257,6 +259,7 @@ export class Flow<TContext = unknown, TData = unknown> {
       return {
         programmaticResult: true,
         aiContextStrings: [],
+        aiExclusionStrings: [],
         hasProgrammaticConditions: false,
       };
     }
@@ -277,6 +280,7 @@ export class Flow<TContext = unknown, TData = unknown> {
             return {
               programmaticResult: false,
               aiContextStrings: [],
+              aiExclusionStrings: [],
               hasProgrammaticConditions: true,
             };
           }
@@ -285,6 +289,7 @@ export class Flow<TContext = unknown, TData = unknown> {
           return {
             programmaticResult: false,
             aiContextStrings: [],
+            aiExclusionStrings: [],
             hasProgrammaticConditions: true,
           };
         }
@@ -293,10 +298,11 @@ export class Flow<TContext = unknown, TData = unknown> {
 
     // `if` passed (or was absent) — now evaluate `when` (AI-evaluated strings)
     if (this.when) {
-      const whenStrings = Array.isArray(this.when) ? this.when : [this.when];
+      const whenConditions = splitWhenConditions(this.when);
       return {
         programmaticResult: true,
-        aiContextStrings: whenStrings,
+        aiContextStrings: whenConditions.positive,
+        aiExclusionStrings: whenConditions.negative,
         hasProgrammaticConditions: !!this.if,
       };
     }
@@ -305,6 +311,7 @@ export class Flow<TContext = unknown, TData = unknown> {
     return {
       programmaticResult: true,
       aiContextStrings: [],
+      aiExclusionStrings: [],
       hasProgrammaticConditions: true,
     };
   }