@falai/agent 2.6.1 → 3.0.0

package/dist/cjs/core/ResponseModal.js

@@ -5,17 +5,20 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResponseModal = void 0;
-const ResponseEngine_1 = require("./ResponseEngine");
-const ResponsePipeline_1 = require("./ResponsePipeline");
-const AutoChainExecutor_1 = require("./AutoChainExecutor");
-const StepLifecycle_1 = require("./StepLifecycle");
-const SessionFinalizer_1 = require("./SessionFinalizer");
-const ToolLoopExecutor_1 = require("./ToolLoopExecutor");
-const SignalCoordinator_1 = require("./SignalCoordinator");
-const ResponseGenerationError_1 = require("./ResponseGenerationError");
-const utils_1 = require("../utils");
-const template_1 = require("../utils/template");
-const streamingMessage_1 = require("../utils/streamingMessage");
+const ResponseEngine_js_1 = require("./ResponseEngine.js");
+const ResponsePipeline_js_1 = require("./ResponsePipeline.js");
+const AutoChainExecutor_js_1 = require("./AutoChainExecutor.js");
+const StepLifecycle_js_1 = require("./StepLifecycle.js");
+const SessionFinalizer_js_1 = require("./SessionFinalizer.js");
+const ToolLoopExecutor_js_1 = require("./ToolLoopExecutor.js");
+const flow_namespace_js_1 = require("./flow-namespace.js");
+const SignalCoordinator_js_1 = require("./SignalCoordinator.js");
+const ResponseGenerationError_js_1 = require("./ResponseGenerationError.js");
+const errors_js_1 = require("../types/errors.js");
+const index_js_1 = require("../utils/index.js");
+const template_js_1 = require("../utils/template.js");
+const streamingMessage_js_1 = require("../utils/streamingMessage.js");
+const json_js_1 = require("../utils/json.js");
 /**
  * ResponseModal class that encapsulates all response generation logic
  * Uses unified approach for both streaming and non-streaming responses
@@ -25,24 +28,24 @@ class ResponseModal {
         this.agent = agent;
         this.options = options;
         // Initialize response engine
-        this.responseEngine = new ResponseEngine_1.ResponseEngine(this.agent.promptSectionCache);
+        this.responseEngine = new ResponseEngine_js_1.ResponseEngine(this.agent.promptSectionCache);
         // Signal pre/post phase orchestration
-        this.signalCoordinator = new SignalCoordinator_1.SignalCoordinator({
+        this.signalCoordinator = new SignalCoordinator_js_1.SignalCoordinator({
             getFlows: () => this.agent.getFlows(),
             signalProcessor: this.agent.signalProcessor,
         });
         // Initialize response pipeline with agent dependencies
-        this.responsePipeline = new ResponsePipeline_1.ResponsePipeline(this.agent.getAgentOptions(), () => this.agent.getFlows(), // Pass a function to get flows dynamically
+        this.responsePipeline = new ResponsePipeline_js_1.ResponsePipeline(this.agent.getAgentOptions(), () => this.agent.getFlows(), // Pass a function to get flows dynamically
         this.agent.getFlowRouter(), this.signalCoordinator, this.agent.updateCollectedData.bind(this.agent), () => this.agent.schema);
         // Step prepare/finalize execution, shared by the prepare phase and finalizer
-        this.stepLifecycle = new StepLifecycle_1.StepLifecycle({
+        this.stepLifecycle = new StepLifecycle_js_1.StepLifecycle({
             getFlows: () => this.agent.getFlows(),
             toolManager: this.getToolManager(),
             updateContext: this.agent.updateContext.bind(this.agent),
             updateData: this.agent.updateCollectedData.bind(this.agent),
         });
         // Single owner of end-of-turn finalization (compaction + persistence + sync)
-        this.sessionFinalizer = new SessionFinalizer_1.SessionFinalizer({
+        this.sessionFinalizer = new SessionFinalizer_js_1.SessionFinalizer({
             getCompactionOptions: () => this.agent.getCompactionOptions(),
             getPersistenceManager: () => this.agent.getPersistenceManager(),
             getAgentOptions: () => this.agent.getAgentOptions(),
@@ -52,7 +55,7 @@ class ResponseModal {
             enableAutoSave: this.options?.enableAutoSave,
         });
         // Tool follow-up loop (run tools, ask the LLM again) + streaming batch execution
-        this.toolLoopExecutor = new ToolLoopExecutor_1.ToolLoopExecutor({
+        this.toolLoopExecutor = new ToolLoopExecutor_js_1.ToolLoopExecutor({
             toolManager: this.getToolManager(),
             getAgentOptions: () => this.agent.getAgentOptions(),
             updateContext: this.agent.updateContext.bind(this.agent),
@@ -69,7 +72,7 @@ class ResponseModal {
         // without this, mutations made before the failure leave the live session
         // diverged from persisted state
         const preTurnSession = this.agent.session.current
-            ? (0, utils_1.cloneDeep)(this.agent.session.current)
+            ? (0, index_js_1.cloneDeep)(this.agent.session.current)
             : undefined;
         try {
             // Use unified response preparation and routing
@@ -84,7 +87,14 @@ class ResponseModal {
             if (preTurnSession) {
                 this.agent.session.syncSession(preTurnSession);
             }
-            throw new ResponseGenerationError_1.ResponseGenerationError(`[ResponseGenerationError] Response generation failed: ${error instanceof Error ? error.message : String(error)}. ` +
+            // Typed library errors carry their own semantics (ProviderError.code,
+            // SessionConflictError) — rethrow bare so consumers can branch on
+            // them instead of string-matching. Everything else wraps with the
+            // original attached as `cause`.
+            if (error instanceof errors_js_1.ProviderError || error instanceof errors_js_1.SessionConflictError) {
+                throw error;
+            }
+            throw new ResponseGenerationError_js_1.ResponseGenerationError(`[ResponseGenerationError] Response generation failed: ${error instanceof Error ? error.message : String(error)}. ` +
                 `Check provider configuration and network connectivity.`, { originalError: error, params, phase: 'response_generation' });
         }
     }
@@ -94,7 +104,7 @@ class ResponseModal {
     async *respondStream(params) {
         // Same failed-turn rollback semantics as respond()
         const preTurnSession = this.agent.session.current
-            ? (0, utils_1.cloneDeep)(this.agent.session.current)
+            ? (0, index_js_1.cloneDeep)(this.agent.session.current)
             : undefined;
         try {
             // Use unified response preparation and routing
@@ -112,7 +122,7 @@ class ResponseModal {
                 accumulated: "",
                 done: true,
                 session: params.session || await this.agent.session.getOrCreate(),
-                error: new ResponseGenerationError_1.ResponseGenerationError(`Streaming response failed: ${error instanceof Error ? error.message : String(error)}`, { originalError: error, params, phase: 'streaming' }),
+                error: new ResponseGenerationError_js_1.ResponseGenerationError(`Streaming response failed: ${error instanceof Error ? error.message : String(error)}`, { originalError: error, params, phase: 'streaming' }),
             };
         }
     }
@@ -225,6 +235,44 @@ class ResponseModal {
     getToolManager() {
         return this.agent.tool;
     }
+    /**
+     * Repair-parse a JSON-shaped protocol fragment (truncated output,
+     * fence-wrapped JSON) into a structured payload. Raw protocol fragments
+     * must never surface as the user-visible reply: if the repair parse fails,
+     * fail the turn LOUDLY so the caller's rollback/retry path engages instead
+     * of leaking `{"message": "…` to an end user. Plain prose (not JSON-shaped
+     * at all) never reaches this helper — the call sites gate on the fragment
+     * shape and pass it through untouched.
+     */
+    salvageStructuredOutput(raw, surface) {
+        const salvaged = (0, json_js_1.tryParseJSONResponse)(raw);
+        if (salvaged && typeof salvaged.message === "string") {
+            index_js_1.logger.warn(`[ResponseModal] Salvaged malformed structured output from ${surface} via JSON repair parse.`);
+            return { ...salvaged, message: salvaged.message };
+        }
+        throw ResponseGenerationError_js_1.ResponseGenerationError.fromError(new Error("Model returned a schema-mandated response that could not be parsed as JSON. " +
+            `The ${surface} was failed instead of delivering raw protocol output to the user.`), 'structured_output_malformed', { responseSchemaName: 'response_output' });
+    }
+    /**
+     * Tool-emitted directives (ctx.dispatch / `{directive}` returns): state
+     * writes apply now; control flow queues for the next turn's
+     * pendingDirective applier (same deferred semantics as dispatch()).
+     */
+    async applyToolEmittedDirectives(session, d) {
+        if (d.dataUpdate) {
+            session = (0, index_js_1.mergeCollected)(session, d.dataUpdate);
+        }
+        if (d.contextUpdate) {
+            await this.agent.updateContext(d.contextUpdate);
+        }
+        const control = { ...d };
+        delete control.dataUpdate;
+        delete control.contextUpdate;
+        if (Object.keys(control).length > 0) {
+            flow_namespace_js_1.flow.queuePending(session, control);
+        }
+        return session;
+    }
     /**
      * Collect scoped instructions from agent, flow, and step into a ScopedInstructions value.
      * @private
@@ -245,29 +293,32 @@ class ResponseModal {
      */
     async prepareUnifiedResponseContext(params) {
         try {
-            const { history: simpleHistory, contextOverride, signal } = params;
+            const { history: simpleHistory, contextOverride, signal, message: turnMessage, allowedFlows } = params;
             // Validate input parameters
             if (!simpleHistory) {
-                throw new ResponseGenerationError_1.ResponseGenerationError('[ResponseGenerationError] Missing history: history is required for response generation. ' +
-                    'Pass a valid history array to the respond/stream method.', { params, phase: 'validation' });
+                throw new ResponseGenerationError_js_1.ResponseGenerationError('[ResponseGenerationError] Missing history: history is required for response generation. ' +
+                    'Pass a valid history array (or pass `message` alongside an existing history base).', { params, phase: 'validation' });
             }
+            // `message` is the user turn: appended to what the model sees this
+            // turn AND recorded on the returned session's history.
+            const history = turnMessage
+                ? [...simpleHistory, (0, index_js_1.userMessage)(turnMessage)]
+                : simpleHistory;
             // Convert HistoryItem[] to Event[] for internal processing
-            const historyEvents = (0, utils_1.historyToEvents)(simpleHistory);
-            // Keep original HistoryItem[] format for external APIs
-            const history = simpleHistory;
+            const historyEvents = (0, index_js_1.historyToEvents)(history);
             // Use ResponsePipeline for context and session preparation; context
             // and session are passed explicitly — the pipeline holds no state
             let responseContext;
             try {
                 responseContext = await this.responsePipeline.prepareResponseContext({
                     contextOverride,
-                    session: params.session ? (0, utils_1.cloneDeep)(params.session) : undefined,
+                    session: params.session ? (0, index_js_1.cloneDeep)(params.session) : undefined,
                     currentContext: await this.agent.getContext(),
                     currentSession: this.agent.currentSession,
                 });
             }
             catch (error) {
-                throw ResponseGenerationError_1.ResponseGenerationError.fromError(error, 'pipeline_context_preparation', params);
+                throw ResponseGenerationError_js_1.ResponseGenerationError.fromError(error, 'pipeline_context_preparation', params);
             }
             const { effectiveContext, contextAfterHook } = responseContext;
             let session = responseContext.session;
@@ -277,7 +328,7 @@ class ResponseModal {
                     await this.agent.updateContext(contextAfterHook);
                 }
                 catch (error) {
-                    throw ResponseGenerationError_1.ResponseGenerationError.fromError(error, 'context_update_from_pipeline', params, { contextAfterHook });
+                    throw ResponseGenerationError_js_1.ResponseGenerationError.fromError(error, 'context_update_from_pipeline', params, { contextAfterHook });
                 }
             }
             // Apply data staged before any session existed (initialData,
@@ -287,19 +338,32 @@ class ResponseModal {
             const stagedData = this.agent.consumePendingData();
             if (Object.keys(stagedData).length > 0) {
                 try {
-                    session = (0, utils_1.mergeCollected)(session, stagedData);
-                    utils_1.logger.debug("[ResponseModal] Merged staged agent data into session:", stagedData);
+                    session = (0, index_js_1.mergeCollected)(session, stagedData);
+                    index_js_1.logger.debug("[ResponseModal] Merged staged agent data into session:", stagedData);
                 }
                 catch (error) {
-                    throw ResponseGenerationError_1.ResponseGenerationError.fromError(error, 'data_merging', params, { stagedData });
+                    throw ResponseGenerationError_js_1.ResponseGenerationError.fromError(error, 'data_merging', params, { stagedData });
                 }
             }
+            // Record the user turn on the session's own history so the returned
+            // session carries the full exchange (respond owns session.history
+            // when `message` is used).
+            if (turnMessage) {
+                session.history = [...(session.history ?? []), (0, index_js_1.userMessage)(turnMessage)];
+            }
             // PHASE 1: PREPARE - Execute prepare function if current step has one
             try {
-                await this.stepLifecycle.runPrepare(session, effectiveContext);
+                const prepareDirective = await this.stepLifecycle.runPrepare(session, effectiveContext);
+                // Queue the control-flow directive for THIS turn: routing
+                // (handleRoutingAndStepSelection) consumes session.pendingDirective
+                // before deciding flow/step, so a prepare-phase goTo/goToStep/
+                // reset steers the current turn.
+                if (prepareDirective) {
+                    flow_namespace_js_1.flow.queuePending(session, prepareDirective);
+                }
             }
             catch (error) {
-                throw ResponseGenerationError_1.ResponseGenerationError.fromError(error, 'step_preparation', params, { session, effectiveContext });
+                throw ResponseGenerationError_js_1.ResponseGenerationError.fromError(error, 'step_preparation', params, { session, effectiveContext });
             }
             // PHASE 2: ROUTING + STEP SELECTION - Determine which flow and step to use
             // Performs pre-extraction and step selection
@@ -310,15 +374,17 @@ class ResponseModal {
                     history: historyEvents,
                     context: effectiveContext,
                     signal,
+                    allowedFlows,
                 });
             }
             catch (error) {
-                throw ResponseGenerationError_1.ResponseGenerationError.fromError(error, 'routing_and_step_selection', params, { session, effectiveContext });
+                throw ResponseGenerationError_js_1.ResponseGenerationError.fromError(error, 'routing_and_step_selection', params, { session, effectiveContext });
             }
             return {
                 effectiveContext,
                 session: routingResult.session,
                 history,
+                turnMessage,
                 selectedFlow: routingResult.selectedFlow,
                 selectedStep: routingResult.selectedStep,
                 responseDirectives: routingResult.responseDirectives,
@@ -328,14 +394,15 @@ class ResponseModal {
                 signalPreDirective: routingResult.signalPreDirective,
                 signalHalted: routingResult.signalHalted,
                 signalHaltReply: routingResult.signalHaltReply,
+                endedFlows: routingResult.endedFlows,
             };
         }
         catch (error) {
             // Re-throw ResponseGenerationError as-is, wrap others
-            if (ResponseGenerationError_1.ResponseGenerationError.isResponseGenerationError(error)) {
+            if (ResponseGenerationError_js_1.ResponseGenerationError.isResponseGenerationError(error)) {
                 throw error;
             }
-            throw ResponseGenerationError_1.ResponseGenerationError.fromError(error, 'preparation', params);
+            throw ResponseGenerationError_js_1.ResponseGenerationError.fromError(error, 'preparation', params);
         }
     }
     /**
@@ -358,7 +425,7 @@ class ResponseModal {
         // Accumulator for signal firings across both phases (fire order)
         const signalFirings = [...(preSignalFirings || [])];
         // Convert HistoryItem[] to Event[] for internal processing
-        const historyEvents = (0, utils_1.historyToEvents)(history);
+        const historyEvents = (0, index_js_1.historyToEvents)(history);
         const base = { effectiveContext, history, historyEvents, signal, signalFirings };
         // ── SIGNAL HALT (Requirement 8.2) ─────────────────────────────────────
         // Pre-signal phase emitted halt → skip LLM call entirely. The post-signal
@@ -379,7 +446,7 @@ class ResponseModal {
                 ? selectedFlow.getStep(session.currentStep.id)
                 : selectedStep;
             if (currentStepInstance?.auto) {
-                const autoChainExecutor = new AutoChainExecutor_1.AutoChainExecutor({
+                const autoChainExecutor = new AutoChainExecutor_js_1.AutoChainExecutor({
                     maxAutoStepsPerTurn: this.agent.maxAutoStepsPerTurn,
                 });
                 const autoResult = await autoChainExecutor.run({
@@ -401,7 +468,7 @@ class ResponseModal {
                 // ended without resolving to an interactive step (last_step: no
                 // successor; completed: explicit complete; goto: cross-flow redirect).
                 if (autoResult.stoppedReason === 'last_step' || autoResult.stoppedReason === 'completed' || autoResult.stoppedReason === 'goto') {
-                    utils_1.logger.debug(`[ResponseModal] Auto-chain ended with ${autoResult.stoppedReason}`);
+                    index_js_1.logger.debug(`[ResponseModal] Auto-chain ended with ${autoResult.stoppedReason}`);
                     return {
                         ...base, session,
                         outcome: { kind: 'flowComplete', selectedFlow, stoppedReason: autoResult.stoppedReason },
@@ -418,7 +485,7 @@ class ResponseModal {
         if (isFlowComplete && selectedFlow) {
             // Flow completion path: pure state transition, no LLM call. The reason
             // is 'last_step' (implicit terminus — no successor or all skipped).
-            utils_1.logger.debug(`[ResponseModal] Releasing session to idle for completed flow: ${selectedFlow.title}`);
+            index_js_1.logger.debug(`[ResponseModal] Releasing session to idle for completed flow: ${selectedFlow.title}`);
             return {
                 ...base, session,
                 outcome: { kind: 'flowComplete', selectedFlow, stoppedReason: 'last_step' },
@@ -472,6 +539,8 @@ class ResponseModal {
         let isFlowComplete = false;
         let appliedInstructions;
         let runPostPhase = true;
+        let tokensUsed;
+        const endedFlows = [...(responseContext.endedFlows ?? [])];
         switch (plan.outcome.kind) {
             case 'halt': {
                 message = plan.outcome.message;
@@ -488,6 +557,11 @@ class ResponseModal {
                 });
                 isFlowComplete = true;
                 stoppedReason = plan.outcome.stoppedReason;
+                endedFlows.push({
+                    flowId: plan.outcome.selectedFlow.id,
+                    title: plan.outcome.selectedFlow.title,
+                    reason: plan.outcome.stoppedReason,
+                });
                 break;
             }
             case 'flowStep': {
@@ -509,6 +583,7 @@ class ResponseModal {
                 toolCalls = result.toolCalls;
                 session = result.session;
                 appliedInstructions = result.appliedInstructions;
+                tokensUsed = result.tokensUsed;
                 if (plan.outcome.step) {
                     executedSteps = [{ id: plan.outcome.step.id, flowId: plan.outcome.selectedFlow.id }];
                 }
@@ -532,6 +607,13 @@ class ResponseModal {
         const tail = await this.applyTurnPostPhase({
             session, context: effectiveContext, historyEvents, message, signalFirings, runPostPhase,
         });
+        // History ownership: with params.message the returned session carries
+        // the full exchange — the user turn was recorded pre-routing, the
+        // assistant tail lands here (post-phase, so overridden replies are the
+        // ones recorded). Empty tails are skipped.
+        if (responseContext.turnMessage && tail.message) {
+            tail.session.history = [...(tail.session.history ?? []), (0, index_js_1.assistantMessage)(tail.message)];
+        }
         return {
             message: tail.message,
             session: tail.session,
@@ -541,6 +623,8 @@ class ResponseModal {
             stoppedReason,
             appliedInstructions,
             triggeredSignals: tail.triggeredSignals,
+            ...(tokensUsed !== undefined ? { metadata: { tokensUsed } } : {}),
+            ...(endedFlows.length > 0 ? { endedFlows } : {}),
         };
     }
     /**
@@ -572,12 +656,12 @@ class ResponseModal {
         if (mergedPreDirective?.halt) {
             if (mergedPreDirective.reply) {
                 // halt + reply: emit the reply as the assistant message
-                utils_1.logger.debug(`[ResponseModal] Halt with reply — skipping LLM call for step ${nextStep.id}`);
+                index_js_1.logger.debug(`[ResponseModal] Halt with reply — skipping LLM call for step ${nextStep.id}`);
                 return { message: mergedPreDirective.reply, session, stoppedReason: 'reply' };
             }
             else {
                 // halt without reply: emit empty assistant content
-                utils_1.logger.debug(`[ResponseModal] Halt without reply — skipping LLM call for step ${nextStep.id}`);
+                index_js_1.logger.debug(`[ResponseModal] Halt without reply — skipping LLM call for step ${nextStep.id}`);
                 return { message: '', session, stoppedReason: 'halt' };
             }
         }
@@ -588,8 +672,8 @@ class ResponseModal {
         // the step-declared reply (last-emission-wins per Algorithm 4).
         if (nextStep.reply != null) {
             // Determine the effective reply: prepare-emitted reply wins over step-declared
-            const effectiveReply = mergedPreDirective?.reply ?? await (0, utils_1.render)(nextStep.reply, (0, template_1.createTemplateContext)({ data: session.data || {}, context, session }));
-            utils_1.logger.debug(`[ResponseModal] Step.reply — skipping LLM call for step ${nextStep.id}`);
+            const effectiveReply = mergedPreDirective?.reply ?? await (0, index_js_1.render)(nextStep.reply, (0, template_js_1.createTemplateContext)({ data: session.data || {}, context, session }));
+            index_js_1.logger.debug(`[ResponseModal] Step.reply — skipping LLM call for step ${nextStep.id}`);
             return { message: effectiveReply, session, stoppedReason: 'reply' };
         }
         // Transient appendage: per-turn slot from Directive.appendPrompt.
@@ -625,16 +709,23 @@ class ResponseModal {
                 signal,
                 parameters: responseSchema ? { jsonSchema: responseSchema, schemaName: "response_output" } : undefined,
             });
-            let message = result.structured?.message || result.message;
-            let toolCalls = result.structured?.toolCalls;
-            // Debug: Log initial AI response
-            utils_1.logger.debug(`[ResponseModal] Initial AI response:`, {
-                hasMessage: !!message,
-                messageLength: message?.length || 0,
-                hasToolCalls: !!toolCalls,
-                toolCallsCount: toolCalls?.length || 0,
-                toolNames: toolCalls?.map(tc => tc.toolName) || [],
-            });
+            let structuredData = result.structured;
+            let message = structuredData?.message || result.message;
+            const tokensUsed = result.metadata?.tokensUsed;
+            // A schema was requested but the provider failed to parse the model's
+            // JSON (truncated output, fence-wrapped fragments). Raw protocol
+            // fragments must never surface as the user-visible reply: attempt one
+            // repair-parse, and if that fails fail the turn LOUDLY so the caller's
+            // rollback/retry path engages instead of leaking `{"message": "…` to
+            // an end user. Plain prose (not JSON-shaped at all) still passes
+            // through — it is not a protocol fragment.
+            if (!structuredData && responseSchema && message && /^\s*(```|{)/.test(message)) {
+                const salvaged = this.salvageStructuredOutput(message, "turn");
+                structuredData = salvaged;
+                message = salvaged.message;
+            }
+            const effectiveResult = structuredData ? { ...result, structured: structuredData } : result;
+            let toolCalls = structuredData?.toolCalls;
             // Execute tools with unified loop handling
             const toolResult = await this.toolLoopExecutor.runLoop({
                 toolCalls,
@@ -652,13 +743,19 @@ class ResponseModal {
             if (toolResult.finalMessage) {
                 message = toolResult.finalMessage;
             }
+            // Tool-emitted directives (ctx.dispatch / `{directive}` returns):
+            // state writes apply now; control flow queues for the next turn's
+            // pendingDirective applier (same deferred semantics as dispatch()).
+            if (toolResult.directives) {
+                session = await this.applyToolEmittedDirectives(session, toolResult.directives);
+            }
             // Collect data from response
             // Use follow-up structured data from tool loop when available, fall back to original result
             const dataSource = toolResult.structured
                 ? { structured: toolResult.structured }
-                : result;
+                : effectiveResult;
             session = await this.collectDataFromResponse({ result: dataSource, selectedFlow, nextStep, session });
-            return { message, toolCalls, session, appliedInstructions };
+            return { message, toolCalls, session, appliedInstructions, tokensUsed };
         }
         finally {
             // Drain the transient appendage at end of turn.
@@ -743,6 +840,13 @@ class ResponseModal {
                 });
                 const accumulated = tail.message;
                 const delta = tail.replyOverridden ? accumulated : chunk.delta;
+                // History ownership (parity with the sync tail): with
+                // params.message the returned session carries the full
+                // exchange — the user turn was recorded pre-routing, the
+                // assistant tail lands here, BEFORE finalize persists it.
+                if (responseContext.turnMessage && tail.message) {
+                    tail.session.history = [...(tail.session.history ?? []), (0, index_js_1.assistantMessage)(tail.message)];
+                }
                 // Single streaming exit: finalize the post-phase session so
                 // post-signal mutations (e.g. pendingDirective) are persisted.
                 await this.sessionFinalizer.finalize(tail.session, effectiveContext);
@@ -789,7 +893,7 @@ class ResponseModal {
      * @private
      */
     async *decodeMessageStream(stream) {
-        const decoder = new streamingMessage_1.StreamingMessageDecoder();
+        const decoder = new streamingMessage_js_1.StreamingMessageDecoder();
         for await (const chunk of stream) {
             const clean = decoder.push(chunk.accumulated);
             yield { ...chunk, delta: clean.delta, accumulated: clean.message };
@@ -829,7 +933,7 @@ class ResponseModal {
         if (mergedPreDirective?.halt) {
             const reply = mergedPreDirective.reply || '';
             const reason = mergedPreDirective.reply ? 'reply' : 'halt';
-            utils_1.logger.debug(`[ResponseModal] Halt (streaming) — skipping LLM call for step ${nextStep.id}, stoppedReason: ${reason}`);
+            index_js_1.logger.debug(`[ResponseModal] Halt (streaming) — skipping LLM call for step ${nextStep.id}, stoppedReason: ${reason}`);
             yield {
                 delta: reply,
                 accumulated: reply,
@@ -845,8 +949,8 @@ class ResponseModal {
         // onEnter and prepare have already fired normally. If prepare returned
         // a Directive with `reply`, that overrides the step-declared reply.
         if (nextStep.reply != null) {
-            const effectiveReply = mergedPreDirective?.reply ?? await (0, utils_1.render)(nextStep.reply, (0, template_1.createTemplateContext)({ data: session.data || {}, context, session }));
-            utils_1.logger.debug(`[ResponseModal] Step.reply (streaming) — skipping LLM call for step ${nextStep.id}`);
+            const effectiveReply = mergedPreDirective?.reply ?? await (0, index_js_1.render)(nextStep.reply, (0, template_js_1.createTemplateContext)({ data: session.data || {}, context, session }));
+            index_js_1.logger.debug(`[ResponseModal] Step.reply (streaming) — skipping LLM call for step ${nextStep.id}`);
             yield {
                 delta: effectiveReply,
                 accumulated: effectiveReply,
@@ -922,6 +1026,14 @@ class ResponseModal {
                     });
                     session = batchResult.session;
                     toolCalls = batchResult.toolCalls;
+                    // Tool-emitted directives (ctx.dispatch / `{directive}`):
+                    // state writes apply now; control flow queues for the next
+                    // turn's pendingDirective applier (same deferred semantics
+                    // as dispatch()). A verbatim tool reply already replaced the
+                    // closing message inside runStreamingBatch.
+                    if (batchResult.directives) {
+                        session = await this.applyToolEmittedDirectives(session, batchResult.directives);
+                    }
                     // Prefer the post-tool follow-up structured for collection and
                     // emission whenever present — independent of whether a closing
                     // message was forced — matching the non-streaming path's
@@ -938,6 +1050,17 @@ class ResponseModal {
                             : batchResult.finalMessage;
                     }
                 }
+                // Streaming twin of the non-streaming salvage guard: a schema was
+                // requested but no structured payload arrived, and the accumulated
+                // text is JSON-shaped (a protocol fragment) — repair-parse it or
+                // fail the turn rather than leaking raw output to the user.
+                if (chunk.done && !finalStructured && responseSchema && finalAccumulated && /^\s*(```|{)/.test(finalAccumulated)) {
+                    const salvaged = this.salvageStructuredOutput(finalAccumulated, "stream");
+                    finalStructured = salvaged;
+                    finalDelta = salvaged.message.startsWith(finalAccumulated)
+                        ? salvaged.message.slice(finalAccumulated.length)
+                        : salvaged.message;
+                }
                 // Collect data on the final chunk for any flow step — flow
                 // required/optional fields are valid targets even without a step
                 // `collect` — preferring the post-tool follow-up structured so a
@@ -1019,16 +1142,16 @@ class ResponseModal {
                             // Update session with validated data
                             const updateDataMethod = this.agent.getUpdateDataMethod();
                             updatedSession = await updateDataMethod(updatedSession, collectedData);
-                            utils_1.logger.debug(`[ResponseModal] Collected data:`, collectedData);
+                            index_js_1.logger.debug(`[ResponseModal] Collected data:`, collectedData);
                         }
                         catch (error) {
-                            utils_1.logger.error(`[ResponseModal] Failed to update collected data:`, error);
+                            index_js_1.logger.error(`[ResponseModal] Failed to update collected data:`, error);
                             // Continue without updating data rather than failing completely
                         }
                     }
                 }
                 catch (error) {
-                    utils_1.logger.error(`[ResponseModal] Error during data collection:`, error);
+                    index_js_1.logger.error(`[ResponseModal] Error during data collection:`, error);
                     // Continue without collecting data rather than failing completely
                 }
             }
@@ -1042,14 +1165,14 @@ class ResponseModal {
                     }
                 }
                 catch (error) {
-                    utils_1.logger.error(`[ResponseModal] Failed to update context from structured response:`, error);
+                    index_js_1.logger.error(`[ResponseModal] Failed to update context from structured response:`, error);
                     // Continue without updating context rather than failing completely
                 }
             }
             return updatedSession;
         }
         catch (error) {
-            utils_1.logger.error(`[ResponseModal] Error in collectDataFromResponse:`, error);
+            index_js_1.logger.error(`[ResponseModal] Error in collectDataFromResponse:`, error);
             // Return original session if data collection fails completely
             return params.session;
         }
@@ -1093,7 +1216,7 @@ class ResponseModal {
                 ...(selectedFlow.optionalFields ?? []),
             ]
             : undefined;
-        let nextSession = (0, utils_1.completeCurrentFlow)(session, {
+        let nextSession = (0, index_js_1.completeCurrentFlow)(session, {
             clearOwnedFields: ownedFields,
         });
         // 3) Wire pendingDirective when onComplete returned a target.
@@ -1110,15 +1233,15 @@ class ResponseModal {
                         goTo: targetFlow.id,
                     },
                 };
-                utils_1.logger.debug(`[ResponseModal] Flow ${selectedFlow.title} completed with pending directive to: ${targetFlow.title}`);
+                index_js_1.logger.debug(`[ResponseModal] Flow ${selectedFlow.title} completed with pending directive to: ${targetFlow.title}`);
             }
             else if (goToTarget) {
-                utils_1.logger.warn(`[FlowConfigurationError] onComplete target not found: flow "${selectedFlow.title}" completed but onComplete target "${goToTarget}" does not match any flow. ` +
+                index_js_1.logger.warn(`[FlowConfigurationError] onComplete target not found: flow "${selectedFlow.title}" completed but onComplete target "${goToTarget}" does not match any flow. ` +
                     `Fix the onComplete value to reference an existing flow id/title, or remove onComplete to release the session to idle.`);
             }
         }
         else {
-            utils_1.logger.debug(`[ResponseModal] Flow ${selectedFlow.title} completed; session released to idle.`);
+            index_js_1.logger.debug(`[ResponseModal] Flow ${selectedFlow.title} completed; session released to idle.`);
         }
         return nextSession;
     }
@@ -1160,7 +1283,7 @@ class ResponseModal {
      */
     async generateFallbackResponse(params) {
         const { history, context, session, signal } = params;
-        utils_1.logger.debug(`[ResponseModal] No flow selected, generating basic response`);
+        index_js_1.logger.debug(`[ResponseModal] No flow selected, generating basic response`);
         // Build basic response prompt without flow context
         const { prompt: fallbackPrompt, appliedInstructions } = await this.responseEngine.buildFallbackPrompt({
             agentOptions: this.agent.getAgentOptions(),