@falai/agent 2.6.0 → 2.7.0

package/src/core/ToolManager.ts

@@ -18,7 +18,7 @@ import type {
 } from "../types";
 import type { Directive } from "../types/flow";
 import { ToolScope } from "../types";
-import { logger } from "../utils";
+import { logger, isToolResultLike, extractResultDirectives } from "../utils";
 // Type-only import: ToolManager must not create a runtime cycle with Agent
 import type { Agent } from "./Agent";
 import { Flow } from "./Flow";
@@ -81,7 +81,7 @@ export class ToolManager<TContext = unknown, TData = unknown> {
    * Set the transient tool layer for the current turn.
    *
    * Accepts the merged `injectTools` array from pre-LLM emitters
-   * (already concatenated in outer-to-inner order by the DirectiveBus).
+   * (concatenated in outer-to-inner order).
    * Deduplicates by tool `id` with last-definition-wins.
    *
    * Must be paired with `clearTransientTools()` in a try/finally guard
@@ -678,6 +678,7 @@ export class ToolManager<TContext = unknown, TData = unknown> {
   }): Promise<ToolExecutionResult> {
     const { tool, context, updateContext, updateData, history, data, toolArguments } = params;
     const startTime = Date.now();
+      const executionTimeout = 30000; // 30 seconds default timeout
 
     try {
       // Validate tool before execution
@@ -725,24 +726,40 @@ export class ToolManager<TContext = unknown, TData = unknown> {
         return gateDenial;
       }
 
-      // Execute tool with timeout protection
-      const executionTimeout = 30000; // 30 seconds default timeout
+      // Execute tool with timeout protection. The timer is cleared when the
+      // race settles AND unref'd so a pending timer never delays process
+      // shutdown; a handler that loses the race keeps running detached (its
+      // result is discarded), which we surface in a warn.
+      let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
       const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error(`Tool execution timeout after ${executionTimeout}ms`)), executionTimeout);
+        timeoutTimer = setTimeout(
+          () => reject(new Error(`Tool execution timeout after ${executionTimeout}ms`)),
+          executionTimeout
+        );
+        timeoutTimer.unref?.();
       });
 
-      const result = await Promise.race([
-        tool.handler(toolContext, toolArguments),
-        timeoutPromise
-      ]);
+      let result: unknown;
+      try {
+        // Attach a no-op catch to the losing handler promise so a post-timeout
+        // rejection can't surface as an unhandled rejection and crash the process.
+        const handlerPromise = Promise.resolve(tool.handler(toolContext, toolArguments));
+        handlerPromise.catch(() => undefined);
+        result = await Promise.race([handlerPromise, timeoutPromise]);
+      } finally {
+        clearTimeout(timeoutTimer);
+      }
 
       const executionTime = Date.now() - startTime;
       logger.debug(`[ToolManager] Tool ${tool.id} completed in ${executionTime}ms`);
 
-      // Handle different result types
+      // Handle different result types. Only SEMANTIC markers identify a
+      // ToolResult — bare `{data}` / `{error}` shapes are indistinguishable
+      // from ordinary business payloads (e.g. upstream API envelopes) and are
+      // wrapped as raw results instead.
       let toolResult: ToolResult<unknown, TContext, TData>;
 
-      if (result && typeof result === 'object' && ('data' in result || 'success' in result || 'error' in result || 'directive' in result)) {
+      if (isToolResultLike(result)) {
         // It's already a ToolResult-like object
         toolResult = result as ToolResult<unknown, TContext, TData>;
       } else {
@@ -753,10 +770,9 @@ export class ToolManager<TContext = unknown, TData = unknown> {
         };
       }
 
-      // Collect directive from ToolResult.directive (if present)
-      if (toolResult.directive) {
-        collectedDirectives.push(toolResult.directive);
-      }
+      // Collect directives from the result — singular and plural forms both
+      // count, ordered identically to the concurrent executor.
+      collectedDirectives.push(...extractResultDirectives(toolResult));
 
       // Apply data updates from tool result with validation
       if (toolResult.dataUpdate) {
@@ -813,6 +829,15 @@ export class ToolManager<TContext = unknown, TData = unknown> {
       const executionTime = Date.now() - startTime;
 
       logger.error(`[ToolManager] Tool execution error for ${tool.id} after ${executionTime}ms:`, error);
+      if (error instanceof Error && error.message.includes("Tool execution timeout")) {
+        // The losing handler may still be running with captured callbacks.
+        // Its writes are NOT rolled back here — tools should stay idempotent
+        // or accept their own cancellation via interruptBehavior/abort.
+        logger.warn(
+          `[ToolManager] Handler for "${tool.id}" exceeded ${executionTimeout}ms and was abandoned while still running. ` +
+          `Its eventual side effects are not cancelled or rolled back.`
+        );
+      }
 
       // Re-throw the error so callers can handle it
       throw error;
@@ -871,9 +896,11 @@ export class ToolManager<TContext = unknown, TData = unknown> {
         return data != null && key in (data as Record<string, unknown>);
       },
       dispatch: (_directive: Directive<TContext, TData>): void => {
-        // Directives from concurrent execution are collected by the StreamingToolExecutor
-        // and surfaced via ToolExecutionUpdate. This is a no-op placeholder;
-        // full directive bus integration happens in ResponsePipeline (task 1.6).
+        // Handlers never see THIS context — StreamingToolExecutor.executeTool
+        // wraps each call in a per-call context whose dispatch attributes the
+        // directive to that tool. Reaching here means a gate or future caller
+        // dispatched outside a tool execution; surface it instead of dropping.
+        logger.warn("[ToolManager] ctx.dispatch called outside tool execution has no turn to attach to; directive dropped.");
       },
     };
 

package/src/core/flow-namespace.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Directive } from "../types/flow";
+import type { SessionState } from "../types/session";
 import { FlowConfigurationError } from "./Step";
 
 // ─── Position field metadata ─────────────────────────────────────────────────
@@ -181,6 +182,32 @@ function validate<TContext, TData>(d: Directive<TContext, TData>): void {
     }
 }
 
+/**
+ * Reduce an array of directives into one via the canonical Algorithm 4 merge
+ * (position precedence, reply last-wins, state shallow-merge, halt OR).
+ * Empty arrays yield undefined.
+ */
+function mergeAll<TContext, TData>(
+    directives: Directive<TContext, TData>[]
+): Directive<TContext, TData> | undefined {
+    if (directives.length === 0) return undefined;
+    return directives.reduce((a, b) => merge(a, b));
+}
+
+/**
+ * Queue a control directive on the session for the pendingDirective applier at
+ * the START of the next turn, merging with anything already queued via the
+ * canonical Algorithm 4 merge.
+ */
+function queuePending<TData>(
+    session: SessionState<TData>,
+    directive: Directive<unknown, TData>
+): void {
+    session.pendingDirective = session.pendingDirective
+        ? merge(session.pendingDirective, directive)
+        : directive;
+}
+
 /**
  * The `flow` namespace object. Exported as a single const for ergonomic usage:
  *
@@ -194,5 +221,7 @@ function validate<TContext, TData>(d: Directive<TContext, TData>): void {
 export const flow = {
     isDirective,
     merge,
+    mergeAll,
+    queuePending,
     validate,
 } as const;

package/src/index.ts

@@ -6,6 +6,9 @@
 
 // Core
 export { Agent } from "./core/Agent";
+export type { RespondParams, StreamOptions, GenerateOptions } from "./core/ResponseModal";
+export { ResponseGenerationError } from "./core/ResponseGenerationError";
+export type { EndedFlow } from "./types/agent";
 export { createAgent } from "./core/createAgent";
 export { Flow } from "./core/Flow";
 export { Step, FlowConfigurationError } from "./core/Step";
@@ -188,4 +191,4 @@ export type {
   ConditionWhen,
 } from "./types";
 export { EventKind, MessageRole } from "./types";
-export { createSession, createSessionId, createPersistedState, enterFlow, enterStep, completeCurrentFlow, isFlowCompletedThisSession, mergeCollected } from "./utils";
+export { restoreSession, createSession, createSessionId, createPersistedState, enterFlow, enterStep, completeCurrentFlow, isFlowCompletedThisSession, mergeCollected } from "./utils";

package/src/providers/AnthropicProvider.ts

@@ -17,11 +17,11 @@ import type {
 } from "../types";
 import type { ProviderCapabilities } from "../types/ai";
 import type { HistoryItem } from "../types/history";
-import { withTimeoutAndRetry, withStreamRetry, resolveRetryConfig, logger, assertUsableCompletion, combineAbortSignals } from "../utils";
+import { withTimeoutAndRetry, withStreamRetry, withBackupFallback, streamWithBackupFallback, backupFallbackLogging, resolveRetryConfig, logger, assertUsableCompletion, combineAbortSignals } from "../utils";
 import {
   classifyProviderError,
-  getErrorMessage,
   isBackupEligible,
+  isRetriableProviderError,
   toProviderError,
   type ErrorClassificationOptions,
 } from "./errorClassification";
@@ -31,9 +31,9 @@ import {
  * Uses types from @anthropic-ai/sdk package
  */
 export interface AnthropicProviderOptions {
-  /** Anthropic API key */
-  apiKey: string;
-  /** Model to use (required) - e.g., "claude-sonnet-4-6", "claude-opus-4-7" */
+  /** Anthropic API key. Optional when `client` is injected (tests). */
+  apiKey?: string;
+  /** Model to use (required) - e.g., "claude-sonnet-5", "claude-opus-5" */
   model: string;
   /** Backup models to try if primary fails (default: []) */
   backupModels?: string[];
@@ -44,6 +44,12 @@ export interface AnthropicProviderOptions {
     timeout?: number;
     retries?: number;
   };
+  /**
+   * Pre-configured SDK client. Overrides the internally-constructed one.
+   * Intended for tests injecting scripted transports; production callers
+   * should pass `apiKey` instead.
+   */
+  client?: Anthropic;
 }
 
 /**
@@ -73,7 +79,10 @@ export class AnthropicProvider implements AiProvider {
     supportsNativeJsonSchema: false, // JSON output is enforced via a prompt instruction, not a native schema mode
     supportsStreaming: true,
     supportsStreamingToolCalls: true,
-    supportsPromptCaching: true,
+    // No cache_control is attached to any request yet — reporting true would
+    // make consumers believe repeated system prompts are cached when they are
+    // not. Flip this when caching is actually implemented.
+    supportsPromptCaching: false,
   };
   private client: Anthropic;
   private primaryModel: string;
@@ -84,17 +93,17 @@ export class AnthropicProvider implements AiProvider {
   private retryConfig: { timeout: number; retries: number };
 
   constructor(options: AnthropicProviderOptions) {
-    const { apiKey, model, backupModels = [], config, retryConfig } = options;
+    const { apiKey, model, backupModels = [], config, retryConfig, client } = options;
 
-    if (!apiKey) {
+    if (!client && !apiKey) {
       throw new Error("Anthropic API key is required");
     }
 
     if (!model) {
-      throw new Error("Model is required. Example: 'claude-sonnet-4-6'");
+      throw new Error("Model is required. Example: 'claude-sonnet-5'");
     }
 
-    this.client = new Anthropic({
+    this.client = client ?? new Anthropic({
       apiKey,
     });
     this.primaryModel = model;
@@ -188,64 +197,19 @@ export class AnthropicProvider implements AiProvider {
   >(
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput<TStructured>> {
-    // Try primary model first
-    try {
-      return await this.generateWithModel<TContext, TStructured>(
-        this.primaryModel,
-        input
-      );
-    } catch (primaryError: unknown) {
-      const primaryErrMsg = getErrorMessage(primaryError);
-      logger.warn(
-        `[ANTHROPIC] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
-      );
-
-      if (!shouldUseBackupModel(primaryError)) {
-        throw toProviderError(primaryError, this.name, CLASSIFICATION_OPTIONS);
-      }
-
-      logger.debug(`[ANTHROPIC] Trying backup models`);
-
-      let lastBackupError: unknown = primaryError;
-
-      for (let i = 0; i < this.backupModels.length; i++) {
-        const backupModel = this.backupModels[i];
-        logger.debug(
-          `[ANTHROPIC] Trying backup model ${i + 1}/${this.backupModels.length
-          }: ${backupModel}`
-        );
-
-        try {
-          const result = await this.generateWithModel<TContext, TStructured>(
-            backupModel,
-            input
-          );
-          logger.debug(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
-          return result;
-        } catch (backupError: unknown) {
-          const backupErrMsg = getErrorMessage(backupError);
-          logger.warn(
-            `[ANTHROPIC] Backup model ${backupModel} failed: ${backupErrMsg}`
-          );
-          lastBackupError = backupError;
-
-          if (
-            !shouldUseBackupModel(backupError) &&
-            i < this.backupModels.length - 1
-          ) {
-            logger.debug(
-              `[ANTHROPIC] Backup model error doesn't qualify for further attempts`
-            );
-            break;
-          }
-        }
-      }
+    const observer = backupFallbackLogging("[ANTHROPIC]", shouldUseBackupModel);
 
-      const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      logger.error(
-        `[ANTHROPIC] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
-      );
-      throw toProviderError(lastBackupError, this.name, CLASSIFICATION_OPTIONS);
+    try {
+      return await withBackupFallback({
+        models: [this.primaryModel, ...this.backupModels],
+        attempt: (model) =>
+          this.generateWithModel<TContext, TStructured>(model, input),
+        shouldTryBackup: shouldUseBackupModel,
+        ...observer.callbacks,
+      });
+    } catch (error: unknown) {
+      observer.logExhausted(error);
+      throw toProviderError(error, this.name, CLASSIFICATION_OPTIONS);
     }
   }
 
@@ -394,7 +358,8 @@ export class AnthropicProvider implements AiProvider {
       operation,
       this.retryConfig.timeout,
       this.retryConfig.retries,
-      `Anthropic ${model}`
+      `Anthropic ${model}`,
+      (error) => isRetriableProviderError(error, CLASSIFICATION_OPTIONS)
     ) as Promise<GenerateMessageOutput<TStructured>>;
   }
 
@@ -404,64 +369,22 @@ export class AnthropicProvider implements AiProvider {
   >(
     input: GenerateMessageInput<TContext>
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
-    // Try primary model first
-    try {
-      yield* withStreamRetry(
-        (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);
-      logger.warn(
-        `[ANTHROPIC] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
-      );
-
-      if (!shouldUseBackupModel(primaryError)) {
-        throw toProviderError(primaryError, this.name, CLASSIFICATION_OPTIONS);
-      }
-
-      logger.debug(`[ANTHROPIC] Trying backup models for streaming`);
-
-      let lastBackupError: unknown = primaryError;
-
-      for (let i = 0; i < this.backupModels.length; i++) {
-        const backupModel = this.backupModels[i];
-        logger.debug(
-          `[ANTHROPIC] Trying backup model ${i + 1}/${this.backupModels.length
-          }: ${backupModel}`
-        );
+    const observer = backupFallbackLogging("[ANTHROPIC]", shouldUseBackupModel, { streaming: true });
 
-        try {
-          yield* withStreamRetry(
-            (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;
-        } catch (backupError: unknown) {
-          const backupErrMsg = getErrorMessage(backupError);
-          logger.warn(
-            `[ANTHROPIC] Backup model ${backupModel} failed: ${backupErrMsg}`
-          );
-          lastBackupError = backupError;
-
-          if (
-            !shouldUseBackupModel(backupError) &&
-            i < this.backupModels.length - 1
-          ) {
-            logger.debug(
-              `[ANTHROPIC] Backup model error doesn't qualify for further attempts`
-            );
-            break;
-          }
-        }
-      }
-
-      const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      logger.error(
-        `[ANTHROPIC] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
-      );
-      throw toProviderError(lastBackupError, this.name, CLASSIFICATION_OPTIONS);
+    try {
+      yield* streamWithBackupFallback({
+        models: [this.primaryModel, ...this.backupModels],
+        attempt: (model) =>
+          withStreamRetry(
+            (signal) => this.generateStreamWithModel<TContext, TStructured>(model, input, signal),
+            { maxRetries: this.retryConfig.retries, firstChunkTimeoutMs: this.retryConfig.timeout, operationName: `Anthropic ${model} stream`, isRetriable: (error) => isRetriableProviderError(error, CLASSIFICATION_OPTIONS) }
+          ),
+        shouldTryBackup: shouldUseBackupModel,
+        ...observer.callbacks,
+      });
+    } catch (error: unknown) {
+      observer.logExhausted(error);
+      throw toProviderError(error, this.name, CLASSIFICATION_OPTIONS);
     }
   }
 
@@ -545,10 +468,13 @@ export class AnthropicProvider implements AiProvider {
     let stopReason: string | undefined;
     let inputTokens = 0;
     let outputTokens = 0;
-    const toolCalls: Array<{
-      toolName: string;
-      arguments: Record<string, unknown>;
-    }> = [];
+    // Tool_use blocks arrive empty: content_block_start carries `input: {}`,
+    // the real arguments stream in later as input_json_delta partial_json
+    // fragments. Accumulate per block index and parse once at stream end.
+    const pendingToolBlocks = new Map<
+      number,
+      { toolName: string; argumentsBuffer: string }
+    >();
 
     for await (const chunk of stream) {
       if (chunk.type === "message_start") {
@@ -556,9 +482,9 @@ export class AnthropicProvider implements AiProvider {
         inputTokens = chunk.message.usage.input_tokens;
       } else if (chunk.type === "content_block_start") {
         if (chunk.content_block.type === "tool_use") {
-          toolCalls.push({
+          pendingToolBlocks.set(chunk.index, {
             toolName: chunk.content_block.name,
-            arguments: chunk.content_block.input as Record<string, unknown>,
+            argumentsBuffer: "",
           });
         }
       } else if (chunk.type === "content_block_delta") {
@@ -570,6 +496,11 @@ export class AnthropicProvider implements AiProvider {
             accumulated,
             done: false,
           } as GenerateMessageStreamChunk<TStructured>;
+        } else if (chunk.delta.type === "input_json_delta") {
+          const block = pendingToolBlocks.get(chunk.index);
+          if (block) {
+            block.argumentsBuffer += chunk.delta.partial_json;
+          }
         }
       } else if (chunk.type === "message_delta") {
         stopReason = chunk.delta.stop_reason || undefined;
@@ -577,6 +508,27 @@ export class AnthropicProvider implements AiProvider {
       }
     }
 
+    const toolCalls: Array<{
+      toolName: string;
+      arguments: Record<string, unknown>;
+    }> = [];
+    for (const [, block] of [...pendingToolBlocks.entries()].sort(
+      ([a], [b]) => a - b
+    )) {
+      let args: Record<string, unknown> = {};
+      if (block.argumentsBuffer) {
+        try {
+          args = JSON.parse(block.argumentsBuffer) as Record<string, unknown>;
+        } catch (error) {
+          logger.warn(
+            "[ANTHROPIC] Failed to parse streamed tool call arguments:",
+            error
+          );
+        }
+      }
+      toolCalls.push({ toolName: block.toolName, arguments: args });
+    }
+
     // Parse JSON response if schema was provided
     let structured: AgentStructuredResponse | undefined;
     if (input.parameters?.jsonSchema && accumulated) {