@falai/agent 2.6.1 → 3.0.0

package/src/core/FlowRouter.ts

@@ -5,14 +5,14 @@ import type {
   SessionState,
   AiProvider,
   TemplateContext,
-} from "../types";
-import { MessageRole } from "../types";
-import { enterFlow, mergeCollected, isFlowCompletedThisSession } from "../utils";
-import type { Flow } from "./Flow";
-import type { Step } from "./Step";
-import { PromptComposer } from "./PromptComposer";
-import { PromptSectionCache } from "./PromptSectionCache";
-import { createTemplateContext, getLastMessageFromHistory, logger, eventsToHistory } from "../utils";
+} from "../types/index.js";
+import { MessageRole } from "../types/index.js";
+import { enterFlow, mergeCollected, isFlowCompletedThisSession } from "../utils/index.js";
+import type { Flow } from "./Flow.js";
+import type { Step } from "./Step.js";
+import { PromptComposer } from "./PromptComposer.js";
+import { PromptSectionCache } from "./PromptSectionCache.js";
+import { createTemplateContext, getLastMessageFromHistory, logger, eventsToHistory } from "../utils/index.js";
 
 export interface CandidateStep<TContext = unknown, TData = unknown> {
   step: Step<TContext, TData>;
@@ -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/PersistenceManager.ts

@@ -17,10 +17,10 @@ import type {
   History,
   PersistenceAdapter,
   CollectedStateData,
-} from "../types";
-import { createSession, sessionStepToData, sessionDataToStep, logger } from "../utils";
-import { SessionConflictError } from "../types/errors";
-import { convertMessagesToHistory } from "./Events";
+} from "../types/index.js";
+import { createSession, sessionStepToData, sessionDataToStep, logger } from "../utils/index.js";
+import { SessionConflictError } from "../types/errors.js";
+import { convertMessagesToHistory } from "./Events.js";
 
 /**
  * Manager for handling persistence operations

package/src/core/PromptComposer.ts

@@ -1,10 +1,10 @@
-import type { Event, Term, Instruction, AgentOptions, ScopedInstructions, AppliedInstruction } from "../types";
-import type { Flow } from "./Flow";
-import { render, renderMany, formatKnowledgeBase, createTemplateContext } from "../utils/template";
-import { TemplateContext } from "../types/template";
-import { PromptSectionCache } from "./PromptSectionCache";
-import { logger } from "../utils";
-import { splitWhenConditions } from "../utils/condition";
+import type { Event, Term, Instruction, AgentOptions, ScopedInstructions, AppliedInstruction } from "../types/index.js";
+import type { Flow } from "./Flow.js";
+import { render, renderMany, formatKnowledgeBase, createTemplateContext } from "../utils/template.js";
+import { TemplateContext } from "../types/template.js";
+import { PromptSectionCache } from "./PromptSectionCache.js";
+import { logger } from "../utils/index.js";
+import { splitWhenConditions } from "../utils/condition.js";
 
 export class PromptComposer<TContext = unknown, TData = unknown> {
   private parts: string[] = [];
@@ -168,7 +168,7 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
           const result = await predicate({
             context: (this.renderContext.context ?? {}) as TContext,
             data: (this.renderContext.data || {}),
-            session: (this.renderContext.session ?? { id: '', data: {}, history: [], metadata: {} }) as import("../types/session").SessionState<TData>,
+            session: (this.renderContext.session ?? { id: '', data: {}, history: [], metadata: {} }) as import("../types/session.js").SessionState<TData>,
             history: this.renderContext.history || [],
           });
           if (!result) return false;

package/src/core/PromptSectionCache.ts

@@ -7,8 +7,8 @@
  * directives, available tools) are recomputed on every resolveAll() call.
  */
 
-import type { PromptSectionType, PromptCacheConfig, SectionCompute } from "../types/prompt-cache";
-export type { PromptSectionType, PromptCacheConfig, SectionCompute } from "../types/prompt-cache";
+import type { PromptSectionType, PromptCacheConfig, SectionCompute } from "../types/prompt-cache.js";
+export type { PromptSectionType, PromptCacheConfig, SectionCompute } from "../types/prompt-cache.js";
 
 /** Internal entry tracking a registered section */
 interface PromptSectionEntry {

package/src/core/ResponseEngine.ts

@@ -7,12 +7,12 @@ import type {
   Template,
   ScopedInstructions,
   AppliedInstruction,
-} from "../types";
-import type { Flow } from "./Flow";
-import type { Step } from "./Step";
-import { PromptComposer } from "./PromptComposer";
-import { PromptSectionCache } from "./PromptSectionCache";
-import { createTemplateContext, render } from "../utils/template";
+} from "../types/index.js";
+import type { Flow } from "./Flow.js";
+import type { Step } from "./Step.js";
+import { PromptComposer } from "./PromptComposer.js";
+import { PromptSectionCache } from "./PromptSectionCache.js";
+import { createTemplateContext, render } from "../utils/template.js";
 
 export interface BuildResponsePromptParams<
   TContext = unknown,

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}`;
-        }
     }
 
     /**

package/src/core/ResponseModal.ts

@@ -7,6 +7,7 @@ import type {
     AgentOptions,
     AgentResponse,
     AgentResponseStreamChunk,
+    EndedFlow,
     History,
     SessionState,
     StepRef,
@@ -22,27 +23,30 @@ import type {
     Term,
     StructuredSchema,
     CompactionOptions,
-} from "../types";
-import type { SignalFiring } from "../types/signals";
-import type { SessionManager } from "./SessionManager";
-import type { SignalProcessor } from "./SignalProcessor";
-import type { PromptSectionCache } from "./PromptSectionCache";
-import type { FlowRouter } from "./FlowRouter";
-import type { PersistenceManager } from "./PersistenceManager";
-import type { Flow } from "./Flow";
-import { Step } from "./Step";
-import { ResponseEngine } from "./ResponseEngine";
-import { ResponsePipeline } from "./ResponsePipeline";
-import { AutoChainExecutor, type AutoChainResult } from "./AutoChainExecutor";
-import { StepLifecycle } from "./StepLifecycle";
-import { SessionFinalizer } from "./SessionFinalizer";
-import { ToolLoopExecutor } from "./ToolLoopExecutor";
-import { SignalCoordinator } from "./SignalCoordinator";
-import { ResponseGenerationError } from "./ResponseGenerationError";
-import { cloneDeep, mergeCollected, logger, historyToEvents, completeCurrentFlow, render } from "../utils";
-import { createTemplateContext } from "../utils/template";
-import { StreamingMessageDecoder } from "../utils/streamingMessage";
-import type { ToolManager } from "./ToolManager";
+} from "../types/index.js";
+import type { SignalFiring } from "../types/signals.js";
+import type { SessionManager } from "./SessionManager.js";
+import type { SignalProcessor } from "./SignalProcessor.js";
+import type { PromptSectionCache } from "./PromptSectionCache.js";
+import type { FlowRouter } from "./FlowRouter.js";
+import type { PersistenceManager } from "./PersistenceManager.js";
+import type { Flow } from "./Flow.js";
+import { Step } from "./Step.js";
+import { ResponseEngine } from "./ResponseEngine.js";
+import { ResponsePipeline } from "./ResponsePipeline.js";
+import { AutoChainExecutor, type AutoChainResult } from "./AutoChainExecutor.js";
+import { StepLifecycle } from "./StepLifecycle.js";
+import { SessionFinalizer } from "./SessionFinalizer.js";
+import { ToolLoopExecutor } from "./ToolLoopExecutor.js";
+import { flow } from "./flow-namespace.js";
+import { SignalCoordinator } from "./SignalCoordinator.js";
+import { ResponseGenerationError } from "./ResponseGenerationError.js";
+import { ProviderError, SessionConflictError } from "../types/errors.js";
+import { cloneDeep, mergeCollected, logger, historyToEvents, completeCurrentFlow, render, userMessage, assistantMessage } from "../utils/index.js";
+import { createTemplateContext } from "../utils/template.js";
+import { StreamingMessageDecoder } from "../utils/streamingMessage.js";
+import { tryParseJSONResponse } from "../utils/json.js";
+import type { ToolManager } from "./ToolManager.js";
 
 /**
  * The narrow surface ResponseModal (and its collaborators) need from the
@@ -95,6 +99,19 @@ export interface ResponseModalOptions {
  */
 export interface RespondParams<TContext = unknown, TData = unknown> extends Record<string, unknown> {
     history: History;
+    /**
+     * The user's message for this turn. When set, the engine appends it to the
+     * generation history AND to the returned session's history, then appends
+     * the assistant reply on top — callers who hold sessions no longer need to
+     * maintain history arrays by hand.
+     */
+    message?: string;
+    /**
+     * Restrict this turn's ROUTING candidates to these flow ids/titles.
+     * Directive targets (goTo etc.) still resolve against the full registry.
+     * Use for entry-pin funnels instead of cloning/filtering agents.
+     */
+    allowedFlows?: string[];
     step?: StepRef;
     session?: SessionState<TData>;
     contextOverride?: Partial<TContext>;
@@ -140,6 +157,10 @@ interface ResponseContext<TContext = unknown, TData = unknown> {
     signalHalted?: boolean;
     /** Reply from a halt directive. */
     signalHaltReply?: string;
+    /** Flows exited via pendingDirective redirects/resets during routing. */
+    endedFlows?: EndedFlow[];
+    /** The user turn supplied via params.message (drives history ownership). */
+    turnMessage?: string;
 }
 
 /**
@@ -261,6 +282,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             if (preTurnSession) {
                 this.agent.session.syncSession(preTurnSession);
             }
+            // 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 ProviderError || error instanceof SessionConflictError) {
+                throw error;
+            }
             throw new ResponseGenerationError(
                 `[ResponseGenerationError] Response generation failed: ${error instanceof Error ? error.message : String(error)}. ` +
                 `Check provider configuration and network connectivity.`,
@@ -430,6 +458,58 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         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.
+     */
+    private salvageStructuredOutput(
+        raw: string,
+        surface: "turn" | "stream"
+    ): AgentStructuredResponse {
+        const salvaged = tryParseJSONResponse(raw) as Partial<AgentStructuredResponse> | undefined;
+        if (salvaged && typeof salvaged.message === "string") {
+            logger.warn(`[ResponseModal] Salvaged malformed structured output from ${surface} via JSON repair parse.`);
+            return { ...salvaged, message: salvaged.message };
+        }
+        throw 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()).
+     */
+    private async applyToolEmittedDirectives(
+        session: SessionState<TData>,
+        d: Directive<TContext, TData>
+    ): Promise<SessionState<TData>> {
+        if (d.dataUpdate) {
+            session = 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.queuePending(session, control);
+        }
+        return session;
+    }
+
     /**
      * Collect scoped instructions from agent, flow, and step into a ScopedInstructions value.
      * @private
@@ -455,21 +535,25 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
      */
     private async prepareUnifiedResponseContext(params: RespondParams<TContext, TData>): Promise<ResponseContext<TContext, TData>> {
         try {
-            const { history: simpleHistory, contextOverride, signal } = params;
+            const { history: simpleHistory, contextOverride, signal, message: turnMessage, allowedFlows } = params;
 
             // Validate input parameters
             if (!simpleHistory) {
                 throw new ResponseGenerationError(
                     '[ResponseGenerationError] Missing history: history is required for response generation. ' +
-                    'Pass a valid history array to the respond/stream method.',
+                    '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, userMessage(turnMessage)]
+                : simpleHistory;
+
             // Convert HistoryItem[] to Event[] for internal processing
-            const historyEvents = historyToEvents(simpleHistory);
-            // Keep original HistoryItem[] format for external APIs
-            const history = simpleHistory;
+            const historyEvents = historyToEvents(history);
 
             // Use ResponsePipeline for context and session preparation; context
             // and session are passed explicitly — the pipeline holds no state
@@ -515,9 +599,23 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 }
             }
 
+            // 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 ?? []), 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.queuePending(session, prepareDirective);
+                }
             } catch (error) {
                 throw ResponseGenerationError.fromError(error, 'step_preparation', params, { session, effectiveContext });
             }
@@ -534,6 +632,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 signalPreDirective?: Directive<TContext, TData>;
                 signalHalted?: boolean;
                 signalHaltReply?: string;
+                endedFlows?: EndedFlow[];
             };
             try {
                 routingResult = await this.responsePipeline.routeAndSelectStep({
@@ -541,6 +640,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     history: historyEvents,
                     context: effectiveContext,
                     signal,
+                    allowedFlows,
                 });
             } catch (error) {
                 throw ResponseGenerationError.fromError(error, 'routing_and_step_selection', params, { session, effectiveContext });
@@ -550,6 +650,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 effectiveContext,
                 session: routingResult.session,
                 history,
+                turnMessage,
                 selectedFlow: routingResult.selectedFlow,
                 selectedStep: routingResult.selectedStep,
                 responseDirectives: routingResult.responseDirectives,
@@ -559,6 +660,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 signalPreDirective: routingResult.signalPreDirective,
                 signalHalted: routingResult.signalHalted,
                 signalHaltReply: routingResult.signalHaltReply,
+                endedFlows: routingResult.endedFlows,
             };
         } catch (error) {
             // Re-throw ResponseGenerationError as-is, wrap others
@@ -748,6 +850,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         let isFlowComplete = false;
         let appliedInstructions: AppliedInstruction[] | undefined;
         let runPostPhase = true;
+        let tokensUsed: number | undefined;
+        const endedFlows: EndedFlow[] = [...(responseContext.endedFlows ?? [])];
 
         switch (plan.outcome.kind) {
             case 'halt': {
@@ -765,6 +869,11 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 });
                 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': {
@@ -786,6 +895,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 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 }];
                 }
@@ -811,6 +921,14 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             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 ?? []), assistantMessage(tail.message)];
+        }
+
         return {
             message: tail.message,
             session: tail.session,
@@ -820,6 +938,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             stoppedReason,
             appliedInstructions,
             triggeredSignals: tail.triggeredSignals,
+            ...(tokensUsed !== undefined ? { metadata: { tokensUsed } } : {}),
+            ...(endedFlows.length > 0 ? { endedFlows } : {}),
         };
     }
 
@@ -852,6 +972,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         session: SessionState<TData>;
         appliedInstructions?: AppliedInstruction[];
         stoppedReason?: StoppedReason;
+        /** Provider-reported usage for the primary generation call. */
+        tokensUsed?: number;
     }> {
         const { selectedFlow, selectedStep, responseDirectives, history, context, historyEvents, signal, transientAppendage, mergedPreDirective } = params;
         let session = params.session;
@@ -940,17 +1062,25 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 parameters: responseSchema ? { jsonSchema: responseSchema, schemaName: "response_output" } : undefined,
             });
 
-            let message = result.structured?.message || result.message;
-            let toolCalls = result.structured?.toolCalls;
+            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;
+            }
 
-            // Debug: Log initial AI response
-            logger.debug(`[ResponseModal] Initial AI response:`, {
-                hasMessage: !!message,
-                messageLength: message?.length || 0,
-                hasToolCalls: !!toolCalls,
-                toolCallsCount: toolCalls?.length || 0,
-                toolNames: toolCalls?.map(tc => tc.toolName) || [],
-            });
+            const effectiveResult = structuredData ? { ...result, structured: structuredData } : result;
+            let toolCalls = structuredData?.toolCalls;
 
             // Execute tools with unified loop handling
             const toolResult = await this.toolLoopExecutor.runLoop({
@@ -971,14 +1101,21 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 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.
             // This ensures Directive.appendPrompt does not leak to subsequent
@@ -1070,6 +1207,14 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 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 ?? []), 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);
@@ -1291,6 +1436,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     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
@@ -1309,6 +1463,18 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     }
                 }
 
+                // 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