@falai/agent 2.6.1 → 2.7.0

package/src/core/Agent.ts

@@ -205,8 +205,14 @@ export class Agent<TContext = unknown, TData = unknown> implements ResponseModal
       this.signalProcessor = undefined;
     }
 
-    // Set log level based on debug option
+    // Set log level based on debug option. NOTE: loglevel's default logger is
+    // process-global — one agent enabling debug turns on DEBUG for every agent
+    // in the process. Warned so multi-tenant embedders aren't surprised.
     if (options.debug) {
+      logger.warn(
+        `[Agent] "${options.name}" enabled debug logging via the PROCESS-GLOBAL loglevel level. ` +
+        `Every agent in this process now logs at DEBUG. Scope logging in your host if needed.`
+      );
       logger.setLevel(LoggerLevel.DEBUG);
     }
 
@@ -868,6 +874,26 @@ export class Agent<TContext = unknown, TData = unknown> implements ResponseModal
       }
     }
 
+    // Overlap detection: warn (don't throw) when the incoming flow's
+    // requiredFields intersect another registered flow's — the schema is
+    // agent-level, so both flows complete together and one is silently
+    // excluded from routing.
+    if (options.requiredFields && options.requiredFields.length > 0) {
+      const incoming = new Set(options.requiredFields.map(String));
+      for (const existing of this._flows) {
+        const shared = (existing.requiredFields ?? [])
+          .map(String)
+          .filter((f) => incoming.has(f));
+        if (shared.length > 0) {
+          logger.warn(
+            `[FlowConfigurationError] Overlapping requiredFields: flows "${existing.title}" and "${options.title}" share [${shared.join(', ')}]. ` +
+            `The schema is agent-level, so data collected for one flow marks the other complete and excludes it from routing. ` +
+            `Give each flow distinct requiredFields, or set \`reentrant: true\` on flows that legitimately share fields.`
+          );
+        }
+      }
+    }
+
     const flow = new Flow<TContext, TData>(options, this);
 
     // Validate that step collect fields reference valid schema keys
@@ -1151,12 +1177,20 @@ export class Agent<TContext = unknown, TData = unknown> implements ResponseModal
    *
    * String form desugars to `{ goTo: target }`.
    *
+   * Durability: with a persistence adapter and autoSave configured (the
+   * defaults), the queued directive is persisted immediately — safe for
+   * out-of-process callers like webhooks or cron. Without an adapter it is
+   * memory-only, as is `persistence.autoSave: false` (then persisting before
+   * the next turn is the caller's job).
+   *
    * @param target - Flow ID/title string (desugars to `{ goTo: target }`) or a full Directive
    * @param session - Session to update (uses current session if not provided)
    * @returns Updated session with `pendingDirective` set
    *
    * @throws FlowConfigurationError if the string target doesn't match any flow
    * @throws FlowConfigurationError if the directive fails validation
+   * @throws SessionConflictError when persistence is enabled and another writer
+   * moved the stored session since this copy was loaded
    *
    * @example
    * // String shorthand — desugars to { goTo: 'Feedback' }
@@ -1166,7 +1200,6 @@ export class Agent<TContext = unknown, TData = unknown> implements ResponseModal
    * // Full directive
    * const updated = await agent.dispatch({ goTo: 'Billing', reply: 'Transferring you now.' }, session);
    */
-  // eslint-disable-next-line @typescript-eslint/require-await
   async dispatch(
     target: string | Directive<TContext, TData>,
     session?: SessionState<TData>
@@ -1225,6 +1258,19 @@ export class Agent<TContext = unknown, TData = unknown> implements ResponseModal
       },
     };
 
+    // Durability: with an adapter + autoSave configured, dispatch persists
+    // immediately — webhooks/cron run out-of-process from the responder, and a
+    // memory-only queue would evaporate with this process. The save stamps the
+    // new version back onto updatedSession, so the next turn's auto-save CAS
+    // stays clean. Persisting BEFORE the in-memory sync keeps the existing
+    // invariant: a throwing dispatch leaves the session untouched.
+    if (this._persistenceManager && this.options.persistence?.autoSave !== false) {
+      await this._persistenceManager.saveSessionState(updatedSession.id, updatedSession);
+      logger.debug(
+        `[Agent] Dispatched directive persisted to adapter for session ${updatedSession.id}`
+      );
+    }
+
     // Update current session in place if no explicit session was passed
     if (!session && this.session.current) {
       this.session.syncSession(updatedSession);

package/src/core/AutoChainExecutor.ts

@@ -15,10 +15,11 @@
  * Implements Algorithm 1 from `.kiro/specs/auto-steps/design.md`.
  */
 
-import type { SessionState } from "../types";
+import type { Directive, SessionState } from "../types";
 import type { Event } from "../types/history";
 import { FlowConfigurationError, Step } from "./Step";
 import { Flow } from "./Flow";
+import { flow } from "./flow-namespace";
 import { enterStep, mergeCollected, logger } from "../utils";
 import { createTemplateContext } from "../utils/template";
 import type {
@@ -31,20 +32,13 @@ import { evaluateIfPredicates } from "../utils/condition";
 
 /**
  * The directive-like object that `prepare` may return on auto-steps.
- * This is a structural subset of Directive (pre-LLM fields).
+ * A structural subset of Directive (pre-LLM + position fields), so results
+ * merge through the canonical Algorithm 4 (`flow.merge`).
  */
-export interface AutoStepPrepareResult {
-    dataUpdate?: Record<string, unknown>;
-    contextUpdate?: Record<string, unknown>;
-    halt?: boolean;
-    reply?: string;
-    /** Position-changing: jump to a step within the current flow. */
-    goToStep?: string;
-    /** Position-changing: jump to another flow. */
-    goTo?: string;
-    /** Position-changing: mark the flow as complete. */
-    complete?: boolean;
-}
+export type AutoStepPrepareResult<TContext = unknown, TData = unknown> = Pick<
+    Directive<TContext, TData>,
+    "dataUpdate" | "contextUpdate" | "halt" | "reply" | "goToStep" | "goTo" | "complete"
+>;
 
 /**
  * Result of running the auto-chain.
@@ -53,7 +47,7 @@ export interface AutoChainResult<TContext = unknown, TData = unknown> {
     /** The interactive step to hand off to the LLM path (undefined if chain ended without one). */
     resolvedStep?: Step<TContext, TData>;
     /** The merged directive from the halting auto-step's prepare (only set when stoppedReason = 'halt'). */
-    mergedDirective?: AutoStepPrepareResult;
+    mergedDirective?: AutoStepPrepareResult<TContext, TData>;
     /** Why the chain stopped, if it didn't reach an interactive step normally. */
     stoppedReason?: StoppedReason;
     /** Updated session after all auto-step state writes. */
@@ -192,10 +186,24 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
 
                 // STEP 5: position-changing directive (goToStep, goTo, complete)
                 if (merged.goToStep) {
-                    const targetStep = flow.getStep(merged.goToStep);
+                    // String form targets the current flow; object form carrying
+                    // a different `flow` defers to the pipeline for cross-flow
+                    // resolution (same as goTo).
+                    const goTarget = typeof merged.goToStep === "string"
+                        ? { step: merged.goToStep, flowId: undefined }
+                        : { step: merged.goToStep.step, flowId: merged.goToStep.flow };
+                    if (goTarget.flowId && goTarget.flowId !== flow.id) {
+                        return {
+                            resolvedStep: step,
+                            mergedDirective: merged,
+                            stoppedReason: 'goto',
+                            session,
+                        };
+                    }
+                    const targetStep = flow.getStep(goTarget.step);
                     if (!targetStep) {
                         throw new FlowConfigurationError(
-                            `[FlowConfigurationError] Auto-step "${step.id}" goToStep targets unknown step: "${merged.goToStep}" does not exist in the current flow. ` +
+                            `[FlowConfigurationError] Auto-step "${step.id}" goToStep targets unknown step: "${goTarget.step}" does not exist in the current flow. ` +
                             `Check the step id or use goTo to target a different flow.`
                         );
                     }
@@ -263,26 +271,15 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
     }
 
     /**
-     * Run onEnter and prepare hooks for an auto-step, collecting any
+     * Run the prepare hook for an auto-step, collecting any
      * Directive return values (pre-LLM fields honored).
      */
     private async runStepHooks(
         step: Step<TContext, TData>,
         session: SessionState<TData>,
         context: TContext
-    ): Promise<AutoStepPrepareResult | undefined> {
-        let merged: AutoStepPrepareResult | undefined;
-
-        // onEnter (future hook — not yet in StepOptions, but handle if present)
-        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') {
-                merged = this.mergeDirectives(merged, onEnterResult as AutoStepPrepareResult);
-            }
-        }
+    ): Promise<AutoStepPrepareResult<TContext, TData> | undefined> {
+        let merged: AutoStepPrepareResult<TContext, TData> | undefined;
 
         // prepare hook — for auto-steps, prepare may return a Directive with pre-LLM fields
         if (step.prepare) {
@@ -296,7 +293,7 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
                 );
                 // prepare may return void or a directive-like object
                 if (prepareResult && typeof prepareResult === 'object') {
-                    merged = this.mergeDirectives(merged, prepareResult as AutoStepPrepareResult);
+                    merged = this.mergeDirectives(merged, prepareResult as AutoStepPrepareResult<TContext, TData>);
                 }
             } else {
                 // Tool reference (string or Tool object) — for auto-steps, tool-based
@@ -312,27 +309,17 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
     }
 
     /**
-     * Merge two directive-like objects. Later values override earlier ones
-     * for scalar fields; object fields (dataUpdate, contextUpdate) are deep-merged.
+     * Merge two directive-like objects via the canonical Algorithm 4 merge —
+     * one algorithm shared with tools, hooks and signals.
      */
     private mergeDirectives(
-        base: AutoStepPrepareResult | undefined,
-        incoming: AutoStepPrepareResult
-    ): AutoStepPrepareResult {
+        base: AutoStepPrepareResult<TContext, TData> | undefined,
+        incoming: AutoStepPrepareResult<TContext, TData>
+    ): AutoStepPrepareResult<TContext, TData> {
         if (!base) return { ...incoming };
-        return {
-            dataUpdate: incoming.dataUpdate
-                ? { ...(base.dataUpdate || {}), ...incoming.dataUpdate }
-                : base.dataUpdate,
-            contextUpdate: incoming.contextUpdate
-                ? { ...(base.contextUpdate || {}), ...incoming.contextUpdate }
-                : base.contextUpdate,
-            halt: incoming.halt ?? base.halt,
-            reply: incoming.reply ?? base.reply,
-            goTo: incoming.goTo ?? base.goTo,
-            goToStep: incoming.goToStep ?? base.goToStep,
-            complete: incoming.complete ?? base.complete,
-        };
+        // AutoStepPrepareResult is a structural subset of Directive, so both
+        // sides flow through the canonical merge directly — no casts needed.
+        return flow.merge<TContext, TData>(base, incoming);
     }
 
     /**

package/src/core/CompactionEngine.ts

@@ -180,6 +180,27 @@ export class CompactionEngine {
         }
     }
 
+    /**
+     * Adjust the left edge of a preserved window so it never begins with an
+     * orphaned tool result — a role:'tool' message whose assistant tool_calls
+     * parent lies outside the window. Providers reject such histories at the
+     * next request.
+     *
+     * The preserve count is a target, not a hard guarantee: when the naive
+     * message-count boundary would split an assistant/tool pair, the window
+     * grows left just enough to keep the pair together.
+     */
+    private static alignPreserveStart(
+        history: HistoryItem[],
+        start: number
+    ): number {
+        let aligned = Math.max(0, Math.min(start, history.length));
+        while (aligned > 0 && history[aligned].role === "tool") {
+            aligned--;
+        }
+        return aligned;
+    }
+
     /**
      * Aggressive truncation fallback: remove oldest messages (no LLM needed).
      * Keeps only the most recent messages that fit within the token budget.
@@ -191,11 +212,16 @@ export class CompactionEngine {
         const threshold = options.maxTokens * options.compactionThreshold;
         const preserveCount = options.preserveRecentCount;
 
-        // Always preserve the last preserveRecentCount messages
-        const preserved = history.slice(-preserveCount);
+        // Always preserve the last ~preserveRecentCount messages (aligned so
+        // the window never opens on an orphaned tool result)
+        const preserveStart = CompactionEngine.alignPreserveStart(
+            history,
+            Math.max(0, history.length - preserveCount)
+        );
+        const preserved = history.slice(preserveStart);
 
         // Try to keep as many older messages as fit within budget
-        const older = history.slice(0, -preserveCount);
+        const older = history.slice(0, preserveStart);
         const result: HistoryItem[] = [];
 
         // Add older messages from most recent backwards until we'd exceed budget
@@ -219,7 +245,9 @@ export class CompactionEngine {
      * Layer 3 (micro_compact): Compress verbose tool outputs inline
      * Layer 4 (auto_compact): Summarize old messages via LLM provider
      *
-     * The last `preserveRecentCount` messages are NEVER modified or removed.
+     * The last `preserveRecentCount` messages are NEVER modified or removed
+     * (the preserved window may extend slightly further left so it never
+     * splits an assistant/tool pair at its boundary).
      */
     static async checkAndCompact(
         history: HistoryItem[],
@@ -277,8 +305,14 @@ export class CompactionEngine {
         }
 
         // Layer 4: Auto-compact (summarize old messages via LLM)
-        const oldMessages = microCompacted.slice(0, -preserveCount);
-        const recentMessages = microCompacted.slice(-preserveCount);
+        // preserveRecentCount is a target, not a hard guarantee: the window's
+        // left edge is aligned so it never opens on an orphaned tool result.
+        const preserveStart = CompactionEngine.alignPreserveStart(
+            microCompacted,
+            Math.max(0, microCompacted.length - preserveCount)
+        );
+        const oldMessages = microCompacted.slice(0, preserveStart);
+        const recentMessages = microCompacted.slice(preserveStart);
 
         const summary = await CompactionEngine.summarizeMessages(
             oldMessages,

package/src/core/FlowRouter.ts

@@ -919,6 +919,18 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
         logger.debug(`[FlowRouter] Selected route: ${selectedFlow.title}`);
         updatedSession = this.enterFlowIfNeeded(updatedSession, selectedFlow);
       }
+    } else {
+      // Routing LLM output could not be parsed into the expected structured
+      // shape (no `flows` payload). The turn degrades to a fallback response
+      // with the flow position untouched — surface that loudly instead of
+      // failing silently.
+      const rawSnippet = (routingResult.message ?? "").trim().slice(0, 120);
+      logger.warn(
+        `[FlowRouter] Routing output unparseable: routing LLM returned no structured "flows" payload` +
+          `${rawSnippet ? `; raw output: "${rawSnippet}"` : ""}. ` +
+          `This turn degrades to a generic fallback response and the flow position is left unchanged. ` +
+          `Check the provider's structured-output/JSON support or inspect the routing prompt for schema violations.`
+      );
     }
 
     return {
@@ -1041,25 +1053,39 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
     }
 
     // Apply sticky routing: if there's a current route, only switch if the
-    // best alternative exceeds the current flow's score by the configured margin
+    // best alternative exceeds the current flow's score by the configured margin.
+    // The margin applies symmetrically: even when the current flow has no
+    // weighted entry (the AI scored it 0 or omitted it), switching away
+    // requires clearing the margin over a zero baseline — shared agent-level
+    // data can otherwise zero out a mid-conversation flow.
     if (currentRouteId) {
       const currentEntry = weightedScores.find(e => e.route.id === currentRouteId);
       const bestEntry = weightedScores[0];
 
-      if (currentEntry && bestEntry.route.id !== currentRouteId) {
-        if (bestEntry.score < currentEntry.score + switchMargin) {
+      if (bestEntry && bestEntry.route.id !== currentRouteId) {
+        const currentScore = currentEntry ? currentEntry.score : 0;
+
+        if (bestEntry.score < currentScore + switchMargin) {
+          const currentRoute =
+            currentEntry?.route ?? routes.find(r => r.id === currentRouteId);
+          if (currentRoute) {
+            logger.debug(
+              `[FlowRouter] Staying on current flow: ${currentRoute.title} ` +
+              `(current: ${currentScore}, best alternative: ${bestEntry.score}, ` +
+              `margin required: ${switchMargin})`
+            );
+            return currentRoute;
+          }
           logger.debug(
-            `[FlowRouter] Staying on current flow: ${currentEntry.route.title} ` +
-            `(current: ${currentEntry.score}, best alternative: ${bestEntry.score}, ` +
-            `margin required: ${switchMargin})`
+            `[FlowRouter] Current flow ${currentRouteId} is no longer routable — selecting best alternative: ${bestEntry.route.title}`
+          );
+        } else {
+          logger.debug(
+            `[FlowRouter] Switching flow: ${currentEntry?.route.title ?? currentRouteId} → ${bestEntry.route.title} ` +
+            `(current: ${currentScore}, alternative: ${bestEntry.score}, ` +
+            `margin: ${switchMargin})`
           );
-          return currentEntry.route;
         }
-        logger.debug(
-          `[FlowRouter] Switching flow: ${currentEntry.route.title} → ${bestEntry.route.title} ` +
-          `(current: ${currentEntry.score}, alternative: ${bestEntry.score}, ` +
-          `margin: ${switchMargin})`
-        );
       }
     }
 

package/src/core/ResponseGenerationError.ts

@@ -21,13 +21,10 @@ export class ResponseGenerationError extends Error {
         message: string,
         public readonly details?: ResponseGenerationErrorDetails
     ) {
-        super(message);
+        // Native `cause` chain: `err.cause` is the original error, so
+        // consumers can reach ProviderError.code etc. without string matching.
+        super(message, { cause: details?.originalError });
         this.name = 'ResponseGenerationError';
-
-        // Preserve stack trace from original error if available
-        if (details?.originalError instanceof Error && details.originalError.stack) {
-            this.stack = `${this.stack}\nCaused by: ${details.originalError.stack}`;
-        }
     }
 
     /**