@falai/agent 2.4.1 → 2.4.3

package/dist/utils/retry.js

@@ -68,4 +68,40 @@ export const withTimeoutAndRetry = async (operation, timeoutMs = 60000, maxRetri
         },
     });
 };
+/**
+ * Streaming analog of {@link withTimeoutAndRetry}. Re-runs an async-generator
+ * factory as long as it fails *before yielding its first chunk* — e.g. an
+ * empty completion that throws "No response", or an error while establishing
+ * the stream. Once any chunk has been yielded the stream is committed and
+ * further errors propagate, so a retry can never double-emit deltas that the
+ * consumer has already received.
+ *
+ * This mirrors the non-streaming path, where the provider throws on an empty
+ * completion inside `withTimeoutAndRetry` and is retried on the same model
+ * before the caller falls through to backup models.
+ */
+export async function* withStreamRetry(factory, options = {}) {
+    const { maxRetries = 3, delay = (attempt) => Math.min(1000 * Math.pow(2, attempt), 5000), operationName = "AI stream", } = options;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        let yielded = false;
+        try {
+            for await (const chunk of factory()) {
+                yielded = true;
+                yield chunk;
+            }
+            return;
+        }
+        catch (error) {
+            // Can't retry once deltas are out, and don't retry past the budget.
+            if (yielded || attempt === maxRetries) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(`[${operationName}] Failed attempt ${attempt + 1}:`, message);
+            const delayMs = delay(attempt);
+            logger.debug(`[${operationName}] Retrying in ${delayMs}ms... (attempt ${attempt + 2}/${maxRetries + 1})`);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+}
 //# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}

package/docs/reference/signals.md

@@ -99,6 +99,7 @@ interface SignalFiring<TContext = unknown, TData = unknown> {
   extracted?: unknown;
   directive?: ResolvedSignalDirective<TContext, TData>;
   handlerError?: string;
+  extractionError?: string;
   durationMs?: number;
 }
 
@@ -205,6 +206,7 @@ One entry per signal that fired this turn. Populated in fire order across both p
 | `extracted` | `unknown` | Extracted payload when in extraction mode. |
 | `directive` | `ResolvedSignalDirective \| undefined` | The directive returned (or dispatched) by the handler, with `replyWith` already resolved onto `reply`. |
 | `handlerError` | `string \| undefined` | Error message if the handler threw. The turn continues — handler errors never break a turn. |
+| `extractionError` | `string \| undefined` | Set when an extraction-mode signal matched but the classifier returned no `extracted` payload (model omitted the field or returned `null`). The handler still runs with `extracted: undefined`; this makes the miss observable instead of silent. Independent of `handlerError`. |
 | `durationMs` | `number \| undefined` | Wall-clock duration of the handler invocation. |
 
 ### `SignalsState` and `SignalTriggerState`
@@ -353,6 +355,7 @@ Soft failures handled in-band (no thrown error, turn continues):
 
 - **Handler throws** — recorded as `firings[i].handlerError`; iteration continues with the next signal.
 - **Classifier call fails** — all LLM-conditioned signals in that batch are treated as non-match; code-only and unconditional signals continue normally.
+- **Extraction-mode signal matched but no payload returned** — recorded as `firings[i].extractionError` with a WARN log; the handler still runs with `extracted: undefined`. Usually means the `extract` schema used a keyword the provider ignores (e.g. `nullable: true` instead of `type: ['string', 'null']`), so the model omitted the field.
 - **Post-phase emits pre-LLM-only fields** (`halt` / `appendPrompt` / `injectTools`) — dropped with debug warning.
 - **`behavior: 'cooldown'` with no `cooldownMs`** — debug warning at construction; runtime treats as `'always'`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/PersistenceManager.ts

@@ -42,6 +42,24 @@ export class PersistenceManager<TData = Record<string, unknown>> {
     this.messageRepository = config.adapter.messageRepository;
   }
 
+  /**
+   * Reject a non-string id before it reaches a repository query filter.
+   *
+   * SECURITY: session/user ids flow into adapter query VALUE positions (e.g.
+   * Mongo `findOne({ id })`). A non-string value such as `{ $ne: null }` —
+   * trivially produced by an HTTP body or an Express `?id[$ne]=` query — would
+   * be interpreted by a NoSQL driver as query operators, turning an equality
+   * lookup into an operator query (cross-tenant read / mass delete). Callers
+   * type these as `string`, but that guarantee is erased at runtime, so we
+   * enforce it here: the single layer every public session/user lookup funnels
+   * through.
+   */
+  private assertScalarId(value: unknown, label: string): asserts value is string {
+    if (typeof value !== "string" || value.length === 0) {
+      throw new Error(`${label} must be a non-empty string`);
+    }
+  }
+
   /**
    * Create a new session
    */
@@ -67,6 +85,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
    * Get session by ID
    */
   async getSession(sessionId: string): Promise<SessionData<TData> | null> {
+    this.assertScalarId(sessionId, "Session ID");
     return await this.sessionRepository.findById(sessionId);
   }
 
@@ -80,6 +99,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
         "userId must be provided or configured in PersistenceConfig"
       );
     }
+    this.assertScalarId(effectiveUserId, "User ID");
     return await this.sessionRepository.findActiveByUserId(effectiveUserId);
   }
 
@@ -96,6 +116,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
         "userId must be provided or configured in PersistenceConfig"
       );
     }
+    this.assertScalarId(effectiveUserId, "User ID");
     return await this.sessionRepository.findByUserId(effectiveUserId, limit);
   }
 
@@ -170,6 +191,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
     sessionId: string,
     limit?: number
   ): Promise<MessageData[]> {
+    this.assertScalarId(sessionId, "Session ID");
     return await this.messageRepository.findBySessionId(sessionId, limit);
   }
 
@@ -186,6 +208,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
         "userId must be provided or configured in PersistenceConfig"
       );
     }
+    this.assertScalarId(effectiveUserId, "User ID");
     return await this.messageRepository.findByUserId(effectiveUserId, limit);
   }
 
@@ -193,6 +216,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
    * Delete a session and all its messages
    */
   async deleteSession(sessionId: string): Promise<boolean> {
+    this.assertScalarId(sessionId, "Session ID");
     // Delete all messages first
     await this.messageRepository.deleteBySessionId(sessionId);
 
@@ -260,9 +284,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
     sessionStep: SessionState<TData>
   ): Promise<SessionData<TData> | null> {
     // Validate input parameters
-    if (!sessionId || typeof sessionId !== 'string') {
-      throw new Error('Session ID must be a non-empty string');
-    }
+    this.assertScalarId(sessionId, "Session ID");
 
     if (!sessionStep || typeof sessionStep !== 'object') {
       throw new Error('Session step must be a valid object');
@@ -307,9 +329,10 @@ export class PersistenceManager<TData = Record<string, unknown>> {
       } else {
         saved = await this.sessionRepository.create({
           id: sessionId,
-          userId: persistenceData.collectedData.metadata?.userId
-            ? JSON.stringify(persistenceData.collectedData.metadata?.userId)
-            : this.config.userId,
+          // Owner is the authenticated principal from config — never derived
+          // from collectedData.metadata (model/user-influenced state), which
+          // would let collected data mis-attribute a session's tenant.
+          userId: this.config.userId,
           status: "active",
           currentFlow: persistenceData.currentFlow,
           currentStep: persistenceData.currentStep,
@@ -342,6 +365,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
   async loadSessionState(
     sessionId: string
   ): Promise<SessionState<TData> | null> {
+    this.assertScalarId(sessionId, "Session ID");
     const sessionData = await this.sessionRepository.findById(sessionId);
 
     if (!sessionData) {

package/src/core/ResponseModal.ts

@@ -1243,6 +1243,10 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             // Stream chunks with unified tool handling
             for await (const chunk of stream) {
                 let toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }> | undefined = undefined;
+                // Final message/structured may be replaced by a forced post-tool
+                // response (see runStreamingBatch / gap: tools-ran-but-no-text).
+                let finalAccumulated = chunk.accumulated;
+                let finalStructured = chunk.structured;
 
                 // Extract tool calls from AI response on final chunk
                 if (chunk.done && chunk.structured?.toolCalls) {
@@ -1265,9 +1269,18 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     });
                     session = batchResult.session;
                     toolCalls = batchResult.toolCalls;
+
+                    // Tools ran but the model produced no result-aware text — use
+                    // the forced closing message so we never emit the bare
+                    // preamble (or an empty message) as the final response.
+                    if (batchResult.finalMessage) {
+                        finalAccumulated = batchResult.finalMessage;
+                        finalStructured = batchResult.structured ?? finalStructured;
+                    }
                 }
 
-                // Extract collected data on final chunk
+                // Extract collected data on final chunk (from the model's own
+                // structured output for this step, not the forced follow-up)
                 if (chunk.done && chunk.structured && nextStep.collect) {
                     session = await this.collectDataFromResponse({
                         result: { structured: chunk.structured },
@@ -1283,7 +1296,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 // - session.currentStep: reflects the executed step
                 yield {
                     delta: chunk.delta,
-                    accumulated: chunk.accumulated,
+                    accumulated: finalAccumulated,
                     done: chunk.done,
                     session,
                     toolCalls,
@@ -1291,7 +1304,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     executedSteps: chunk.done ? [{ id: nextStep.id, flowId: selectedFlow.id }] : undefined,
                     stoppedReason: chunk.done ? 'needs_input' : undefined,
                     metadata: chunk.metadata,
-                    structured: chunk.structured,
+                    structured: finalStructured,
                     appliedInstructions: chunk.done ? appliedInstructions : undefined,
                 };
             }

package/src/core/SessionManager.ts

@@ -59,6 +59,13 @@ export class SessionManager<TData = unknown> {
    * Works for sessionIds that exist, don't exist, or auto-generated IDs
    */
   async getOrCreate(sessionId?: string): Promise<SessionState<TData>> {
+    // SECURITY: a non-string sessionId (e.g. `{ $ne: null }` from an HTTP body
+    // or `?sessionId[$ne]=` query) forwarded into a NoSQL query becomes an
+    // operator clause. Reject it at the entry point; `undefined` is allowed and
+    // auto-generates an id, and an empty string keeps its fall-back semantics.
+    if (sessionId !== undefined && typeof sessionId !== "string") {
+      throw new Error("sessionId must be a string");
+    }
     // Use provided sessionId or fall back to default
     const effectiveSessionId = sessionId || this.defaultSessionId;
 

package/src/core/SignalProcessor.ts

@@ -27,6 +27,11 @@ import type {
 import type { SignalEvaluator } from "./SignalEvaluator";
 import { logger } from "../utils";
 
+/** Recorded on `SignalFiring.extractionError` when a matched extraction-mode
+ * signal yields no payload (model omitted the field or returned null). */
+const EXTRACTION_MISSING_MESSAGE =
+    "Signal matched in extraction mode but the classifier returned no extracted payload.";
+
 // ──────────────────────────────────────────────────────────────────────────────
 // behaviorAllowsExecution — Algorithm 2
 // ──────────────────────────────────────────────────────────────────────────────
@@ -454,23 +459,29 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
             }
         }
 
-        // ── STEP 6b: unconditional + extract signals ────────────────────────
-        const unconditionalWithExtract = unconditional.filter((s) => s.extract != null);
-        if (unconditionalWithExtract.length > 0) {
+        // ── STEP 6b: extraction for code-matched signals ─────────────────────
+        // Signals matched by code — unconditional (no `when`/`if`) or code-only
+        // (`if` without `when`) — that carry an `extract` schema still need a
+        // dedicated extraction call. LLM-conditioned signals already had their
+        // extraction merged into the STEP 6 classifier batch, so they are
+        // excluded here by identity. Without this, an `if` + `extract` signal
+        // (e.g. the documented `leadStage` example) would reach its handler with
+        // `ctx.extracted` permanently undefined.
+        const codeMatchedWithExtract = matched.filter(
+            (m) => m.signal.extract != null && !llmConditioned.includes(m.signal),
+        );
+        if (codeMatchedWithExtract.length > 0) {
             const extractResults = await this.evaluator.evaluateSignals({
-                signals: unconditionalWithExtract,
+                signals: codeMatchedWithExtract.map((m) => m.signal),
                 session,
                 history,
                 context,
             });
 
-            // Attach extracted data to already-matched unconditional entries
-            for (const s of unconditionalWithExtract) {
-                const id = s.id ?? 'unknown';
-                const entry = matched.find((m) => m.signal === s);
-                if (entry) {
-                    entry.extracted = extractResults[id]?.extracted;
-                }
+            // Attach extracted data back onto the already-matched entries.
+            for (const m of codeMatchedWithExtract) {
+                const id = m.signal.id ?? 'unknown';
+                m.extracted = extractResults[id]?.extracted;
             }
         }
 
@@ -490,6 +501,16 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
             // Turn-local directive bus for this handler (captures dispatch calls)
             const handlerBus: SignalDirective<TContext, TData>[] = [];
 
+            // A signal in extraction mode that matched but produced no payload
+            // would otherwise pass `extracted: undefined` to the handler with no
+            // trace. Surface the miss on the firing and in logs instead.
+            const extractionMissing = m.signal.extract != null && m.extracted == null;
+            if (extractionMissing) {
+                logger.warn(
+                    `[Signals] Signal "${m.signal.id ?? 'unknown'}" matched in extraction mode ` +
+                    `but the classifier returned no extracted payload; handler receives extracted: undefined.`,
+                );
+            }
 
             const sigCtx = buildSignalContext<TContext, TData, any>({
                 signal: m.signal,
@@ -555,6 +576,7 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
                     extracted: m.extracted,
                     directive: resolvedDirective,
                     durationMs: handlerDurationMs,
+                    ...(extractionMissing ? { extractionError: EXTRACTION_MISSING_MESSAGE } : {}),
                 });
 
                 // stopOtherSignals → break iteration
@@ -574,6 +596,7 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
                     reason: m.reason,
                     handlerError: errorMessage,
                     durationMs: handlerDurationMs,
+                    ...(extractionMissing ? { extractionError: EXTRACTION_MISSING_MESSAGE } : {}),
                 });
 
                 // Continue iteration — handler errors never break the turn

package/src/core/StreamingToolExecutor.ts

@@ -19,6 +19,7 @@ import type {
     Tool,
     TrackedTool,
 } from "../types/tool";
+import { evaluateToolGates } from "./toolGates";
 
 /** Options for the StreamingToolExecutor */
 interface StreamingToolExecutorOptions {
@@ -221,6 +222,17 @@ export class StreamingToolExecutor<TContext = unknown, TData = unknown> {
         const batchAbortController = this.siblingAbortController;
 
         try {
+            // Pre-execution gates (validateInput → checkPermissions), shared with
+            // ToolManager.executeTool. These MUST run on the streaming path too:
+            // when a gate denies, the handler is NOT invoked. Run before any abort
+            // wiring so a denial returns cleanly with nothing to unwind.
+            const gateDenial = await evaluateToolGates(tool, toolCall.arguments, this.toolContext);
+            if (gateDenial) {
+                tracked.results.push(gateDenial);
+                tracked.status = "completed";
+                return;
+            }
+
             // Create a combined abort signal from parent + sibling
             const toolAbortController = new AbortController();
             const abortTool = () => {

package/src/core/ToolLoopExecutor.ts

@@ -147,7 +147,9 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             }
 
             // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution
-            const MAX_TOOL_LOOPS = this.deps.maxToolLoops || 5;
+            // `??` so an explicit `maxToolLoops: 0` is honored instead of being
+            // clobbered to the default by a falsy-zero check.
+            const MAX_TOOL_LOOPS = this.deps.maxToolLoops ?? 5;
             let toolLoopCount = 0;
             let hasToolCalls = toolCalls && toolCalls.length > 0;
             let finalMessage: string | undefined;
@@ -296,63 +298,26 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             }
 
             // If tools were executed but no final text message was produced,
-            // make one more LLM call to generate a proper text response from tool results.
-            // This prevents the original tool-invocation message (e.g. "Let me check...")
-            // from being returned as the final user-facing response.
+            // make one more LLM call to generate a proper text response from tool
+            // results. This prevents the original tool-invocation message (e.g.
+            // "Let me check...") from being returned as the final user-facing
+            // response. Shared with the streaming path via forceFinalTextFromTools.
             if (!finalMessage && toolLoopCount > 0) {
                 logger.debug(`[ToolLoopExecutor] No final message after tool loop, making additional LLM call for text response`);
-
-                // Build tool result history from toolResultsMap which contains ALL
-                // tool executions (initial + follow-up). We can't use `toolCalls` here
-                // because it was reassigned to the (empty) follow-up tool calls when
-                // the while loop broke out.
-                const finalToolResultHistoryItems: HistoryItem[] = [];
-                for (const [toolName, toolResult] of toolResultsMap) {
-                    finalToolResultHistoryItems.push({
-                        role: "assistant" as const,
-                        content: null,
-                        tool_calls: [{
-                            id: toolName,
-                            name: toolName,
-                            arguments: toolArgsMap.get(toolName) || {},
-                        }],
-                    });
-                    finalToolResultHistoryItems.push({
-                        role: "tool" as const,
-                        tool_call_id: toolName,
-                        name: toolName,
-                        content: toolResult,
-                    });
+                const forced = await this.forceFinalTextFromTools({
+                    history,
+                    toolResultsMap,
+                    toolArgsMap,
+                    responsePrompt,
+                    responseSchema,
+                    context,
+                    signal,
+                });
+                if (forced.finalMessage) {
+                    finalMessage = forced.finalMessage;
                 }
-
-                const finalHistory = [...history, ...finalToolResultHistoryItems];
-                const agentOptions = this.deps.getAgentOptions();
-
-                try {
-                    const textResult = await agentOptions.provider.generateMessage({
-                        prompt: responsePrompt + "\n\nProvide a text response to the user based on the tool results. Do not call any tools.",
-                        history: finalHistory,
-                        context,
-                        tools: [], // No tools - force text response
-                        parameters: responseSchema ? {
-                            jsonSchema: responseSchema,
-                            schemaName: "tool_final_text",
-                        } : undefined,
-                        signal,
-                    });
-
-                    finalMessage = textResult.structured?.message || textResult.message;
-                    if (textResult.structured) {
-                        followUpStructured = textResult.structured;
-                    }
-
-                    logger.debug(`[ToolLoopExecutor] Generated final text response after tool loop:`, {
-                        hasMessage: !!finalMessage,
-                        messageLength: finalMessage?.length || 0,
-                    });
-                } catch (error) {
-                    logger.error(`[ToolLoopExecutor] Failed to generate final text response after tool loop:`, error);
-                    // finalMessage remains undefined; caller will use original message as fallback
+                if (forced.structured) {
+                    followUpStructured = forced.structured;
                 }
             }
 
@@ -377,12 +342,83 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
         }
     }
 
+    /**
+     * After tools have executed but the model produced no closing text, make one
+     * more LLM call (no tools) that turns the tool results into a user-facing
+     * message. Shared by the non-streaming tool loop and the streaming batch so
+     * both paths behave identically. Returns an empty object if the call fails
+     * or yields nothing, leaving the caller to fall back to its prior message.
+     */
+    private async forceFinalTextFromTools(params: {
+        history: HistoryItem[];
+        toolResultsMap: Map<string, string>;
+        toolArgsMap: Map<string, Record<string, unknown>>;
+        responsePrompt: string;
+        responseSchema?: Record<string, unknown>;
+        context: TContext;
+        signal?: AbortSignal;
+    }): Promise<{ finalMessage?: string; structured?: AgentStructuredResponse }> {
+        const { history, toolResultsMap, toolArgsMap, responsePrompt, responseSchema, context, signal } = params;
+
+        // Reconstruct assistant tool_call + tool result pairs so the follow-up
+        // call can see what the tools returned.
+        const finalToolResultHistoryItems: HistoryItem[] = [];
+        for (const [toolName, toolResult] of toolResultsMap) {
+            finalToolResultHistoryItems.push({
+                role: "assistant" as const,
+                content: null,
+                tool_calls: [{
+                    id: toolName,
+                    name: toolName,
+                    arguments: toolArgsMap.get(toolName) || {},
+                }],
+            });
+            finalToolResultHistoryItems.push({
+                role: "tool" as const,
+                tool_call_id: toolName,
+                name: toolName,
+                content: toolResult,
+            });
+        }
+
+        const finalHistory = [...history, ...finalToolResultHistoryItems];
+        const agentOptions = this.deps.getAgentOptions();
+
+        try {
+            const textResult = await agentOptions.provider.generateMessage({
+                prompt: responsePrompt + "\n\nProvide a text response to the user based on the tool results. Do not call any tools.",
+                history: finalHistory,
+                context,
+                tools: [], // No tools - force text response
+                parameters: responseSchema ? {
+                    jsonSchema: responseSchema,
+                    schemaName: "tool_final_text",
+                } : undefined,
+                signal,
+            });
+
+            const finalMessage = textResult.structured?.message || textResult.message;
+            logger.debug(`[ToolLoopExecutor] Generated final text response from tool results:`, {
+                hasMessage: !!finalMessage,
+                messageLength: finalMessage?.length || 0,
+            });
+            return { finalMessage, structured: textResult.structured };
+        } catch (error) {
+            logger.error(`[ToolLoopExecutor] Failed to generate final text response from tool results:`, error);
+            // Leave the caller to fall back to its prior message.
+            return {};
+        }
+    }
+
     /**
      * Execute the streaming path's initial batch of tool calls concurrently
      * via ToolManager.executeWithConcurrency, yielding tool-progress chunks.
-     * Falls back to `runLoop()` when concurrent execution fails.
+     * When tools ran but the model produced no closing text, forces a final
+     * text response from the tool results (mirroring `runLoop()`). Falls back
+     * to `runLoop()` when concurrent execution fails.
      *
-     * Returns the updated session and the final tool calls.
+     * Returns the updated session, final tool calls, and any forced closing
+     * message/structured response.
      */
     async *runStreamingBatch(params: {
         toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }>;
@@ -407,6 +443,9 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
         {
             session: SessionState<TData>;
             toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }> | undefined;
+            /** Closing message forced from the tool results, if one was generated. */
+            finalMessage?: string;
+            structured?: AgentStructuredResponse;
         }
     > {
         const { context, history, selectedFlow, step, accumulated, responsePrompt, availableTools, responseSchema, signal } = params;
@@ -419,9 +458,17 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             toolName: tc.toolName,
             arguments: tc.arguments,
         }));
+        // Map request id -> request so completed results can be attributed back
+        // to their tool name/arguments for the forced final-text call.
+        const requestById = new Map(toolCallRequests.map((r) => [r.id, r]));
+        const toolResultsMap = new Map<string, string>();
+        const toolArgsMap = new Map<string, Record<string, unknown>>();
 
         const historyEvents = historyToEvents(history);
 
+        let finalMessage: string | undefined;
+        let structured: AgentStructuredResponse | undefined;
+
         try {
             for await (const update of this.deps.toolManager.executeWithConcurrency({
                 toolCalls: toolCallRequests,
@@ -450,6 +497,15 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                     }
                 }
 
+                // Capture tool results for the forced final-text call
+                if (update.result) {
+                    const req = requestById.get(update.toolCallId);
+                    if (req) {
+                        toolResultsMap.set(req.toolName, serializeToolResult(update.result));
+                        toolArgsMap.set(req.toolName, req.arguments);
+                    }
+                }
+
                 // Yield progress updates immediately
                 if (update.progress) {
                     yield {
@@ -465,6 +521,23 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             }
 
             logger.debug(`[ToolLoopExecutor] Concurrent tool execution completed for ${toolCallRequests.length} tools`);
+
+            // Tools ran but streaming produced no post-tool message — force one
+            // from the results, mirroring runLoop. (The streaming chunk only ever
+            // carries the pre-tool preamble, never a result-aware response.)
+            if (toolResultsMap.size > 0) {
+                const forced = await this.forceFinalTextFromTools({
+                    history,
+                    toolResultsMap,
+                    toolArgsMap,
+                    responsePrompt,
+                    responseSchema,
+                    context,
+                    signal,
+                });
+                finalMessage = forced.finalMessage;
+                structured = forced.structured;
+            }
         } catch (error) {
             logger.error(`[ToolLoopExecutor] Concurrent tool execution failed, falling back to sequential:`, error);
             // Fall back to the unified tool loop on failure
@@ -474,9 +547,11 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
             });
             session = toolResult.session;
             toolCalls = toolResult.finalToolCalls;
+            finalMessage = toolResult.finalMessage;
+            structured = toolResult.structured;
         }
 
-        return { session, toolCalls };
+        return { session, toolCalls, finalMessage, structured };
     }
 
     /**