@falai/agent 2.4.3 → 2.6.0

package/src/core/ToolLoopExecutor.ts

@@ -26,7 +26,7 @@ import type { Flow } from "./Flow";
 import type { Step } from "./Step";
 import type { ToolManager } from "./ToolManager";
 import { ResponseGenerationError } from "./ResponseGenerationError";
-import { historyToEvents, logger, serializeToolResult } from "../utils";
+import { historyToEvents, logger, serializeToolResult, assistantMessage, toolMessage } from "../utils";
 
 export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
     constructor(
@@ -72,7 +72,10 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
     }> {
         try {
             const { context, history, selectedFlow, responsePrompt, availableTools, responseSchema, signal } = params;
-            let { toolCalls, session } = params;
+            // The follow-up loop (which reassigned toolCalls) now lives in
+            // runFollowUpLoop; here toolCalls is only read.
+            const { toolCalls } = params;
+            let { session } = params;
 
             // Convert HistoryItem[] to Event[] for internal processing
             const historyEvents = historyToEvents(history);
@@ -146,6 +149,66 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                 }
             }
 
+            // Hand off to the multi-round follow-up loop shared with the
+            // streaming path. The initial batch above already executed
+            // sequentially and populated the result maps.
+            return await this.runFollowUpLoop({
+                toolCalls,
+                session,
+                toolResultsMap,
+                toolArgsMap,
+                context,
+                history,
+                selectedFlow,
+                responsePrompt,
+                availableTools,
+                responseSchema,
+                signal,
+            });
+        } catch (error) {
+            throw ResponseGenerationError.fromError(error, 'tool_execution', params, {
+                toolCallsCount: params.toolCalls?.length || 0,
+                availableToolsCount: params.availableTools.length
+            });
+        }
+    }
+
+    /**
+     * The multi-round follow-up loop shared by the non-streaming (`runLoop`) and
+     * streaming (`runStreamingBatch`) tool paths: re-prompt the model with the
+     * tool results (tools available on the first round so it can chain further
+     * calls), execute any further tool calls, repeat up to `maxToolLoops`, then
+     * force a result-aware closing message if the model never produced one.
+     * Callers run the *initial* batch — sequentially for `runLoop`, concurrently
+     * (with progress) for `runStreamingBatch` — and pass the populated result
+     * maps; from here both paths behave identically.
+     */
+    private async runFollowUpLoop(params: {
+        toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+        session: SessionState<TData>;
+        toolResultsMap: Map<string, string>;
+        toolArgsMap: Map<string, Record<string, unknown>>;
+        context: TContext;
+        history: HistoryItem[];
+        selectedFlow?: Flow<TContext, TData>;
+        responsePrompt: string;
+        availableTools: Array<{
+            id: string;
+            name: string;
+            description?: string;
+            parameters?: unknown;
+        }>;
+        responseSchema?: Record<string, unknown>;
+        signal?: AbortSignal;
+    }): Promise<{
+        session: SessionState<TData>;
+        finalToolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+        finalMessage?: string;
+        structured?: AgentStructuredResponse;
+    }> {
+        const { context, history, selectedFlow, responsePrompt, availableTools, responseSchema, signal, toolResultsMap, toolArgsMap } = params;
+        let { toolCalls, session } = params;
+        try {
             // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution
             // `??` so an explicit `maxToolLoops: 0` is honored instead of being
             // clobbered to the default by a falsy-zero check.
@@ -164,24 +227,18 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
                 for (const toolCall of toolCalls || []) {
                     const tool = this.findAvailableTool(toolCall.toolName, selectedFlow);
                     if (tool) {
-                        // Create HistoryItem format for tool results
-                        // Add assistant message with tool_calls
-                        toolResultHistoryItems.push({
-                            role: "assistant" as const,
-                            content: null,
-                            tool_calls: [{
-                                id: toolCall.toolName,
-                                name: toolCall.toolName,
-                                arguments: toolCall.arguments,
-                            }],
-                        });
-                        // Add tool result
-                        toolResultHistoryItems.push({
-                            role: "tool" as const,
-                            tool_call_id: toolCall.toolName,
-                            name: toolCall.toolName,
-                            content: toolResultsMap.get(toolCall.toolName) || "Tool executed successfully",
-                        });
+                        // assistant tool_call + tool result pair, via the shared
+                        // history factories (same as forceFinalTextFromTools).
+                        toolResultHistoryItems.push(
+                            assistantMessage(null, [
+                                { id: toolCall.toolName, name: toolCall.toolName, arguments: toolCall.arguments },
+                            ]),
+                            toolMessage(
+                                toolCall.toolName,
+                                toolCall.toolName,
+                                toolResultsMap.get(toolCall.toolName) || "Tool executed successfully",
+                            ),
+                        );
                     }
                 }
 
@@ -364,21 +421,12 @@ export class ToolLoopExecutor<TContext = unknown, TData = unknown> {
         // 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,
-            });
+            finalToolResultHistoryItems.push(
+                assistantMessage(null, [
+                    { id: toolName, name: toolName, arguments: toolArgsMap.get(toolName) || {} },
+                ]),
+                toolMessage(toolName, toolName, toolResult),
+            );
         }
 
         const finalHistory = [...history, ...finalToolResultHistoryItems];
@@ -522,25 +570,33 @@ 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;
-            }
+            // Multi-round follow-up shared with the non-streaming path: re-prompt
+            // with the tool results so the model can chain further tool calls,
+            // then produce result-aware closing text (forced if it never does).
+            // Previously a single forced-text call — streaming now loops to parity
+            // with runLoop, so a streamed turn can chain tools across rounds.
+            const followUp = await this.runFollowUpLoop({
+                toolCalls,
+                session,
+                toolResultsMap,
+                toolArgsMap,
+                context,
+                history,
+                selectedFlow,
+                responsePrompt,
+                availableTools,
+                responseSchema,
+                signal,
+            });
+            session = followUp.session;
+            toolCalls = followUp.finalToolCalls;
+            finalMessage = followUp.finalMessage;
+            structured = followUp.structured;
         } catch (error) {
             logger.error(`[ToolLoopExecutor] Concurrent tool execution failed, falling back to sequential:`, error);
-            // Fall back to the unified tool loop on failure
+            // Fall back to the unified tool loop on failure. runLoop re-executes
+            // the tools from scratch, so any partial results collected above are
+            // intentionally discarded (it builds and forces its own).
             const toolResult = await this.runLoop({
                 toolCalls, context, session, history, selectedFlow,
                 responsePrompt, availableTools, responseSchema, signal,

package/src/index.ts

@@ -32,6 +32,9 @@ export { DeepSeekProvider } from "./providers/DeepSeekProvider";
 export type { DeepSeekProviderOptions } from "./providers/DeepSeekProvider";
 // Base class for building OpenAI-compatible providers (Groq, Together, etc.)
 export { OpenAICompatibleProvider } from "./providers/OpenAICompatibleProvider";
+export type { StructuredOutputMode } from "./providers/OpenAICompatibleProvider";
+export { createOpenAICompatibleProvider } from "./providers/GenericOpenAICompatibleProvider";
+export type { OpenAICompatibleOptions } from "./providers/GenericOpenAICompatibleProvider";
 
 // Adapters
 export { PrismaAdapter } from "./adapters/PrismaAdapter";

package/src/providers/AnthropicProvider.ts

@@ -17,7 +17,7 @@ import type {
 } from "../types";
 import type { ProviderCapabilities } from "../types/ai";
 import type { HistoryItem } from "../types/history";
-import { withTimeoutAndRetry, withStreamRetry, logger } from "../utils";
+import { withTimeoutAndRetry, withStreamRetry, resolveRetryConfig, logger, assertUsableCompletion, combineAbortSignals } from "../utils";
 import {
   classifyProviderError,
   getErrorMessage,
@@ -26,11 +26,6 @@ import {
   type ErrorClassificationOptions,
 } from "./errorClassification";
 
-const DEFAULT_RETRY_CONFIG = {
-  timeout: 60000,
-  retries: 3,
-};
-
 /**
  * Configuration options for Anthropic provider
  * Uses types from @anthropic-ai/sdk package
@@ -105,14 +100,7 @@ export class AnthropicProvider implements AiProvider {
     this.primaryModel = model;
     this.backupModels = backupModels;
     this.config = config;
-    this.retryConfig = {
-      // `||` is intentional: a 0ms timeout is degenerate (aborts every call
-      // immediately), so fall back to the default.
-      timeout: retryConfig?.timeout || DEFAULT_RETRY_CONFIG.timeout,
-      // `??` so an explicit `retries: 0` (disable retries) is honored instead of
-      // being clobbered to the default by a falsy-zero check.
-      retries: retryConfig?.retries ?? DEFAULT_RETRY_CONFIG.retries,
-    };
+    this.retryConfig = resolveRetryConfig(retryConfig);
   }
 
   /**
@@ -268,7 +256,7 @@ export class AnthropicProvider implements AiProvider {
     model: string,
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput<TStructured>> {
-    const operation = async (): Promise<GenerateMessageOutput> => {
+    const operation = async (signal: AbortSignal): Promise<GenerateMessageOutput> => {
       // Anthropic requires max_tokens to be specified
       const maxTokens = input.parameters?.maxOutputTokens || 4096;
 
@@ -332,7 +320,9 @@ export class AnthropicProvider implements AiProvider {
         }
       }
 
-      const response = await this.client.messages.create(params);
+      const response = await this.client.messages.create(params, {
+        signal: combineAbortSignals(input.signal, signal),
+      });
 
       // Extract text and tool calls from response
       const textContent = response.content.find(
@@ -381,16 +371,10 @@ export class AnthropicProvider implements AiProvider {
         } as AgentStructuredResponse;
       }
 
-      // A parsed-but-blank structured message with no tool calls is just as
-      // empty as no text at all — throw so withTimeoutAndRetry retries instead
-      // of returning {"message":""}.
-      if (
-        toolCalls.length === 0 &&
-        typeof structured?.message === "string" &&
-        !structured.message.trim()
-      ) {
-        throw new Error("No response from Anthropic");
-      }
+      // A parsed-but-blank message with no tool calls is as empty as no text;
+      // the shared guard throws so withTimeoutAndRetry retries instead of
+      // returning {"message":""}.
+      assertUsableCompletion(structured, message, toolCalls.length, "Anthropic");
 
       return {
         message,
@@ -423,8 +407,8 @@ export class AnthropicProvider implements AiProvider {
     // Try primary model first
     try {
       yield* withStreamRetry(
-        () => this.generateStreamWithModel<TContext, TStructured>(this.primaryModel, input),
-        { maxRetries: this.retryConfig.retries, operationName: `Anthropic ${this.primaryModel} stream` }
+        (signal) => this.generateStreamWithModel<TContext, TStructured>(this.primaryModel, input, signal),
+        { maxRetries: this.retryConfig.retries, firstChunkTimeoutMs: this.retryConfig.timeout, operationName: `Anthropic ${this.primaryModel} stream` }
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
@@ -449,8 +433,8 @@ export class AnthropicProvider implements AiProvider {
 
         try {
           yield* withStreamRetry(
-            () => this.generateStreamWithModel<TContext, TStructured>(backupModel, input),
-            { maxRetries: this.retryConfig.retries, operationName: `Anthropic ${backupModel} stream` }
+            (signal) => this.generateStreamWithModel<TContext, TStructured>(backupModel, input, signal),
+            { maxRetries: this.retryConfig.retries, firstChunkTimeoutMs: this.retryConfig.timeout, operationName: `Anthropic ${backupModel} stream` }
           );
           logger.debug(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
           return;
@@ -486,7 +470,8 @@ export class AnthropicProvider implements AiProvider {
     TStructured = AgentStructuredResponse
   >(
     model: string,
-    input: GenerateMessageInput<TContext>
+    input: GenerateMessageInput<TContext>,
+    attemptSignal?: AbortSignal
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Anthropic requires max_tokens to be specified
     const maxTokens = input.parameters?.maxOutputTokens || 4096;
@@ -551,7 +536,9 @@ export class AnthropicProvider implements AiProvider {
       }
     }
 
-    const stream = this.client.messages.stream(params);
+    const stream = this.client.messages.stream(params, {
+      signal: combineAbortSignals(input.signal, attemptSignal),
+    });
 
     let accumulated = "";
     let currentModel = model;
@@ -612,17 +599,9 @@ export class AnthropicProvider implements AiProvider {
       } as AgentStructuredResponse;
     }
 
-    // Empty-completion guard — mirror of the non-streaming path. A blank
-    // effective message (structured message under a schema, else accumulated
-    // text) with no tool calls means the model produced nothing usable; throw
-    // so withStreamRetry/generateStreamWithBackup retry instead of silently
-    // emitting an empty message.
-    const messageText = (
-      typeof structured?.message === "string" ? structured.message : accumulated
-    ).trim();
-    if (!messageText && toolCalls.length === 0) {
-      throw new Error("No response from Anthropic");
-    }
+    // Empty-completion guard — same definition as the non-streaming path, so the
+    // stream retries / falls back to backup instead of emitting an empty message.
+    assertUsableCompletion(structured, accumulated, toolCalls.length, "Anthropic");
 
     // Yield final chunk
     yield {

package/src/providers/DeepSeekProvider.ts

@@ -7,15 +7,9 @@
 import OpenAI from "openai";
 import type {
   ChatCompletionChunk,
-  ChatCompletionCreateParamsNonStreaming,
   ChatCompletionCreateParamsStreaming,
 } from "openai/resources/chat/completions";
 
-import type {
-  GenerateMessageInput,
-  GenerateMessageOutput,
-  StructuredSchema,
-} from "../types";
 import type { ProviderCapabilities } from "../types/ai";
 import { logger } from "../utils";
 import {
@@ -96,38 +90,12 @@ export class DeepSeekProvider extends OpenAICompatibleProvider {
       backupModels,
       config,
       retryConfig,
+      // DeepSeek has no responses.parse API; structured output goes through
+      // chat completions with a native json_schema response_format.
+      structuredOutput: "json_schema",
     });
   }
 
-  /**
-   * DeepSeek has no responses.parse API; structured output goes through
-   * chat completions with a json_schema response_format.
-   */
-  protected override async executeStructuredGenerate(
-    model: string,
-    input: GenerateMessageInput<unknown>,
-    _jsonSchema: StructuredSchema
-  ): Promise<GenerateMessageOutput> {
-    return this.executeChatCompletion(model, input);
-  }
-
-  /**
-   * DeepSeek supports native json_schema enforcement in chat completions
-   * (both streaming and non-streaming).
-   */
-  protected override structuredResponseFormat(
-    jsonSchema: StructuredSchema,
-    schemaName: string | undefined
-  ): ChatCompletionCreateParamsNonStreaming["response_format"] {
-    return {
-      type: "json_schema" as const,
-      json_schema: {
-        name: schemaName || "structured_output",
-        schema: this.adaptSchema(jsonSchema),
-      },
-    };
-  }
-
   /**
    * DeepSeek reports usage in streaming chunks when explicitly requested.
    */

package/src/providers/GeminiProvider.ts

@@ -21,7 +21,8 @@ import type {
 } from "../types";
 import type { ProviderCapabilities } from "../types/ai";
 import type { HistoryItem } from "../types/history";
-import { withTimeoutAndRetry, withStreamRetry } from "../utils/retry";
+import { withTimeoutAndRetry, withStreamRetry, resolveRetryConfig, combineAbortSignals } from "../utils/retry";
+import { assertUsableCompletion } from "../utils/completion";
 import { tryParseJSONResponse } from "../utils/json";
 import { logger } from "../utils/logger";
 import {
@@ -32,11 +33,6 @@ import {
   type ErrorClassificationOptions,
 } from "./errorClassification";
 
-const DEFAULT_RETRY_CONFIG = {
-  timeout: 60000,
-  retries: 3,
-};
-
 /**
  * Configuration options for Gemini provider
  * Uses types from @google/genai package
@@ -106,14 +102,7 @@ export class GeminiProvider implements AiProvider {
     this.primaryModel = model;
     this.backupModels = backupModels;
     this.config = config;
-    this.retryConfig = {
-      // `||` is intentional: a 0ms timeout is degenerate (aborts every call
-      // immediately), so fall back to the default.
-      timeout: retryConfig?.timeout || DEFAULT_RETRY_CONFIG.timeout,
-      // `??` so an explicit `retries: 0` (disable retries) is honored instead of
-      // being clobbered to the default by a falsy-zero check.
-      retries: retryConfig?.retries ?? DEFAULT_RETRY_CONFIG.retries,
-    };
+    this.retryConfig = resolveRetryConfig(retryConfig);
   }
 
   /**
@@ -200,13 +189,15 @@ export class GeminiProvider implements AiProvider {
    *
    * @private
    */
-  private safeExtractText(responseOrChunk: { text?: string; candidates?: Array<{ content?: { parts?: Array<{ text?: string; functionCall?: unknown }> } }> }): string {
+  private safeExtractText(responseOrChunk: { text?: string; candidates?: Array<{ content?: { parts?: Array<{ text?: string; thought?: boolean; functionCall?: unknown }> } }> }): string {
     // Always extract text parts manually to avoid SDK warnings about
     // non-text parts like "thoughtSignature" in the response.
     const parts = responseOrChunk.candidates?.[0]?.content?.parts;
     if (parts) {
+      // Exclude reasoning parts (thought: true) — with includeThoughts enabled
+      // they carry text but must never leak into the user-facing message.
       return parts
-        .filter((p) => p.text != null)
+        .filter((p) => p.text != null && !p.thought)
         .map((p) => p.text)
         .join("");
     }
@@ -423,7 +414,7 @@ export class GeminiProvider implements AiProvider {
     model: string,
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput<TStructured>> {
-    const operation = async (): Promise<GenerateMessageOutput> => {
+    const operation = async (signal: AbortSignal): Promise<GenerateMessageOutput> => {
       // Schema-required: configure response schema
       const configOverride: Partial<GenerateContentConfig> = { ...this.config };
 
@@ -468,12 +459,13 @@ export class GeminiProvider implements AiProvider {
           }
         }
 
+        const reqSignal = combineAbortSignals(input.signal, signal);
         response = await this.genAI.models.generateContent({
           model,
           contents: historyContents,
           config: {
             ...configOverride,
-            ...(input.signal ? { abortSignal: input.signal } : {}),
+            ...(reqSignal ? { abortSignal: reqSignal } : {}),
           },
         });
       } catch (error: unknown) {
@@ -542,16 +534,10 @@ export class GeminiProvider implements AiProvider {
         } as AgentStructuredResponse;
       }
 
-      // A parsed-but-blank structured message with no tool calls is just as
-      // empty as no text at all — throw so withTimeoutAndRetry retries instead
-      // of returning {"message":""}.
-      if (
-        toolCalls.length === 0 &&
-        typeof structured?.message === "string" &&
-        !structured.message.trim()
-      ) {
-        throw new Error("No response from Gemini");
-      }
+      // A parsed-but-blank message with no tool calls is as empty as no text;
+      // the shared guard throws so withTimeoutAndRetry retries instead of
+      // returning {"message":""}.
+      assertUsableCompletion(structured, message, toolCalls.length, "Gemini");
 
       return {
         message,
@@ -582,8 +568,8 @@ export class GeminiProvider implements AiProvider {
     // Try primary model first
     try {
       yield* withStreamRetry(
-        () => this.generateStreamWithModel(this.primaryModel, input),
-        { maxRetries: this.retryConfig.retries, operationName: `Gemini ${this.primaryModel} stream` }
+        (signal) => this.generateStreamWithModel(this.primaryModel, input, signal),
+        { maxRetries: this.retryConfig.retries, firstChunkTimeoutMs: this.retryConfig.timeout, operationName: `Gemini ${this.primaryModel} stream` }
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
@@ -608,8 +594,8 @@ export class GeminiProvider implements AiProvider {
 
         try {
           yield* withStreamRetry(
-            () => this.generateStreamWithModel(backupModel, input),
-            { maxRetries: this.retryConfig.retries, operationName: `Gemini ${backupModel} stream` }
+            (signal) => this.generateStreamWithModel(backupModel, input, signal),
+            { maxRetries: this.retryConfig.retries, firstChunkTimeoutMs: this.retryConfig.timeout, operationName: `Gemini ${backupModel} stream` }
           );
           logger.debug(`[GEMINI] Backup model ${backupModel} succeeded`);
           return;
@@ -645,8 +631,11 @@ export class GeminiProvider implements AiProvider {
     TStructured = AgentStructuredResponse
   >(
     model: string,
-    input: GenerateMessageInput<TContext>
+    input: GenerateMessageInput<TContext>,
+    attemptSignal?: AbortSignal
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    // Caller cancellation + the retry helper's per-attempt deadline, as one.
+    const reqSignal = combineAbortSignals(input.signal, attemptSignal);
     // Streaming: request JSON if schema provided
     const configOverride: Partial<GenerateContentConfig> = { ...this.config };
 
@@ -696,7 +685,7 @@ export class GeminiProvider implements AiProvider {
         contents: historyContents,
         config: {
           ...configOverride,
-          ...(input.signal ? { abortSignal: input.signal } : {}),
+          ...(reqSignal ? { abortSignal: reqSignal } : {}),
         },
       });
     } catch (error: unknown) {
@@ -714,7 +703,7 @@ export class GeminiProvider implements AiProvider {
     }> = [];
 
     for await (const chunk of stream) {
-      if (input.signal?.aborted) break;
+      if (reqSignal?.aborted) break;
 
       // Safely extract text — chunk.text can throw when chunk has only function calls
       const delta = this.safeExtractText(chunk);
@@ -768,17 +757,9 @@ export class GeminiProvider implements AiProvider {
       } as AgentStructuredResponse;
     }
 
-    // Empty-completion guard — mirror of the non-streaming path. The effective
-    // message is the parsed structured message when a schema is used, else the
-    // accumulated text. A blank message with no tool calls means the model
-    // produced nothing usable; throw so withStreamRetry/generateStreamWithBackup
-    // retry instead of silently emitting an empty message.
-    const messageText = (
-      typeof structured?.message === "string" ? structured.message : accumulated
-    ).trim();
-    if (!messageText && toolCalls.length === 0) {
-      throw new Error("No response from Gemini");
-    }
+    // Empty-completion guard — same definition as the non-streaming path, so the
+    // stream retries / falls back to backup instead of emitting an empty message.
+    assertUsableCompletion(structured, accumulated, toolCalls.length, "Gemini");
 
     // Yield final chunk
     yield {