@falai/agent 2.6.0 → 2.7.0

package/src/core/SessionFinalizer.ts

@@ -15,8 +15,9 @@ import type { AgentOptions, SessionState } from "../types";
 import type { CompactionOptions } from "../types/compaction";
 import type { PersistenceManager } from "./PersistenceManager";
 import type { StepLifecycle } from "./StepLifecycle";
+import { flow } from "./flow-namespace";
 import { CompactionEngine } from "./CompactionEngine";
-import { logger } from "../utils";
+import { boundConversationHistory, DEFAULT_MAX_HISTORY_MESSAGES, logger } from "../utils";
 
 export class SessionFinalizer<TContext = unknown, TData = unknown> {
     constructor(
@@ -36,6 +37,24 @@ export class SessionFinalizer<TContext = unknown, TData = unknown> {
      * Handle session persistence and finalization.
      */
     async finalize(session: SessionState<TData>, context: TContext): Promise<void> {
+        const agentOptions = this.deps.getAgentOptions();
+
+        // Hard history bound — backstop when no compaction is configured (or
+        // after it ran). Unbounded growth eventually bricks the thread at the
+        // provider context limit.
+        const historyCap = agentOptions.maxHistoryMessages ?? DEFAULT_MAX_HISTORY_MESSAGES;
+        if (historyCap > 0 && session.history && session.history.length > historyCap) {
+            const bounded = boundConversationHistory(session.history, historyCap);
+            if (bounded !== session.history) {
+                logger.warn(
+                    `[SessionFinalizer] Session "${session.id}" history exceeded ${historyCap} entries ` +
+                    `(${session.history.length}); trimmed the oldest. Configure compaction for ` +
+                    `summarization instead of truncation, or raise maxHistoryMessages.`
+                );
+                session.history = bounded;
+            }
+        }
+
         // Deterministic compaction: runs on every finalize (not just addMessage)
         // so respond()-only callers get bounded history too
         const compactionOptions = this.deps.getCompactionOptions();
@@ -54,9 +73,23 @@ export class SessionFinalizer<TContext = unknown, TData = unknown> {
             }
         }
 
+        // Execute finalize BEFORE persisting so its state writes (which now
+        // land on this turn's session) are captured by the save below. A
+        // control-flow directive returned by finalize queues on the session —
+        // the pendingDirective applier applies it at the START of the next turn.
+        let finalizeDirective;
+        try {
+            finalizeDirective = await this.deps.stepLifecycle.runFinalize(session, context);
+        } catch (error) {
+            logger.error("[SessionFinalizer] Step finalize hook failed:", error);
+            throw error;
+        }
+        if (finalizeDirective) {
+            flow.queuePending(session, finalizeDirective);
+        }
+
         // Auto-save session step to persistence if configured
         const persistenceManager = this.deps.getPersistenceManager();
-        const agentOptions = this.deps.getAgentOptions();
         if (
             persistenceManager &&
             session.id &&
@@ -66,9 +99,6 @@ export class SessionFinalizer<TContext = unknown, TData = unknown> {
             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) {

package/src/core/SessionManager.ts

@@ -12,7 +12,7 @@ import { PersistenceManager } from "./PersistenceManager";
 import { CompactionEngine } from "./CompactionEngine";
 import type { PersistenceAdapter } from "../types/persistence";
 import type { Agent } from "./Agent";
-import { createSession } from "../utils";
+import { boundConversationHistory, createSession, DEFAULT_MAX_HISTORY_MESSAGES } from "../utils";
 
 /**
  * SessionManager handles session lifecycle and conversation history
@@ -24,6 +24,9 @@ export class SessionManager<TData = unknown> {
   private agent?: Agent<any, TData>;
   private defaultSessionId?: string;
 
+  /** Coalesces concurrent getOrCreate calls for the same session id. */
+  private inflightGets = new Map<string, Promise<SessionState<TData>>>();
+
   constructor(
     persistenceManagerOrAdapter?:
       | PersistenceManager<TData>
@@ -56,7 +59,13 @@ export class SessionManager<TData = unknown> {
 
   /**
    * Core method: getOrCreate handles both existing and new sessions
-   * Works for sessionIds that exist, don't exist, or auto-generated IDs
+   * Works for sessionIds that exist, don't exist, or auto-generated IDs.
+   *
+   * Concurrent calls for the same id are COALESCED into one in-flight load:
+   * the Agent constructor fires an un-awaited getOrCreate while a first turn
+   * may already be starting — without coalescing, both calls can observe a
+   * missing row and create two competing sessions (one blanking the other's
+   * persisted state).
    */
   async getOrCreate(sessionId?: string): Promise<SessionState<TData>> {
     // SECURITY: a non-string sessionId (e.g. `{ $ne: null }` from an HTTP body
@@ -69,6 +78,23 @@ export class SessionManager<TData = unknown> {
     // Use provided sessionId or fall back to default
     const effectiveSessionId = sessionId || this.defaultSessionId;
 
+    const inflightKey = effectiveSessionId || "__auto__";
+    const inflight = this.inflightGets.get(inflightKey);
+    if (inflight) {
+      return inflight;
+    }
+
+    const promise = this.getOrCreateInner(effectiveSessionId).finally(() => {
+      this.inflightGets.delete(inflightKey);
+    });
+    this.inflightGets.set(inflightKey, promise);
+    return promise;
+  }
+
+  private async getOrCreateInner(
+    effectiveSessionId: string | undefined
+  ): Promise<SessionState<TData>> {
+
     // If we already have a session and no sessionId specified, return it
     if (this.currentSession && !effectiveSessionId) {
       return this.currentSession;
@@ -79,27 +105,25 @@ export class SessionManager<TData = unknown> {
       return this.currentSession;
     }
 
-    // If sessionId provided, try to load it first
+    // If sessionId provided, try to load it first. A missing row returns
+    // `null` (→ create below); a FAILED load throws — swallowing it here used
+    // to fall through to create(), which saved a blank session over the
+    // existing row and erased the user's conversation on a transient DB error.
     if (effectiveSessionId && this.persistenceManager) {
-      try {
-        const session = await this.persistenceManager.loadSessionState(
-          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;
+      const session = await this.persistenceManager.loadSessionState(
+        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
+          );
         }
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      } catch (_error) {
-        // Session doesn't exist, will create new one with this ID
+        this.currentSession = session;
+        return session;
       }
     }
 
@@ -150,6 +174,16 @@ export class SessionManager<TData = unknown> {
     };
 
     session.history.push(historyItem);
+    // Same hard bound the finalizer applies — keeps interim auto-saves bounded
+    // on the chat()/stream() path too.
+    const cap = this.agent?.getAgentOptions().maxHistoryMessages ?? DEFAULT_MAX_HISTORY_MESSAGES;
+    if (cap > 0 && session.history) {
+      const bounded = boundConversationHistory(session.history, cap);
+      if (bounded !== session.history) {
+        log.warn(`SessionManager: history exceeded ${cap} entries; trimmed the oldest.`);
+        session.history = bounded;
+      }
+    }
     session.metadata!.lastUpdatedAt = new Date();
 
     // Ensure currentSession is updated

package/src/core/SignalProcessor.ts

@@ -25,6 +25,7 @@ import type {
     SignalTriggerState,
 } from "../types/signals";
 import type { SignalEvaluator } from "./SignalEvaluator";
+import { flow } from "./flow-namespace";
 import { logger } from "../utils";
 
 /** Recorded on `SignalFiring.extractionError` when a matched extraction-mode
@@ -654,90 +655,9 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
     private mergeDirectives(
         directives: SignalDirective<TContext, TData>[],
     ): Directive<TContext, TData> {
-        const merged: Directive<TContext, TData> = {};
-
-        for (const d of directives) {
-            // Position fields — last-write-wins
-            if (d.goTo !== undefined) {
-                merged.goTo = d.goTo;
-                // Clear other position fields
-                delete merged.goToStep;
-                delete merged.complete;
-                delete merged.abort;
-                delete merged.reset;
-            }
-            if (d.goToStep !== undefined) {
-                merged.goToStep = d.goToStep;
-                delete merged.goTo;
-                delete merged.complete;
-                delete merged.abort;
-                delete merged.reset;
-            }
-            if (d.complete !== undefined) {
-                merged.complete = d.complete;
-                delete merged.goTo;
-                delete merged.goToStep;
-                delete merged.abort;
-                delete merged.reset;
-            }
-            if (d.abort !== undefined) {
-                merged.abort = d.abort;
-                delete merged.goTo;
-                delete merged.goToStep;
-                delete merged.complete;
-                delete merged.reset;
-            }
-            if (d.reset !== undefined) {
-                merged.reset = d.reset;
-                delete merged.goTo;
-                delete merged.goToStep;
-                delete merged.complete;
-                delete merged.abort;
-            }
-
-            // halt — last-write-wins
-            if (d.halt !== undefined) {
-                merged.halt = d.halt;
-            }
-
-            // reply — last-write-wins
-            if (d.reply !== undefined) {
-                merged.reply = d.reply;
-            }
-
-            // appendPrompt — array-concat
-            if (d.appendPrompt != null) {
-                merged.appendPrompt = [
-                    ...(merged.appendPrompt ?? []),
-                    ...d.appendPrompt,
-                ];
-            }
-
-            // injectTools — array-concat
-            if (d.injectTools != null) {
-                merged.injectTools = [
-                    ...(merged.injectTools ?? []),
-                    ...d.injectTools,
-                ];
-            }
-
-            // dataUpdate — shallow-merge
-            if (d.dataUpdate != null) {
-                merged.dataUpdate = {
-                    ...(merged.dataUpdate ?? {}),
-                    ...d.dataUpdate,
-                };
-            }
-
-            // contextUpdate — shallow-merge
-            if (d.contextUpdate != null) {
-                merged.contextUpdate = {
-                    ...(merged.contextUpdate ?? {}),
-                    ...d.contextUpdate,
-                };
-            }
-        }
-
-        return merged;
+        // Canonical Algorithm 4 merge — one algorithm shared with tools and
+        // step hooks (position precedence, reply last-wins, state shallow-merge,
+        // halt OR). Empty in, empty ({}) out.
+        return flow.mergeAll(directives) ?? {};
     }
 }

package/src/core/Step.ts

@@ -17,6 +17,7 @@ import type { ConditionWhen, ConditionIf } from "../types/flow";
 import { generateStepId, logger } from "../utils";
 import { splitWhenConditions } from "../utils/condition";
 import { Agent } from './Agent'
+import { flow } from "./flow-namespace";
 
 /**
  * Error thrown when a step's configuration violates auto-step constraints.
@@ -28,6 +29,27 @@ export class FlowConfigurationError extends Error {
   }
 }
 
+/** The function-form of step prepare/finalize. */
+type StepPrepareFn<TContext, TData> = (
+  context: TContext,
+  data?: Partial<TData>
+) => void | PrepareResult<TContext, TData> | Promise<void | PrepareResult<TContext, TData>>;
+
+/**
+ * Merge two handler results (shorthand + hooks.* desugar). Scalar/object
+ * results merge via the canonical Algorithm 4; void/undefined passes through.
+ */
+function mergeHookResults<TContext, TData>(
+  a: void | PrepareResult<TContext, TData>,
+  b: void | PrepareResult<TContext, TData>
+): PrepareResult<TContext, TData> | undefined {
+  if (a == null) return b ?? undefined;
+  if (b == null) return a;
+  // PrepareResult is a structural subset of Directive — the canonical merge
+  // accepts both sides and its output remains a valid PrepareResult.
+  return flow.merge<TContext, TData>(a, b);
+}
+
 /**
  * Represents a step within a route
  */
@@ -89,8 +111,63 @@ export class Step<TContext = unknown, TData = unknown> {
     this.reply = options.reply;
     this.when = options.when;
     this.if = options.if;
-    this.prepare = options.prepare;
-    this.finalize = options.finalize;
+
+    // Desugar `hooks.prepare` / `hooks.finalize` onto the shorthand fields so
+    // both spellings run through the same lifecycle machinery. When both are
+    // declared, both run — the shorthand first, then the hook — with their
+    // directive returns merged via Algorithm 4 (same desugar pattern as
+    // flow-level onComplete).
+    const hooks = options.hooks;
+
+    /** Compose a function-form shorthand with a function-form hook. */
+    const composeWithHook = (
+      base: StepPrepareFn<TContext, TData> | undefined,
+      hook: StepPrepareFn<TContext, TData>
+    ): StepPrepareFn<TContext, TData> => {
+      if (!base) return hook;
+      return async (context, data) =>
+        mergeHookResults<TContext, TData>(
+          await base(context, data),
+          await hook(context, data)
+        );
+    };
+
+    if (hooks?.prepare) {
+      const hookPrepare: StepPrepareFn<TContext, TData> = (context, data) =>
+        hooks.prepare!(context, data);
+      const base = options.prepare;
+      // A tool-reference shorthand cannot compose with a function hook in a
+      // single field — refuse loudly instead of silently dropping one.
+      if (base != null && typeof base !== "function") {
+        throw new FlowConfigurationError(
+          `[FlowConfigurationError] Step "${this.id}" declares both a tool-based prepare and hooks.prepare. A step can only have one prepare handler — remove one or inline the tool call inside the function.`
+        );
+      }
+      this.prepare = composeWithHook(
+        typeof base === "function" ? base : undefined,
+        hookPrepare
+      );
+    } else {
+      this.prepare = options.prepare;
+    }
+
+    if (hooks?.finalize) {
+      const hookFinalize: StepPrepareFn<TContext, TData> = (context, data) =>
+        hooks.finalize!(context, data);
+      const base = options.finalize;
+      if (base != null && typeof base !== "function") {
+        throw new FlowConfigurationError(
+          `[FlowConfigurationError] Step "${this.id}" declares both a tool-based finalize and hooks.finalize. A step can only have one finalize handler — remove one or inline the tool call inside the function.`
+        );
+      }
+      this.finalize = composeWithHook(
+        typeof base === "function" ? base : undefined,
+        hookFinalize
+      );
+    } else {
+      this.finalize = options.finalize;
+    }
+
     this.tools = options.tools;
 
     // Validate when/if split: functions belong on `if`, not `when`

package/src/core/StepLifecycle.ts

@@ -4,14 +4,44 @@
  * A handler may be a function, a registered tool id, or an inline tool.
  * Used by the response prepare phase (prepare) and by SessionFinalizer
  * (finalize).
+ *
+ * Handlers may emit directives three ways: a function's return value,
+ * `ctx.dispatch()` inside a tool, or a `{ directive }` tool return. All are
+ * merged via the canonical Algorithm 4 (`flow.merge`) and validated with
+ * `flow.validate`. State writes (`dataUpdate`/`contextUpdate`) are applied
+ * immediately to the TURN session — never to agent-level live state — so
+ * persistence captures them. Remaining control-flow fields (position fields,
+ * verbatim replies, halts) are returned to the caller to act on.
  */
 
-import type { PrepareResult, SessionState, Tool } from "../types";
+import type { Directive, PrepareResult, SessionState, Tool } from "../types";
 import type { Flow } from "./Flow";
 import type { Step } from "./Step";
 import type { ToolManager } from "./ToolManager";
+import { flow } from "./flow-namespace";
 import { logger } from "../utils";
 
+/** Fields a caller can still act on after state writes have been applied. */
+const CONTROL_FIELDS = [
+    "goTo",
+    "goToStep",
+    "reset",
+    "complete",
+    "abort",
+    "reply",
+    "halt",
+    "appendPrompt",
+    "injectTools",
+] as const;
+
+function hasControlFields(directive: Directive): boolean {
+    return CONTROL_FIELDS.some(
+        (field) =>
+            (directive as Record<string, unknown>)[field] !== undefined &&
+            (directive as Record<string, unknown>)[field] !== null
+    );
+}
+
 export class StepLifecycle<TContext = unknown, TData = unknown> {
     constructor(
         private readonly deps: {
@@ -23,10 +53,14 @@ export class StepLifecycle<TContext = unknown, TData = unknown> {
     ) { }
 
     /**
-     * Execute prepare function for the session's current step if available.
+     * Execute prepare for the session's current step if available.
+     * Returns the merged control-flow directive, if the handler emitted one.
      * Auto-steps are skipped — their prepare is handled by AutoChainExecutor.
      */
-    async runPrepare(session: SessionState<TData>, context: TContext): Promise<void> {
+    async runPrepare(
+        session: SessionState<TData>,
+        context: TContext
+    ): Promise<Directive<TContext, TData> | undefined> {
         if (session.currentFlow && session.currentStep) {
             const currentFlow = this.deps.getFlows().find(
                 (r) => r.id === session.currentFlow?.id
@@ -36,26 +70,31 @@ export class StepLifecycle<TContext = unknown, TData = unknown> {
                 // Skip auto-steps — their prepare is handled by AutoChainExecutor
                 if (currentStep?.auto) {
                     logger.debug(`[StepLifecycle] Skipping pre-routing prepare for auto-step: ${currentStep.id}`);
-                    return;
+                    return undefined;
                 }
                 if (currentStep?.prepare) {
                     logger.debug(`[StepLifecycle] Executing prepare for step: ${currentStep.id}`);
-                    await this.executePrepareFinalize(
+                    return this.executePrepareFinalize(
                         currentStep.prepare,
                         context,
-                        session.data,
+                        session,
                         currentFlow,
                         currentStep
                     );
                 }
             }
         }
+        return undefined;
     }
 
     /**
-     * Execute finalize function for the session's current step if available.
+     * Execute finalize for the session's current step if available.
+     * Returns the merged control-flow directive, if the handler emitted one.
      */
-    async runFinalize(session: SessionState<TData>, context: TContext): Promise<void> {
+    async runFinalize(
+        session: SessionState<TData>,
+        context: TContext
+    ): Promise<Directive<TContext, TData> | undefined> {
         if (session.currentFlow && session.currentStep) {
             const currentFlow = this.deps.getFlows().find(
                 (r) => r.id === session.currentFlow?.id
@@ -66,58 +105,75 @@ export class StepLifecycle<TContext = unknown, TData = unknown> {
                     logger.debug(
                         `[StepLifecycle] Executing finalize for step: ${currentStep.id}`
                     );
-                    await this.executePrepareFinalize(
+                    return this.executePrepareFinalize(
                         currentStep.finalize,
                         context,
-                        session.data,
+                        session,
                         currentFlow,
                         currentStep
                     );
                 }
             }
         }
+        return undefined;
     }
 
     /**
-     * Execute a prepare or finalize function/tool.
+     * Execute a prepare or finalize handler and resolve its emitted directives.
      */
     private async executePrepareFinalize(
         prepareOrFinalize:
             | string
             | Tool<TContext, TData>
-            | ((context: TContext, data?: Partial<TData>) => void | PrepareResult | Promise<void | PrepareResult>)
+            | ((context: TContext, data?: Partial<TData>) => void | PrepareResult<TContext, TData> | Promise<void | PrepareResult<TContext, TData>>)
             | undefined,
         context: TContext,
-        data?: Partial<TData>,
-        flow?: Flow<TContext, TData>,
+        session: SessionState<TData>,
+        flowRef?: Flow<TContext, TData>,
         step?: Step<TContext, TData>
-    ): Promise<void> {
-        if (!prepareOrFinalize) return;
+    ): Promise<Directive<TContext, TData> | undefined> {
+        if (!prepareOrFinalize) return undefined;
+
+        const collected: Directive<TContext, TData>[] = [];
+
+        /** State writes land on the TURN session so persistence captures them. */
+        const writeToSession = (updates: Partial<TData> | Record<string, unknown> | undefined): void => {
+            if (!updates) return;
+            session.data = { ...(session.data ?? {}), ...updates };
+        };
 
         if (typeof prepareOrFinalize === "function") {
-            // It's a function - call it directly
-            await prepareOrFinalize(context, data);
+            // It's a function - call it and honor its return value
+            const result = await prepareOrFinalize(context, session.data);
+            if (result && typeof result === "object") {
+                collected.push(result);
+            }
         } else {
             // It's a tool reference - find and execute the tool
             let tool: Tool<TContext, TData> | undefined;
 
             if (typeof prepareOrFinalize === "string") {
                 // Tool ID - use ToolManager for unified resolution
-                tool = this.deps.toolManager.find(prepareOrFinalize, undefined, step, flow);
+                tool = this.deps.toolManager.find(prepareOrFinalize, undefined, step, flowRef);
             } else {
                 // Tool object - use directly
                 tool = prepareOrFinalize;
             }
 
             if (tool) {
-                // Use ToolManager for unified tool execution
+                // Use ToolManager for unified tool execution. updateData writes
+                // into the turn session (previously it mutated the agent's live
+                // session, losing writes made after the persistence snapshot).
                 const result = await this.deps.toolManager.executeTool({
                     tool,
                     context,
                     updateContext: this.deps.updateContext,
-                    updateData: this.deps.updateData,
+                    updateData: async (updates) => {
+                        writeToSession(updates);
+                        await this.deps.updateData(updates);
+                    },
                     history: [], // Empty history for prepare/finalize
-                    data,
+                    data: session.data,
                 });
 
                 if (!result.success) {
@@ -126,6 +182,16 @@ export class StepLifecycle<TContext = unknown, TData = unknown> {
                     );
                     throw new Error(`Tool execution failed: ${result.error}`);
                 }
+
+                // Collect directives (ctx.dispatch / {directive} returns)
+                if (result.directives?.length) {
+                    collected.push(...(result.directives as Directive<TContext, TData>[]));
+                }
+                // Honor ToolResult-level state updates
+                writeToSession(result.dataUpdate as Partial<TData> | undefined);
+                if (result.contextUpdate) {
+                    await this.deps.updateContext(result.contextUpdate as Partial<TContext>);
+                }
             } else {
                 logger.warn(
                     `[StepLifecycle] Tool not found for prepare/finalize: ${typeof prepareOrFinalize === "string"
@@ -135,5 +201,42 @@ export class StepLifecycle<TContext = unknown, TData = unknown> {
                 );
             }
         }
+
+        if (collected.length === 0) return undefined;
+
+        // Canonical merge + validation — one algorithm shared with tools,
+        // signals, and auto-steps.
+        for (const directive of collected) {
+            flow.validate(directive);
+        }
+        const merged = flow.mergeAll(collected);
+        if (!merged) return undefined;
+
+        // Apply state writes immediately; they are not control flow.
+        writeToSession(merged.dataUpdate);
+        if (merged.contextUpdate) {
+            await this.deps.updateContext(merged.contextUpdate);
+        }
+
+        if (!hasControlFields(merged)) return undefined;
+
+        // Pre-LLM augmentation fields (appendPrompt / injectTools / halt / reply)
+        // have no sink on non-auto steps yet — surface loudly instead of silently
+        // dropping them.
+        if (
+            (merged.appendPrompt?.length || merged.injectTools?.length || merged.halt || merged.reply) &&
+            !step?.auto
+        ) {
+            logger.warn(
+                `[StepLifecycle] Directive from "${step?.id ?? "step"}" ${flowRef ? `in flow "${flowRef.title}" ` : ""}` +
+                `carries pre-LLM fields (appendPrompt/injectTools/halt/reply) that only auto-steps honor today. ` +
+                `Use an auto step for prompt augmentation or a signal handler for halt+reply.`
+            );
+        }
+
+        const control = { ...merged };
+        delete control.dataUpdate;
+        delete control.contextUpdate;
+        return control;
     }
 }