@falai/agent 2.4.1 → 2.4.3

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;
+}

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/types/signals.ts

@@ -327,6 +327,12 @@ export interface SignalFiring<TContext = unknown, TData = unknown> {
     directive?: ResolvedSignalDirective<TContext, TData>;
     /** Error message if the handler threw. */
     handlerError?: string;
+    /**
+     * Set when the signal matched in extraction mode (`extract` defined) but the
+     * classifier returned no extracted payload — the handler ran with
+     * `extracted: undefined`. Independent of `handlerError`.
+     */
+    extractionError?: string;
     /** Wall-clock duration of the handler invocation in milliseconds. */
     durationMs?: number;
 }

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));
+    }
+  }
+}