@falai/agent 2.2.4 → 2.4.1

package/src/core/SessionFinalizer.ts

@@ -0,0 +1,78 @@
+/**
+ * SessionFinalizer owns end-of-turn session finalization: deterministic
+ * history compaction, persistence auto-save, the step `finalize` hook,
+ * and syncing the finalized session back to the agent's live session.
+ *
+ * Every turn finalizes exactly once: the non-streaming path in
+ * `respond()` after generation completes; the streaming path in the
+ * final-chunk interception loop after the post-signal phase (so
+ * post-phase session mutations are persisted), with only the
+ * pre-routing signal/auto-chain halt chunks finalizing at their own
+ * yield sites.
+ */
+
+import type { AgentOptions, SessionState } from "../types";
+import type { CompactionOptions } from "../types/compaction";
+import type { PersistenceManager } from "./PersistenceManager";
+import type { StepLifecycle } from "./StepLifecycle";
+import { CompactionEngine } from "./CompactionEngine";
+import { logger } from "../utils";
+
+export class SessionFinalizer<TContext = unknown, TData = unknown> {
+    constructor(
+        private readonly deps: {
+            getCompactionOptions: () => CompactionOptions | undefined;
+            getPersistenceManager: () => PersistenceManager<TData> | undefined;
+            getAgentOptions: () => AgentOptions<TContext, TData>;
+            getCurrentSession: () => SessionState<TData> | undefined;
+            setCurrentSession: (session: SessionState<TData>) => void;
+            stepLifecycle: StepLifecycle<TContext, TData>;
+            /** ResponseModalOptions.enableAutoSave (undefined means enabled). */
+            enableAutoSave?: boolean;
+        }
+    ) { }
+
+    /**
+     * Handle session persistence and finalization.
+     */
+    async finalize(session: SessionState<TData>, context: TContext): Promise<void> {
+        // Deterministic compaction: runs on every finalize (not just addMessage)
+        // so respond()-only callers get bounded history too
+        const compactionOptions = this.deps.getCompactionOptions();
+        if (compactionOptions && session.history && session.history.length > 0) {
+            try {
+                const result = await CompactionEngine.checkAndCompact(session.history, compactionOptions);
+                if (result.strategy !== 'none') {
+                    session.history = result.history;
+                    logger.info(
+                        `[SessionFinalizer] Compaction applied: strategy='${result.strategy}', ` +
+                        `estimatedTokens=${result.estimatedTokens}, messagesCompacted=${result.messagesCompacted}`
+                    );
+                }
+            } catch (error) {
+                logger.warn("[SessionFinalizer] Compaction failed at finalize, continuing without compaction", error);
+            }
+        }
+
+        // Auto-save session step to persistence if configured
+        const persistenceManager = this.deps.getPersistenceManager();
+        const agentOptions = this.deps.getAgentOptions();
+        if (
+            persistenceManager &&
+            session.id &&
+            (this.deps.enableAutoSave !== false && agentOptions.persistence?.autoSave !== false)
+        ) {
+            await persistenceManager.saveSessionState(session.id, session);
+            logger.debug(`[SessionFinalizer] Auto-saved session step to persistence: ${session.id}`);
+        }
+
+        // Execute finalize function
+        await this.deps.stepLifecycle.runFinalize(session, context);
+
+        // Update current session if we have one
+        const currentSession = this.deps.getCurrentSession();
+        if (currentSession) {
+            this.deps.setCurrentSession(session);
+        }
+    }
+}

package/src/core/SessionManager.ts

@@ -79,6 +79,14 @@ export class SessionManager<TData = unknown> {
           effectiveSessionId
         );
         if (session) {
+          // Loaded session data wins over anything staged before it existed
+          const pending = this.agent?.consumePendingData();
+          if (pending && Object.keys(pending).length > 0) {
+            log.debug(
+              "SessionManager: discarding pre-session staged data in favor of loaded session state",
+              pending
+            );
+          }
           this.currentSession = session;
           return session;
         }
@@ -99,6 +107,9 @@ export class SessionManager<TData = unknown> {
     const session = createSession<TData>({
       id: sessionId,
       history: [], // Session manages its own history
+      // Seed with data staged before the session existed (initialData,
+      // pre-session updateCollectedData calls)
+      data: this.agent?.consumePendingData() ?? ({} as Partial<TData>),
     });
 
     this.currentSession = session;
@@ -237,15 +248,16 @@ export class SessionManager<TData = unknown> {
     await this.getOrCreate();
 
     if (this.currentSession && data) {
-      this.currentSession.data = {
-        ...this.currentSession.data,
-        ...data,
-      };
-      this.currentSession.metadata!.lastUpdatedAt = new Date();
-
-      // Synchronize with agent's collected data for bidirectional sync
       if (this.agent) {
-        await this.agent.updateCollectedData(this.currentSession.data);
+        // Route through the agent so schema validation and onDataUpdate
+        // hooks run; it writes into this session's data directly
+        await this.agent.updateCollectedData(data);
+      } else {
+        this.currentSession.data = {
+          ...this.currentSession.data,
+          ...data,
+        };
+        this.currentSession.metadata!.lastUpdatedAt = new Date();
       }
 
       // Auto-save to persistence
@@ -306,7 +318,7 @@ export class SessionManager<TData = unknown> {
    *
    * @internal Called from ResponseModal after stream()/generate() completion
    */
-  syncSession(session: SessionState<TData>): void {
+  syncSession(session: SessionState<TData> | undefined): void {
     this.currentSession = session;
   }
 

package/src/core/SignalCoordinator.ts

@@ -0,0 +1,263 @@
+/**
+ * SignalCoordinator owns the signal pre/post phase orchestration for a turn:
+ *
+ * - `runPrePhase()` / `runPostPhase()` — delegation to the SignalProcessor,
+ *   returning a stable empty shape when no processor is configured.
+ * - `applyPositionDirective()` — applies a pre-phase directive's position
+ *   field (goTo, goToStep, complete, abort, reset) as the turn's routing
+ *   decision, discarding the router's result.
+ * - `applyPostPhase()` — runs the post phase and applies its directive to
+ *   the turn result in one step: session updates, pendingDirective for
+ *   position fields (no mid-turn re-entry per D6), and the reply override
+ *   of the user-visible message.
+ */
+
+import type { Directive, Event, SessionState } from "../types";
+import type { SignalFiring } from "../types/signals";
+import type { SignalProcessor } from "./SignalProcessor";
+import type { Flow } from "./Flow";
+import type { Step } from "./Step";
+import { hasDirectivePositionField } from "./ResponsePipeline";
+import { enterFlow, enterStep, mergeCollected, logger } from "../utils";
+
+/** Result of a signal phase run (pre or post). */
+export interface SignalPhaseResult<TContext = unknown, TData = unknown> {
+    firings: SignalFiring<TContext, TData>[];
+    updatedSession: SessionState<TData>;
+    mergedDirective: Directive<TContext, TData> | undefined;
+}
+
+export class SignalCoordinator<TContext = unknown, TData = unknown> {
+    constructor(
+        private readonly deps: {
+            getFlows: () => Flow<TContext, TData>[];
+            signalProcessor?: SignalProcessor<TContext, TData>;
+        }
+    ) { }
+
+    /** Whether a signal processor is configured (zero-cost path when absent). */
+    get enabled(): boolean {
+        return this.deps.signalProcessor !== undefined;
+    }
+
+    /**
+     * PRE-SIGNAL PHASE — Evaluates pre/both signals in parallel with routing.
+     *
+     * Delegates to `signalProcessor.runPreSignalPhase(...)` when configured.
+     * When no signal processor is present (zero-cost path), returns a stable
+     * empty shape so callers don't need to branch.
+     *
+     * @requirements 2.1, 2.3, 8.6, 13.3
+     */
+    async runPrePhase(
+        session: SessionState<TData>,
+        context: TContext,
+        history: Event[],
+    ): Promise<SignalPhaseResult<TContext, TData>> {
+        if (!this.deps.signalProcessor) {
+            return { firings: [], updatedSession: session, mergedDirective: undefined };
+        }
+        const result = await this.deps.signalProcessor.runPreSignalPhase({ session, history, context });
+        return {
+            firings: result.firings,
+            updatedSession: result.updatedSession,
+            mergedDirective: result.mergedDirective,
+        };
+    }
+
+    /**
+     * POST-SIGNAL PHASE — Evaluates post/both signals after finalize/onComplete.
+     *
+     * Delegates to `signalProcessor.runPostSignalPhase(...)` when configured.
+     * When no signal processor is present, returns a stable empty shape.
+     *
+     * Post-phase signals see the complete turn result: assistant message in history,
+     * collected data, tool results. Position directives from this phase set
+     * `session.pendingDirective` (no mid-turn re-entry per D6 decision).
+     *
+     * Pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`) are already
+     * dropped inside `runPostSignalPhase` per Phase 4.5 — this seam does NOT
+     * re-introduce them.
+     *
+     * @requirements 9.1, 9.2, 9.3, 9.4
+     */
+    async runPostPhase(
+        session: SessionState<TData>,
+        context: TContext,
+        history: Event[],
+    ): Promise<SignalPhaseResult<TContext, TData>> {
+        if (!this.deps.signalProcessor) {
+            return { firings: [], updatedSession: session, mergedDirective: undefined };
+        }
+        const result = await this.deps.signalProcessor.runPostSignalPhase({ session, history, context });
+        return {
+            firings: result.firings,
+            updatedSession: result.updatedSession,
+            mergedDirective: result.mergedDirective,
+        };
+    }
+
+    /**
+     * Run the post phase and apply its merged directive to the turn result:
+     * session updates from the phase, `pendingDirective` for position fields
+     * (Requirement 9.3, no mid-turn re-entry per D6), and the reply override
+     * of the user-visible message (undefined means "leave it unchanged"; an
+     * empty string is an explicit replacement).
+     *
+     * @requirements 9.1, 9.2, 9.3, 9.4
+     */
+    async applyPostPhase(params: {
+        session: SessionState<TData>;
+        context: TContext;
+        historyEvents: Event[];
+        message: string;
+    }): Promise<{
+        session: SessionState<TData>;
+        message: string;
+        firings: SignalFiring<TContext, TData>[];
+        /** True when the directive's `reply` replaced the message. */
+        replyOverridden: boolean;
+    }> {
+        const postResult = await this.runPostPhase(
+            params.session, params.context, params.historyEvents,
+        );
+        let session = postResult.updatedSession;
+
+        // Requirement 9.3: Post-phase position directive sets session.pendingDirective
+        if (postResult.mergedDirective && hasDirectivePositionField(postResult.mergedDirective)) {
+            session = { ...session, pendingDirective: postResult.mergedDirective };
+        }
+
+        const replyOverridden = postResult.mergedDirective?.reply !== undefined;
+        const message = replyOverridden
+            ? postResult.mergedDirective!.reply!
+            : params.message;
+
+        return { session, message, firings: postResult.firings, replyOverridden };
+    }
+
+    /**
+     * Apply a signal's position directive (goTo, goToStep, complete, abort, reset).
+     * Discards routing result and uses the signal's position decision.
+     *
+     * @requirements 8.3
+     */
+    applyPositionDirective(
+        signalResult: {
+            firings: SignalFiring<TContext, TData>[];
+            updatedSession: SessionState<TData>;
+            mergedDirective: Directive<TContext, TData> | undefined;
+        },
+    ): {
+        selectedFlow?: Flow<TContext, TData>;
+        selectedStep?: Step<TContext, TData>;
+        responseDirectives?: string[];
+        session: SessionState<TData>;
+        isFlowComplete: boolean;
+        signalFirings?: SignalFiring<TContext, TData>[];
+        signalPreDirective?: Directive<TContext, TData>;
+        signalHalted?: boolean;
+        signalHaltReply?: string;
+    } {
+        const directive = signalResult.mergedDirective!;
+        let session = signalResult.updatedSession;
+        const flows = this.deps.getFlows();
+        let selectedFlow: Flow<TContext, TData> | undefined;
+        let selectedStep: Step<TContext, TData> | undefined;
+        let isFlowComplete = false;
+
+        // Apply data updates if present alongside position
+        if (directive.dataUpdate) {
+            session = mergeCollected(session, directive.dataUpdate);
+        }
+
+        if (directive.goTo) {
+            const flowTarget = typeof directive.goTo === 'string'
+                ? directive.goTo
+                : directive.goTo.flow ?? directive.goTo.step;
+
+            if (flowTarget) {
+                const targetFlow = flows.find(f => f.id === flowTarget || f.title === flowTarget);
+                if (targetFlow) {
+                    session = enterFlow(session, targetFlow.id, targetFlow.title);
+                    selectedFlow = targetFlow;
+
+                    if (typeof directive.goTo === 'object' && directive.goTo.step) {
+                        const targetStep = targetFlow.getStep(directive.goTo.step);
+                        if (targetStep) {
+                            session = enterStep(session, targetStep.id, targetStep.description);
+                            selectedStep = targetStep;
+                        }
+                    }
+                } else {
+                    logger.warn(`[Signals] Pre-phase goTo target not found: "${flowTarget}". Falling back to no flow.`);
+                }
+            }
+        } else if (directive.goToStep) {
+            const stepTarget = typeof directive.goToStep === 'string'
+                ? directive.goToStep
+                : directive.goToStep.step;
+            const flowTarget = typeof directive.goToStep === 'object'
+                ? directive.goToStep.flow
+                : undefined;
+
+            if (flowTarget) {
+                const targetFlow = flows.find(f => f.id === flowTarget || f.title === flowTarget);
+                if (targetFlow) {
+                    session = enterFlow(session, targetFlow.id, targetFlow.title);
+                    selectedFlow = targetFlow;
+                    const targetStep = targetFlow.getStep(stepTarget);
+                    if (targetStep) {
+                        session = enterStep(session, targetStep.id, targetStep.description);
+                        selectedStep = targetStep;
+                    }
+                }
+            } else if (session.currentFlow) {
+                const currentFlow = flows.find(f => f.id === session.currentFlow?.id);
+                if (currentFlow) {
+                    selectedFlow = currentFlow;
+                    const targetStep = currentFlow.getStep(stepTarget);
+                    if (targetStep) {
+                        session = enterStep(session, targetStep.id, targetStep.description);
+                        selectedStep = targetStep;
+                    }
+                }
+            }
+        } else if (directive.complete) {
+            isFlowComplete = true;
+        } else if (directive.abort) {
+            // Abort — no flow, session cleared or marked
+            isFlowComplete = true;
+        } else if (directive.reset) {
+            if (session.currentFlow) {
+                const currentFlow = flows.find(f => f.id === session.currentFlow?.id);
+                if (currentFlow) {
+                    selectedFlow = currentFlow;
+                    const resetStep = typeof directive.reset === 'object' && directive.reset.step
+                        ? directive.reset.step
+                        : undefined;
+                    if (resetStep) {
+                        const targetStep = currentFlow.getStep(resetStep);
+                        if (targetStep) {
+                            session = enterStep(session, targetStep.id, targetStep.description);
+                            selectedStep = targetStep;
+                        }
+                    } else {
+                        const initialStep = currentFlow.initialStep;
+                        session = enterStep(session, initialStep.id, initialStep.description);
+                        selectedStep = initialStep;
+                    }
+                }
+            }
+        }
+
+        return {
+            selectedFlow,
+            selectedStep,
+            session,
+            isFlowComplete,
+            signalFirings: signalResult.firings,
+            signalPreDirective: signalResult.mergedDirective || undefined,
+        };
+    }
+}

package/src/core/SignalEvaluator.ts

@@ -18,6 +18,7 @@ import type {
     SignalPredicateContext,
 } from "../types/signals";
 import { eventsToHistory, logger } from "../utils";
+import { splitWhenConditions, evaluateIfPredicates } from "../utils/condition";
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Types
@@ -44,8 +45,8 @@ export interface EvaluateSignalsParams<TContext = unknown, TData = unknown> {
 /**
  * Builds the classifier prompt for a batch of signals.
  *
- * Splits `when` entries by `!` prefix at render time:
- * - Non-`!` → "TRIGGER WHEN (ANY matches)"
+ * Splits `when` entries with the shared ConditionWhen parser:
+ * - Positive entries → "TRIGGER WHEN (ANY matches)"
  * - `!` entries → prefix stripped, "DO NOT TRIGGER WHEN (ANY inhibits)"
  *
  * Extraction schemas render under "WHEN MATCHED, EXTRACT".
@@ -80,11 +81,11 @@ export function buildSignalClassifierPrompt<TContext = unknown, TData = unknown>
         }
 
         // Split when entries
-        const whenEntries = normalizeWhen(signal.when);
-        const positiveEntries = whenEntries.filter(w => !w.startsWith("!"));
-        const negativeEntries = whenEntries.filter(w => w.startsWith("!")).map(w => w.slice(1));
+        const whenConditions = splitWhenConditions(signal.when);
+        const positiveEntries = whenConditions.positive;
+        const negativeEntries = whenConditions.negative;
 
-        const isUnconditional = whenEntries.length === 0;
+        const isUnconditional = positiveEntries.length === 0 && negativeEntries.length === 0;
 
         if (isUnconditional && signal.extract) {
             // Unconditional + extract → ALWAYS EXTRACT
@@ -94,6 +95,8 @@ export function buildSignalClassifierPrompt<TContext = unknown, TData = unknown>
             for (const entry of positiveEntries) {
                 lines.push(`    • ${entry}`);
             }
+        } else if (negativeEntries.length > 0) {
+            lines.push(`  TRIGGER WHEN: no positive condition; trigger unless an exclusion matches.`);
         }
 
         if (negativeEntries.length > 0) {
@@ -207,23 +210,9 @@ export class SignalEvaluator<TContext = unknown, TData = unknown> {
         predicates: SignalPredicate<TContext, TData> | SignalPredicate<TContext, TData>[],
         ctx: SignalPredicateContext<TContext, TData>,
     ): Promise<boolean> {
-        const predicateArray = Array.isArray(predicates) ? predicates : [predicates];
-
-        for (let i = 0; i < predicateArray.length; i++) {
-            try {
-                const result = await predicateArray[i](ctx);
-                if (!result) {
-                    return false;
-                }
-            } catch (error) {
-                logger.error(
-                    `[Signals] Predicate at index ${i} threw: ${error instanceof Error ? error.message : String(error)}`,
-                );
-                return false;
-            }
-        }
-
-        return true;
+        return evaluateIfPredicates<SignalPredicateContext<TContext, TData>>(
+            predicates, ctx, "Signals"
+        );
     }
 
     /**
@@ -350,12 +339,6 @@ export function splitIntoBatches<T>(items: T[], batchSize: number): T[][] {
 // Internal helpers
 // ──────────────────────────────────────────────────────────────────────────────
 
-/** Normalize `when` to a string array. */
-function normalizeWhen(when: string | string[] | undefined): string[] {
-    if (!when) return [];
-    return Array.isArray(when) ? when : [when];
-}
-
 /**
  * Render extraction schema properties as human-readable lines for the prompt.
  * Lists each property's name, type, and constraints (enum, min/max, format).

package/src/core/Step.ts

@@ -15,6 +15,7 @@ import type { StepResult, BranchSpec, BranchResult } from "../types/flow";
 import { ToolScope, Template, TemplateContext } from "../types";
 import type { ConditionWhen, ConditionIf } from "../types/flow";
 import { generateStepId, logger } from "../utils";
+import { splitWhenConditions } from "../utils/condition";
 import { Agent } from './Agent'
 
 /**
@@ -448,7 +449,8 @@ export class Step<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(
@@ -456,6 +458,7 @@ export class Step<TContext = unknown, TData = unknown> {
   ): Promise<{
     shouldActivate: boolean;
     aiContextStrings: string[];
+    aiExclusionStrings: string[];
     hasProgrammaticConditions: boolean;
   }> {
     // If neither `when` nor `if` is set, step is always eligible
@@ -463,6 +466,7 @@ export class Step<TContext = unknown, TData = unknown> {
       return {
         shouldActivate: true,
         aiContextStrings: [],
+        aiExclusionStrings: [],
         hasProgrammaticConditions: false
       };
     }
@@ -483,6 +487,7 @@ export class Step<TContext = unknown, TData = unknown> {
             return {
               shouldActivate: false,
               aiContextStrings: [],
+              aiExclusionStrings: [],
               hasProgrammaticConditions: true
             };
           }
@@ -491,6 +496,7 @@ export class Step<TContext = unknown, TData = unknown> {
           return {
             shouldActivate: false,
             aiContextStrings: [],
+            aiExclusionStrings: [],
             hasProgrammaticConditions: true
           };
         }
@@ -499,13 +505,14 @@ export class Step<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);
       // `when` strings are handed to the AI — return them as aiContextStrings
       // The programmatic result is true (strings don't fail programmatically;
       // they're scored by the AI at routing time)
       return {
         shouldActivate: true,
-        aiContextStrings: whenStrings,
+        aiContextStrings: whenConditions.positive,
+        aiExclusionStrings: whenConditions.negative,
         hasProgrammaticConditions: !!this.if
       };
     }
@@ -514,6 +521,7 @@ export class Step<TContext = unknown, TData = unknown> {
     return {
       shouldActivate: true,
       aiContextStrings: [],
+      aiExclusionStrings: [],
       hasProgrammaticConditions: true
     };
   }