@falai/agent 2.6.1 → 3.0.0

package/src/core/StepLifecycle.ts

@@ -4,13 +4,43 @@
  * 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 { Flow } from "./Flow";
-import type { Step } from "./Step";
-import type { ToolManager } from "./ToolManager";
-import { logger } from "../utils";
+import type { Directive, PrepareResult, SessionState, Tool } from "../types/index.js";
+import type { Flow } from "./Flow.js";
+import type { Step } from "./Step.js";
+import type { ToolManager } from "./ToolManager.js";
+import { flow } from "./flow-namespace.js";
+import { logger } from "../utils/index.js";
+
+/** 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(
@@ -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;
     }
 }

package/src/core/StreamingToolExecutor.ts

@@ -11,6 +11,7 @@
  */
 
 import log from "loglevel";
+import type { Directive } from "../types/index.js";
 import type {
     ToolCallRequest,
     ToolExecutionUpdate,
@@ -18,8 +19,9 @@ import type {
     ToolContext,
     Tool,
     TrackedTool,
-} from "../types/tool";
-import { evaluateToolGates } from "./toolGates";
+} from "../types/tool.js";
+import { evaluateToolGates } from "./toolGates.js";
+import { isToolResultLike, extractResultDirectives } from "../utils/index.js";
 
 /** Options for the StreamingToolExecutor */
 interface StreamingToolExecutorOptions {
@@ -257,8 +259,18 @@ export class StreamingToolExecutor<TContext = unknown, TData = unknown> {
                 this.parentSignal.addEventListener("abort", parentAbortHandler, { once: true });
             }
 
+            // Per-call context so ctx.dispatch() emissions attribute to THIS
+            // tool even while siblings run concurrently on the shared context.
+            const dispatchedDirectives: Directive[] = [];
+            const callContext: ToolContext<TContext, TData> = {
+                ...this.toolContext,
+                dispatch: (directive) => {
+                    dispatchedDirectives.push(directive);
+                },
+            };
+
             // Execute the tool handler
-            const result = await tool.handler(this.toolContext, toolCall.arguments);
+            const result = await tool.handler(callContext, toolCall.arguments);
 
             // Clean up abort listeners
             if (batchAbortController) {
@@ -282,6 +294,15 @@ export class StreamingToolExecutor<TContext = unknown, TData = unknown> {
             // Normalize the result
             const executionResult = this.normalizeResult(result, tool);
 
+            // Merge ctx.dispatch() emissions with result-carried directives —
+            // the same collection the sequential ToolManager.executeTool does.
+            if (dispatchedDirectives.length > 0) {
+                executionResult.directives = [
+                    ...(executionResult.directives ?? []),
+                    ...dispatchedDirectives,
+                ];
+            }
+
             // Apply per-tool maxResultSizeChars truncation (Req 9.4)
             const truncatedResult = this.applyResultTruncation(executionResult, tool);
 
@@ -326,18 +347,22 @@ export class StreamingToolExecutor<TContext = unknown, TData = unknown> {
         result: unknown,
         tool: Tool<TContext, TData>
     ): ToolExecutionResult {
-        if (
-            result &&
-            typeof result === "object" &&
-            ("data" in result || "success" in result || "error" in result)
-        ) {
+        // Only SEMANTIC markers identify a ToolResult — bare `{data}` / `{error}`
+        // shapes are indistinguishable from ordinary business payloads and are
+        // wrapped as raw results instead (shared guard with ToolManager).
+        if (isToolResultLike(result)) {
             const r = result as Record<string, unknown>;
+            // A handler may return `{ directive }` (singular shorthand) or
+            // `{ directives }` — normalized via the shared extractor so the
+            // concurrent path honors them identically to sequential execution.
+            const directives = extractResultDirectives(result);
             return {
                 success: r.success !== false,
                 data: r.data,
                 error: r.error as string | undefined,
                 contextUpdate: r.contextUpdate as Record<string, unknown> | undefined,
                 dataUpdate: r.dataUpdate as Record<string, unknown> | undefined,
+                ...(directives.length > 0 ? { directives } : {}),
                 metadata: {
                     toolId: tool.id,
                     ...(r.meta as Record<string, unknown> | undefined),