@falai/agent 2.6.1 → 3.0.0

package/src/core/SessionFinalizer.ts

@@ -11,12 +11,13 @@
  * 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";
+import type { AgentOptions, SessionState } from "../types/index.js";
+import type { CompactionOptions } from "../types/compaction.js";
+import type { PersistenceManager } from "./PersistenceManager.js";
+import type { StepLifecycle } from "./StepLifecycle.js";
+import { flow } from "./flow-namespace.js";
+import { CompactionEngine } from "./CompactionEngine.js";
+import { boundConversationHistory, DEFAULT_MAX_HISTORY_MESSAGES, logger } from "../utils/index.js";
 
 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

@@ -6,13 +6,13 @@
  */
 
 import log from "loglevel";
-import type { SessionState } from "../types/session";
-import type { History, HistoryItem } from "../types/history";
-import { PersistenceManager } from "./PersistenceManager";
-import { CompactionEngine } from "./CompactionEngine";
-import type { PersistenceAdapter } from "../types/persistence";
-import type { Agent } from "./Agent";
-import { createSession } from "../utils";
+import type { SessionState } from "../types/session.js";
+import type { History, HistoryItem } from "../types/history.js";
+import { PersistenceManager } from "./PersistenceManager.js";
+import { CompactionEngine } from "./CompactionEngine.js";
+import type { PersistenceAdapter } from "../types/persistence.js";
+import type { Agent } from "./Agent.js";
+import { boundConversationHistory, createSession, DEFAULT_MAX_HISTORY_MESSAGES } from "../utils/index.js";
 
 /**
  * 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/SignalCoordinator.ts

@@ -12,13 +12,13 @@
  *   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";
+import type { Directive, Event, SessionState } from "../types/index.js";
+import type { SignalFiring } from "../types/signals.js";
+import type { SignalProcessor } from "./SignalProcessor.js";
+import type { Flow } from "./Flow.js";
+import type { Step } from "./Step.js";
+import { hasDirectivePositionField } from "./ResponsePipeline.js";
+import { enterFlow, enterStep, mergeCollected, logger } from "../utils/index.js";
 
 /** Result of a signal phase run (pre or post). */
 export interface SignalPhaseResult<TContext = unknown, TData = unknown> {

package/src/core/SignalEvaluator.ts

@@ -9,16 +9,16 @@
  * @module SignalEvaluator
  */
 
-import type { AiProvider } from "../types/ai";
-import type { Event } from "../types/history";
-import type { SessionState } from "../types/session";
+import type { AiProvider } from "../types/ai.js";
+import type { Event } from "../types/history.js";
+import type { SessionState } from "../types/session.js";
 import type {
     Signal,
     SignalPredicate,
     SignalPredicateContext,
-} from "../types/signals";
-import { eventsToHistory, logger } from "../utils";
-import { splitWhenConditions, evaluateIfPredicates } from "../utils/condition";
+} from "../types/signals.js";
+import { eventsToHistory, logger } from "../utils/index.js";
+import { splitWhenConditions, evaluateIfPredicates } from "../utils/condition.js";
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Types

package/src/core/SignalProcessor.ts

@@ -11,11 +11,11 @@
  * @module SignalProcessor
  */
 
-import type { AiProvider } from "../types/ai";
-import type { Event } from "../types/history";
-import { MessageRole as MessageRoleEnum } from "../types/history";
-import type { SessionState } from "../types/session";
-import type { Directive } from "../types/flow";
+import type { AiProvider } from "../types/ai.js";
+import type { Event } from "../types/history.js";
+import { MessageRole as MessageRoleEnum } from "../types/history.js";
+import type { SessionState } from "../types/session.js";
+import type { Directive } from "../types/flow.js";
 import type {
     Signal,
     SignalContext,
@@ -23,9 +23,10 @@ import type {
     SignalFiring,
     SignalPredicateContext,
     SignalTriggerState,
-} from "../types/signals";
-import type { SignalEvaluator } from "./SignalEvaluator";
-import { logger } from "../utils";
+} from "../types/signals.js";
+import type { SignalEvaluator } from "./SignalEvaluator.js";
+import { flow } from "./flow-namespace.js";
+import { logger } from "../utils/index.js";
 
 /** Recorded on `SignalFiring.extractionError` when a matched extraction-mode
  * signal yields no payload (model omitted the field or returned null). */
@@ -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

@@ -9,14 +9,15 @@ import type {
   Instruction,
   Tool,
   PrepareResult,
-} from "../types";
-import type { SessionState } from "../types/session";
-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'
+} from "../types/index.js";
+import type { SessionState } from "../types/session.js";
+import type { StepResult, BranchSpec, BranchResult } from "../types/flow.js";
+import { ToolScope, Template, TemplateContext } from "../types/index.js";
+import type { ConditionWhen, ConditionIf } from "../types/flow.js";
+import { generateStepId, logger } from "../utils/index.js";
+import { splitWhenConditions } from "../utils/condition.js";
+import { Agent } from './Agent.js'
+import { flow } from "./flow-namespace.js";
 
 /**
  * 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`