@falai/agent 1.2.4 → 1.2.6

package/src/core/ResponseModal.ts

@@ -139,6 +139,8 @@ interface ResponseContext<TContext = unknown, TData = unknown> {
     batchStoppedReason?: StoppedReason;
     /** Step that caused batch to stop (if applicable) */
     batchStoppedAtStep?: StepOptions<TContext, TData>;
+    /** AbortSignal for cancellation propagation */
+    signal?: AbortSignal;
 }
 
 /**
@@ -260,20 +262,28 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
         // Stream response using existing respondStream method
         let finalMessage = "";
+        let finalizedSession: SessionState<TData> | undefined;
         for await (const chunk of this.respondStream({
             history,
             session,
             contextOverride: options?.contextOverride,
             signal: options?.signal,
         })) {
-            // Accumulate the final message for session history
+            // Accumulate the final message and capture finalized session
             if (chunk.done) {
                 finalMessage = chunk.accumulated;
+                finalizedSession = chunk.session;
             }
 
             yield chunk;
         }
 
+        // Sync finalized session to agent.session.current (skip in override-history mode)
+        // Must happen BEFORE addMessage so the assistant message is added on top of the synced session state
+        if (!options?.history && finalizedSession) {
+            this.agent.session.syncSession(finalizedSession);
+        }
+
         // Add agent response to session history (only if not using override history)
         if (!options?.history && finalMessage) {
             await this.agent.session.addMessage("assistant", finalMessage);
@@ -320,6 +330,12 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             signal: options?.signal,
         });
 
+        // Sync finalized session to agent.session.current (skip in override-history mode)
+        // Must happen BEFORE addMessage so the assistant message is added on top of the synced session state
+        if (!options?.history && result.session) {
+            this.agent.session.syncSession(result.session);
+        }
+
         // Add agent response to session history (only if not using override history)
         if (!options?.history) {
             await this.agent.session.addMessage("assistant", result.message);
@@ -469,6 +485,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 batchSteps: routingResult.batchSteps,
                 batchStoppedReason: routingResult.batchStoppedReason,
                 batchStoppedAtStep: routingResult.batchStoppedAtStep,
+                signal,
             };
         } catch (error) {
             // Re-throw ResponseGenerationError as-is, wrap others
@@ -711,6 +728,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             isRouteComplete,
             batchSteps,
             batchStoppedReason,
+            signal,
         } = responseContext;
         let session = initialSession;
 
@@ -758,7 +776,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     history,
                     context: effectiveContext,
                     historyEvents,
-                    signal: undefined,
+                    signal,
                 });
 
                 message = result.message;
@@ -786,7 +804,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     context: effectiveContext,
                     history,
                     historyEvents,
-                    signal: undefined,
+                    signal,
                 });
 
                 // Set step to END_ROUTE marker
@@ -1517,7 +1535,11 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         }
 
         // Collect data from response
-        session = await this.collectDataFromResponse({ result, selectedRoute, nextStep, session });
+        // Use follow-up structured data from tool loop when available, fall back to original result
+        const dataSource = toolResult.structured
+            ? { structured: toolResult.structured }
+            : result;
+        session = await this.collectDataFromResponse({ result: dataSource, selectedRoute, nextStep, session });
 
         return { message, toolCalls, session };
     }
@@ -1769,6 +1791,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         session: SessionState<TData>;
         finalToolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
         finalMessage?: string;
+        structured?: AgentStructuredResponse;
     }> {
         try {
             const { context, history, selectedRoute, responsePrompt, availableTools, responseSchema, signal } = params;
@@ -1857,6 +1880,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             let toolLoopCount = 0;
             let hasToolCalls = toolCalls && toolCalls.length > 0;
             let finalMessage: string | undefined;
+            let followUpStructured: AgentStructuredResponse | undefined;
 
             while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
                 toolLoopCount++;
@@ -1998,6 +2022,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     logger.debug(`[ResponseModal] Tool loop completed after ${toolLoopCount} iterations`);
                     // Update final message and toolCalls from follow-up result if no more tools
                     finalMessage = followUpResult.structured?.message || followUpResult.message;
+                    followUpStructured = followUpResult.structured;
                     toolCalls = followUpToolCalls || [];
                     break;
                 }
@@ -2007,6 +2032,64 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 logger.warn(`[ResponseModal] Tool loop limit reached (${MAX_TOOL_LOOPS}), stopping`);
             }
 
+            // 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.
+            if (!finalMessage && toolLoopCount > 0) {
+                logger.debug(`[ResponseModal] No final message after tool loop, making additional LLM call for text response`);
+
+                // Build tool result history for the final call
+                const finalToolResultHistoryItems: HistoryItem[] = [];
+                for (const toolCall of toolCalls || []) {
+                    finalToolResultHistoryItems.push({
+                        role: "assistant" as const,
+                        content: null,
+                        tool_calls: [{
+                            id: toolCall.toolName,
+                            name: toolCall.toolName,
+                            arguments: toolCall.arguments,
+                        }],
+                    });
+                    finalToolResultHistoryItems.push({
+                        role: "tool" as const,
+                        tool_call_id: toolCall.toolName,
+                        name: toolCall.toolName,
+                        content: toolResultsMap.get(toolCall.toolName) || "Tool executed successfully",
+                    });
+                }
+
+                const finalHistory = [...history, ...finalToolResultHistoryItems];
+                const agentOptions = this.agent.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(`[ResponseModal] Generated final text response after tool loop:`, {
+                        hasMessage: !!finalMessage,
+                        messageLength: finalMessage?.length || 0,
+                    });
+                } catch (error) {
+                    logger.error(`[ResponseModal] Failed to generate final text response after tool loop:`, error);
+                    // finalMessage remains undefined; caller will use original message as fallback
+                }
+            }
+
             logger.debug(`[ResponseModal] Tool loop completed:`, {
                 totalIterations: toolLoopCount,
                 hasFinalMessage: !!finalMessage,
@@ -2018,6 +2101,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 session,
                 finalToolCalls: toolCalls,
                 finalMessage,
+                structured: followUpStructured,
             };
         } catch (error) {
             throw ResponseGenerationError.fromError(error, 'tool_execution', params, {

package/src/core/Route.ts

@@ -567,9 +567,8 @@ export class Route<TContext = unknown, TData = unknown> {
    * @param data - Currently collected agent-level data
    * @returns true if all required fields are present, false otherwise
    * 
-   * Note: Routes with no requiredFields AND no optionalFields are never complete
-   * based on data (they complete via END_ROUTE). Routes with only optionalFields
-   * are always complete (optional data doesn't block completion).
+   * Note: Routes with no requiredFields (whether they have optionalFields or not)
+   * are never complete based on data — they can only complete via END_ROUTE.
    */
   isComplete(data: Partial<TData>): boolean {
     // If route has required fields, check if they're all collected
@@ -580,9 +579,10 @@ export class Route<TContext = unknown, TData = unknown> {
       });
     }
 
-    // If route has optional fields but no required fields, it's always complete
+    // If route has optional fields but no required fields, it's NOT complete
+    // Optional-only routes can only complete via END_ROUTE
     if (this.optionalFields && this.optionalFields.length > 0) {
-      return true;
+      return false;
     }
 
     // No required or optional fields - route doesn't complete based on data
@@ -623,9 +623,10 @@ export class Route<TContext = unknown, TData = unknown> {
       return completedFields.length / this.requiredFields.length;
     }
 
-    // If route has optional fields but no required fields, it's always complete
+    // If route has optional fields but no required fields, it's NOT complete
+    // Optional-only routes can only complete via END_ROUTE, progress is 0
     if (this.optionalFields && this.optionalFields.length > 0) {
-      return 1;
+      return 0;
     }
 
     // No required or optional fields - route doesn't complete based on data

package/src/core/SessionManager.ts

@@ -298,6 +298,18 @@ export class SessionManager<TData = unknown> {
     return newSession;
   }
 
+  /**
+   * Sync the session state without triggering persistence save.
+   * Used by modern APIs (stream, generate, chat) to push the finalized session
+   * back to `currentSession` after completion. Persistence is handled separately
+   * by `finalizeSession()`.
+   *
+   * @internal Called from ResponseModal after stream()/generate() completion
+   */
+  syncSession(session: SessionState<TData>): void {
+    this.currentSession = session;
+  }
+
   /**
    * Get the persistence manager (for testing purposes)
    */