@falai/agent 2.4.2 → 2.4.3

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, logger } from "../utils";
+import { withTimeoutAndRetry, withStreamRetry, logger } from "../utils";
 import {
   classifyProviderError,
   getErrorMessage,
@@ -106,8 +106,12 @@ export class AnthropicProvider implements AiProvider {
     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,
-      retries: retryConfig?.retries || DEFAULT_RETRY_CONFIG.retries,
+      // `??` 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,
     };
   }
 
@@ -377,6 +381,17 @@ 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");
+      }
+
       return {
         message,
         metadata: {
@@ -407,9 +422,9 @@ export class AnthropicProvider implements AiProvider {
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Try primary model first
     try {
-      yield* this.generateStreamWithModel<TContext, TStructured>(
-        this.primaryModel,
-        input
+      yield* withStreamRetry(
+        () => this.generateStreamWithModel<TContext, TStructured>(this.primaryModel, input),
+        { maxRetries: this.retryConfig.retries, operationName: `Anthropic ${this.primaryModel} stream` }
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
@@ -433,9 +448,9 @@ export class AnthropicProvider implements AiProvider {
         );
 
         try {
-          yield* this.generateStreamWithModel<TContext, TStructured>(
-            backupModel,
-            input
+          yield* withStreamRetry(
+            () => this.generateStreamWithModel<TContext, TStructured>(backupModel, input),
+            { maxRetries: this.retryConfig.retries, operationName: `Anthropic ${backupModel} stream` }
           );
           logger.debug(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
           return;
@@ -597,6 +612,18 @@ 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");
+    }
+
     // Yield final chunk
     yield {
       delta: "",

package/src/providers/GeminiProvider.ts

@@ -21,7 +21,7 @@ import type {
 } from "../types";
 import type { ProviderCapabilities } from "../types/ai";
 import type { HistoryItem } from "../types/history";
-import { withTimeoutAndRetry } from "../utils/retry";
+import { withTimeoutAndRetry, withStreamRetry } from "../utils/retry";
 import { tryParseJSONResponse } from "../utils/json";
 import { logger } from "../utils/logger";
 import {
@@ -107,8 +107,12 @@ export class GeminiProvider implements AiProvider {
     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,
-      retries: retryConfig?.retries || DEFAULT_RETRY_CONFIG.retries,
+      // `??` 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,
     };
   }
 
@@ -538,6 +542,17 @@ 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");
+      }
+
       return {
         message,
         metadata: {
@@ -566,7 +581,10 @@ export class GeminiProvider implements AiProvider {
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Try primary model first
     try {
-      yield* this.generateStreamWithModel(this.primaryModel, input);
+      yield* withStreamRetry(
+        () => this.generateStreamWithModel(this.primaryModel, input),
+        { maxRetries: this.retryConfig.retries, operationName: `Gemini ${this.primaryModel} stream` }
+      );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
       logger.warn(
@@ -589,7 +607,10 @@ export class GeminiProvider implements AiProvider {
         );
 
         try {
-          yield* this.generateStreamWithModel(backupModel, input);
+          yield* withStreamRetry(
+            () => this.generateStreamWithModel(backupModel, input),
+            { maxRetries: this.retryConfig.retries, operationName: `Gemini ${backupModel} stream` }
+          );
           logger.debug(`[GEMINI] Backup model ${backupModel} succeeded`);
           return;
         } catch (backupError: unknown) {
@@ -747,6 +768,18 @@ 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");
+    }
+
     // Yield final chunk
     yield {
       delta: "",

package/src/providers/OpenAICompatibleProvider.ts

@@ -27,7 +27,7 @@ import type {
 } from "../types";
 import type { ProviderCapabilities } from "../types/ai";
 import type { HistoryItem } from "../types/history";
-import { withTimeoutAndRetry, logger } from "../utils";
+import { withTimeoutAndRetry, withStreamRetry, logger } from "../utils";
 import {
   classifyProviderError,
   getErrorMessage,
@@ -100,8 +100,12 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
     this.backupModels = init.backupModels ?? [];
     this.config = init.config;
     this.retryConfig = {
+      // `||` is intentional: a 0ms timeout is degenerate (aborts every call
+      // immediately), so fall back to the default.
       timeout: init.retryConfig?.timeout || DEFAULT_RETRY_CONFIG.timeout,
-      retries: init.retryConfig?.retries || DEFAULT_RETRY_CONFIG.retries,
+      // `??` so an explicit `retries: 0` (disable retries) is honored instead of
+      // being clobbered to the default by a falsy-zero check.
+      retries: init.retryConfig?.retries ?? DEFAULT_RETRY_CONFIG.retries,
     };
   }
 
@@ -408,9 +412,9 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Try primary model first
     try {
-      yield* this.generateStreamWithModel<TContext, TStructured>(
-        this.primaryModel,
-        input
+      yield* withStreamRetry(
+        () => this.generateStreamWithModel<TContext, TStructured>(this.primaryModel, input),
+        { maxRetries: this.retryConfig.retries, operationName: `${this.logLabel} ${this.primaryModel} stream` }
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
@@ -435,9 +439,9 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
         );
 
         try {
-          yield* this.generateStreamWithModel<TContext, TStructured>(
-            backupModel,
-            input
+          yield* withStreamRetry(
+            () => this.generateStreamWithModel<TContext, TStructured>(backupModel, input),
+            { maxRetries: this.retryConfig.retries, operationName: `${this.logLabel} ${backupModel} stream` }
           );
           logger.debug(`[${this.logLabel}] Backup model ${backupModel} succeeded`);
           return;
@@ -580,6 +584,17 @@ export abstract class OpenAICompatibleProvider 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 ${this.displayName}`);
+    }
+
     return {
       message,
       metadata: {
@@ -720,6 +735,19 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
       } as TStructured;
     }
 
+    // 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 structuredMessage = (structured as AgentStructuredResponse | undefined)?.message;
+    const messageText = (
+      typeof structuredMessage === "string" ? structuredMessage : accumulated
+    ).trim();
+    if (!messageText && toolCalls.length === 0) {
+      throw new Error(`No response from ${this.displayName}`);
+    }
+
     // Yield final chunk
     yield {
       delta: "",

package/src/utils/index.ts

@@ -55,8 +55,8 @@ export {
 export { LoggerLevel, logger } from "./logger";
 
 // Retry utilities
-export type { RetryOptions } from "./retry";
-export { retry, withTimeoutAndRetry } from "./retry";
+export type { RetryOptions, StreamRetryOptions } from "./retry";
+export { retry, withTimeoutAndRetry, withStreamRetry } from "./retry";
 
 // Condition utilities
 export {

package/src/utils/retry.ts

@@ -95,3 +95,58 @@ export const withTimeoutAndRetry = async <T>(
     },
   });
 };
+
+export interface StreamRetryOptions {
+  /** Maximum number of retries after the first attempt. Defaults to 3. */
+  maxRetries?: number;
+  /** Backoff before the next attempt, in ms. Defaults to capped exponential. */
+  delay?: (attempt: number) => number;
+  /** Label used in retry logs. */
+  operationName?: string;
+}
+
+/**
+ * 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<T>(
+  factory: () => AsyncGenerator<T>,
+  options: StreamRetryOptions = {}
+): AsyncGenerator<T> {
+  const {
+    maxRetries = 3,
+    delay = (attempt: number) => 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: unknown) {
+      // 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));
+    }
+  }
+}