@falai/agent 2.4.2 → 2.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.4.2",
+  "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/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 };
     }
 
     /**

package/src/core/ToolManager.ts

@@ -24,6 +24,7 @@ import type { Agent } from "./Agent";
 import { Flow } from "./Flow";
 import { Step } from "./Step";
 import { StreamingToolExecutor } from "./StreamingToolExecutor";
+import { evaluateToolGates } from "./toolGates";
 
 /**
  * Error thrown when tool creation fails
@@ -715,38 +716,13 @@ export class ToolManager<TContext = unknown, TData = unknown> {
 
       logger.debug(`[ToolManager] Executing tool: ${tool.id} with args:`, toolArguments);
 
-      // Tool validation gate (Req 6.1, 6.7)
-      if (typeof tool.validateInput === 'function' && toolArguments) {
-        const validation = await tool.validateInput(toolArguments, toolContext);
-        if (!validation.valid) {
-          const executionTime = Date.now() - startTime;
-          logger.warn(`[DataValidationError] Tool "${tool.id}" input validation failed: ${validation.error}. Fix the tool call arguments to match the expected schema.`);
-          return {
-            success: false,
-            error: `Validation failed: ${validation.error || 'Invalid input'}`,
-            metadata: { toolId: tool.id, executionTime, gate: 'validateInput' }
-          };
-        }
-      }
-
-      // Tool permission gate (Req 6.7, 6.8)
-      // When denied: do not invoke handler, do not process directives, do not apply state writes
-      if (typeof tool.checkPermissions === 'function' && toolArguments) {
-        const permission = await tool.checkPermissions(toolArguments, toolContext);
-        if (!permission.allowed) {
-          const executionTime = Date.now() - startTime;
-          logger.warn(`[ToolExecutionError] Tool "${tool.id}" permission denied: ${permission.reason}. The tool's checkPermissions hook rejected this call.`);
-          return {
-            success: false,
-            error: `Permission denied: ${permission.reason || 'Not allowed'}`,
-            metadata: {
-              toolId: tool.id,
-              executionTime,
-              gate: 'checkPermissions',
-              canOverride: permission.canOverride
-            }
-          };
-        }
+      // Pre-execution gates (validateInput → checkPermissions). Shared with the
+      // streaming executor (StreamingToolExecutor) so authorization/validation
+      // behave identically on every transport. When a gate denies, the handler
+      // is NOT invoked.
+      const gateDenial = await evaluateToolGates(tool, toolArguments, toolContext, startTime);
+      if (gateDenial) {
+        return gateDenial;
       }
 
       // Execute tool with timeout protection

package/src/core/toolGates.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared pre-execution gates for tool calls.
+ *
+ * A tool's `validateInput` and `checkPermissions` hooks must be applied
+ * identically regardless of how the call is executed. Previously the gates
+ * lived only in `ToolManager.executeTool` (the sequential `generate()`/
+ * `respond()` path), so the streaming path (`StreamingToolExecutor`, used by
+ * `stream()`) invoked handlers without them — a documented authorization gate
+ * ("when denied, handler is NOT invoked") was silently a no-op on one
+ * transport. Centralizing the logic here keeps both executors in lockstep.
+ */
+import type { Tool, ToolContext, ToolExecutionResult } from "../types/tool";
+import { logger } from "../utils";
+
+/**
+ * Run a tool's pre-execution gates in order: `validateInput`, then
+ * `checkPermissions`. Returns a failed `ToolExecutionResult` when a gate
+ * blocks the call (the handler must NOT be invoked), or `null` when both
+ * gates pass.
+ *
+ * @param startTime - optional execution start time (ms from `Date.now()`).
+ *   When provided, denial metadata includes `executionTime`, matching the
+ *   sequential executor's result shape; omit it on the streaming path.
+ */
+export async function evaluateToolGates<TContext, TData>(
+  tool: Tool<TContext, TData>,
+  toolArguments: Record<string, unknown> | undefined,
+  toolContext: ToolContext<TContext, TData>,
+  startTime?: number
+): Promise<ToolExecutionResult | null> {
+  // Tool validation gate (Req 6.1, 6.7)
+  if (typeof tool.validateInput === "function" && toolArguments) {
+    const validation = await tool.validateInput(toolArguments, toolContext);
+    if (!validation.valid) {
+      logger.warn(
+        `[DataValidationError] Tool "${tool.id}" input validation failed: ${validation.error}. Fix the tool call arguments to match the expected schema.`
+      );
+      return {
+        success: false,
+        error: `Validation failed: ${validation.error || "Invalid input"}`,
+        metadata: {
+          toolId: tool.id,
+          ...(startTime !== undefined ? { executionTime: Date.now() - startTime } : {}),
+          gate: "validateInput",
+        },
+      };
+    }
+  }
+
+  // Tool permission gate (Req 6.7, 6.8)
+  // When denied: do not invoke handler, do not process directives, do not apply state writes
+  if (typeof tool.checkPermissions === "function" && toolArguments) {
+    const permission = await tool.checkPermissions(toolArguments, toolContext);
+    if (!permission.allowed) {
+      logger.warn(
+        `[ToolExecutionError] Tool "${tool.id}" permission denied: ${permission.reason}. The tool's checkPermissions hook rejected this call.`
+      );
+      return {
+        success: false,
+        error: `Permission denied: ${permission.reason || "Not allowed"}`,
+        metadata: {
+          toolId: tool.id,
+          ...(startTime !== undefined ? { executionTime: Date.now() - startTime } : {}),
+          gate: "checkPermissions",
+          canOverride: permission.canOverride,
+        },
+      };
+    }
+  }
+
+  return null;
+}