@falai/agent 2.6.0 → 2.7.0

package/src/providers/GeminiProvider.ts

@@ -21,14 +21,14 @@ import type {
 } from "../types";
 import type { ProviderCapabilities } from "../types/ai";
 import type { HistoryItem } from "../types/history";
-import { withTimeoutAndRetry, withStreamRetry, resolveRetryConfig, combineAbortSignals } from "../utils/retry";
+import { withTimeoutAndRetry, withStreamRetry, withBackupFallback, streamWithBackupFallback, backupFallbackLogging, resolveRetryConfig, combineAbortSignals } from "../utils/retry";
 import { assertUsableCompletion } from "../utils/completion";
 import { tryParseJSONResponse } from "../utils/json";
 import { logger } from "../utils/logger";
 import {
   classifyProviderError,
-  getErrorMessage,
   isBackupEligible,
+  isRetriableProviderError,
   toProviderError,
   type ErrorClassificationOptions,
 } from "./errorClassification";
@@ -38,8 +38,8 @@ import {
  * Uses types from @google/genai package
  */
 export interface GeminiProviderOptions {
-  /** Gemini API key */
-  apiKey: string;
+  /** Gemini API key. Optional when `client` is injected (tests). */
+  apiKey?: string;
   /** Model to use (required) - e.g., "gemini-3.1-pro-preview" */
   model: string;
   /** Backup models to try if primary fails (default: []) */
@@ -51,6 +51,12 @@ export interface GeminiProviderOptions {
     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?: GoogleGenAIType;
 }
 
 /**
@@ -88,9 +94,9 @@ export class GeminiProvider implements AiProvider {
   private retryConfig: { timeout: number; retries: number };
 
   constructor(options: GeminiProviderOptions) {
-    const { apiKey, model, backupModels = [], config, retryConfig } = options;
+    const { apiKey, model, backupModels = [], config, retryConfig, client } = options;
 
-    if (!apiKey) {
+    if (!client && !apiKey) {
       throw new Error("Gemini API key is required");
     }
 
@@ -98,7 +104,7 @@ export class GeminiProvider implements AiProvider {
       throw new Error("Model is required. Example: 'gemini-3.1-pro-preview'");
     }
 
-    this.genAI = new GoogleGenAI({ apiKey });
+    this.genAI = client ?? new GoogleGenAI({ apiKey });
     this.primaryModel = model;
     this.backupModels = backupModels;
     this.config = config;
@@ -352,58 +358,19 @@ export class GeminiProvider implements AiProvider {
   >(
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput<TStructured>> {
-    // Try primary model first
-    try {
-      return await this.generateWithModel(this.primaryModel, input);
-    } catch (primaryError: unknown) {
-      const primaryErrMsg = getErrorMessage(primaryError);
-      logger.warn(
-        `[GEMINI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
-      );
-
-      if (!shouldUseBackupModel(primaryError)) {
-        throw toProviderError(primaryError, this.name, CLASSIFICATION_OPTIONS);
-      }
-
-      logger.debug(`[GEMINI] Trying backup models`);
-
-      let lastBackupError: unknown = primaryError;
-
-      for (let i = 0; i < this.backupModels.length; i++) {
-        const backupModel = this.backupModels[i];
-        logger.debug(
-          `[GEMINI] Trying backup model ${i + 1}/${this.backupModels.length
-          }: ${backupModel}`
-        );
+    const observer = backupFallbackLogging("[GEMINI]", shouldUseBackupModel);
 
-        try {
-          const result = await this.generateWithModel(backupModel, input);
-          logger.debug(`[GEMINI] Backup model ${backupModel} succeeded`);
-          return result as GenerateMessageOutput<TStructured>;
-        } catch (backupError: unknown) {
-          const backupErrMsg = getErrorMessage(backupError);
-          logger.warn(
-            `[GEMINI] Backup model ${backupModel} failed: ${backupErrMsg}`
-          );
-          lastBackupError = backupError;
-
-          if (
-            !shouldUseBackupModel(backupError) &&
-            i < this.backupModels.length - 1
-          ) {
-            logger.debug(
-              `[GEMINI] Backup model error doesn't qualify for further attempts`
-            );
-            break;
-          }
-        }
-      }
-
-      const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      logger.error(
-        `[GEMINI] 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);
     }
   }
 
@@ -555,7 +522,8 @@ export class GeminiProvider implements AiProvider {
       operation,
       this.retryConfig.timeout,
       this.retryConfig.retries,
-      `Gemini ${model}`
+      `Gemini ${model}`,
+      (error) => isRetriableProviderError(error, CLASSIFICATION_OPTIONS)
     ) as Promise<GenerateMessageOutput<TStructured>>;
   }
 
@@ -565,64 +533,22 @@ export class GeminiProvider implements AiProvider {
   >(
     input: GenerateMessageInput<TContext>
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
-    // Try primary model first
-    try {
-      yield* withStreamRetry(
-        (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);
-      logger.warn(
-        `[GEMINI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
-      );
-
-      if (!shouldUseBackupModel(primaryError)) {
-        throw toProviderError(primaryError, this.name, CLASSIFICATION_OPTIONS);
-      }
-
-      logger.debug(`[GEMINI] 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(
-          `[GEMINI] Trying backup model ${i + 1}/${this.backupModels.length
-          }: ${backupModel}`
-        );
+    const observer = backupFallbackLogging("[GEMINI]", shouldUseBackupModel, { streaming: true });
 
-        try {
-          yield* withStreamRetry(
-            (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;
-        } catch (backupError: unknown) {
-          const backupErrMsg = getErrorMessage(backupError);
-          logger.warn(
-            `[GEMINI] Backup model ${backupModel} failed: ${backupErrMsg}`
-          );
-          lastBackupError = backupError;
-
-          if (
-            !shouldUseBackupModel(backupError) &&
-            i < this.backupModels.length - 1
-          ) {
-            logger.debug(
-              `[GEMINI] Backup model error doesn't qualify for further attempts`
-            );
-            break;
-          }
-        }
-      }
-
-      const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      logger.error(
-        `[GEMINI] 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: `Gemini ${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);
     }
   }
 

package/src/providers/OpenAICompatibleProvider.ts

@@ -27,11 +27,13 @@ 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 type { ResponseInput } from "openai/resources/responses/responses";
+import { withTimeoutAndRetry, withStreamRetry, withBackupFallback, streamWithBackupFallback, backupFallbackLogging, resolveRetryConfig, logger, assertUsableCompletion, combineAbortSignals } from "../utils";
 import {
   classifyProviderError,
   getErrorMessage,
   isBackupEligible,
+  isRetriableProviderError,
   toProviderError,
   type ErrorClassificationOptions,
 } from "./errorClassification";
@@ -142,6 +144,56 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
   // Provider-specific hooks
   // ---------------------------------------------------------------------
 
+  /**
+   * Map interaction history onto Responses-API input items so structured
+   * generations carry the same context as chat completions: plain messages
+   * pass through as easy-input messages, and tool exchanges map to
+   * function_call / function_call_output pairs keyed by the original ids.
+   * The prompt is appended as the final user turn, mirroring how the
+   * chat-completions path builds its messages array.
+   */
+  private buildResponsesInput(history: HistoryItem[], prompt: string): ResponseInput {
+    const items: ResponseInput = [];
+
+    for (const item of history) {
+      switch (item.role) {
+        case "system":
+          items.push({ role: "system", content: item.content });
+          break;
+        case "user":
+          items.push({ role: "user", content: item.content });
+          break;
+        case "assistant": {
+          if (item.content) {
+            items.push({ role: "assistant", content: item.content });
+          }
+          for (const toolCall of item.tool_calls ?? []) {
+            items.push({
+              type: "function_call",
+              call_id: toolCall.id,
+              name: toolCall.name,
+              arguments: JSON.stringify(toolCall.arguments),
+            });
+          }
+          break;
+        }
+        case "tool":
+          items.push({
+            type: "function_call_output",
+            call_id: item.tool_call_id,
+            output:
+              typeof item.content === "string"
+                ? item.content
+                : JSON.stringify(item.content),
+          });
+          break;
+      }
+    }
+
+    items.push({ role: "user", content: prompt });
+    return items;
+  }
+
   /**
    * Generate a structured (JSON schema) response. Default uses the
    * responses.parse API (OpenAI, OpenRouter). Subclasses whose API lacks
@@ -162,8 +214,10 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
     const response = await this.client.responses.parse(
       {
         model,
-        instructions: input.prompt,
-        input: "",
+        // Full conversation context: mapped history plus the prompt as the
+        // final user turn. This used to send only `instructions` with an empty
+        // `input`, leaving every structured turn without conversation memory.
+        input: this.buildResponsesInput(input.history, input.prompt),
         reasoning: {
           effort: input.parameters?.reasoning?.effort || "low",
         },
@@ -368,65 +422,22 @@ export abstract class OpenAICompatibleProvider 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(
-        `[${this.logLabel}] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
-      );
-
-      if (!this.shouldUseBackupModel(primaryError)) {
-        throw this.wrapTerminalError(primaryError);
-      }
-
-      logger.debug(`[${this.logLabel}] Trying backup models`);
-
-      let lastBackupError: unknown = primaryError;
-
-      for (let i = 0; i < this.backupModels.length; i++) {
-        const backupModel = this.backupModels[i];
-        logger.debug(
-          `[${this.logLabel}] Trying backup model ${i + 1}/${
-            this.backupModels.length
-          }: ${backupModel}`
-        );
-
-        try {
-          const result = await this.generateWithModel<TContext, TStructured>(
-            backupModel,
-            input
-          );
-          logger.debug(`[${this.logLabel}] Backup model ${backupModel} succeeded`);
-          return result;
-        } catch (backupError: unknown) {
-          const backupErrMsg = getErrorMessage(backupError);
-          logger.warn(
-            `[${this.logLabel}] Backup model ${backupModel} failed: ${backupErrMsg}`
-          );
-          lastBackupError = backupError;
-
-          if (
-            !this.shouldUseBackupModel(backupError) &&
-            i < this.backupModels.length - 1
-          ) {
-            logger.debug(
-              `[${this.logLabel}] Backup model error doesn't qualify for further attempts`
-            );
-            break;
-          }
-        }
-      }
+    const observer = backupFallbackLogging(
+      `[${this.logLabel}]`,
+      (error) => this.shouldUseBackupModel(error)
+    );
 
-      const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      logger.error(
-        `[${this.logLabel}] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
-      );
-      throw this.wrapTerminalError(lastBackupError);
+    try {
+      return await withBackupFallback({
+        models: [this.primaryModel, ...this.backupModels],
+        attempt: (model) =>
+          this.generateWithModel<TContext, TStructured>(model, input),
+        shouldTryBackup: (error) => this.shouldUseBackupModel(error),
+        ...observer.callbacks,
+      });
+    } catch (error: unknown) {
+      observer.logExhausted(error);
+      throw this.wrapTerminalError(error);
     }
   }
 
@@ -436,65 +447,26 @@ export abstract class OpenAICompatibleProvider 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: `${this.logLabel} ${this.primaryModel} stream` }
-      );
-    } catch (primaryError: unknown) {
-      const primaryErrMsg = getErrorMessage(primaryError);
-      logger.warn(
-        `[${this.logLabel}] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
-      );
-
-      if (!this.shouldUseBackupModel(primaryError)) {
-        throw this.wrapTerminalError(primaryError);
-      }
-
-      logger.debug(`[${this.logLabel}] 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(
-          `[${this.logLabel}] Trying backup model ${i + 1}/${
-            this.backupModels.length
-          }: ${backupModel}`
-        );
-
-        try {
-          yield* withStreamRetry(
-            (signal) => this.generateStreamWithModel<TContext, TStructured>(backupModel, input, signal),
-            { maxRetries: this.retryConfig.retries, firstChunkTimeoutMs: this.retryConfig.timeout, operationName: `${this.logLabel} ${backupModel} stream` }
-          );
-          logger.debug(`[${this.logLabel}] Backup model ${backupModel} succeeded`);
-          return;
-        } catch (backupError: unknown) {
-          const backupErrMsg = getErrorMessage(backupError);
-          logger.warn(
-            `[${this.logLabel}] Backup model ${backupModel} failed: ${backupErrMsg}`
-          );
-          lastBackupError = backupError;
-
-          if (
-            !this.shouldUseBackupModel(backupError) &&
-            i < this.backupModels.length - 1
-          ) {
-            logger.debug(
-              `[${this.logLabel}] Backup model error doesn't qualify for further attempts`
-            );
-            break;
-          }
-        }
-      }
+    const observer = backupFallbackLogging(
+      `[${this.logLabel}]`,
+      (error) => this.shouldUseBackupModel(error),
+      { streaming: true }
+    );
 
-      const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      logger.error(
-        `[${this.logLabel}] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
-      );
-      throw this.wrapTerminalError(lastBackupError);
+    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: `${this.logLabel} ${model} stream`, isRetriable: (error) => isRetriableProviderError(error, this.classificationOptions) }
+          ),
+        shouldTryBackup: (error) => this.shouldUseBackupModel(error),
+        ...observer.callbacks,
+      });
+    } catch (error: unknown) {
+      observer.logExhausted(error);
+      throw this.wrapTerminalError(error);
     }
   }
 
@@ -529,7 +501,8 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
       operation,
       this.retryConfig.timeout,
       this.retryConfig.retries,
-      `${this.displayName} ${model}`
+      `${this.displayName} ${model}`,
+      (error) => isRetriableProviderError(error, this.classificationOptions)
     ) as Promise<GenerateMessageOutput<TStructured>>;
   }
 
@@ -689,10 +662,15 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
     let promptTokens: number | undefined;
     let completionTokens: number | undefined;
     let totalTokens: number | undefined;
-    const toolCalls: Array<{
-      toolName: string;
-      arguments: Record<string, unknown>;
-    }> = [];
+    // Tool calls arrive across MANY deltas: the first carries the id/name,
+    // later ones carry argument-string fragments that must be concatenated.
+    // Accumulate per call (keyed by `index`) and parse once at stream end —
+    // parsing per fragment produced N broken entries for one real call.
+    const pendingToolCalls = new Map<
+      number,
+      { toolName: string; argumentsBuffer: string }
+    >();
+    let lastSlot = 0;
 
     for await (const chunk of stream) {
       currentModel = chunk.model;
@@ -707,18 +685,25 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
       const choice = chunk.choices?.[0];
       if (!choice) continue;
 
-      // Extract tool calls from delta
+      // Accumulate streamed tool-call fragments by index
       if (choice.delta?.tool_calls) {
         for (const toolCall of choice.delta.tool_calls) {
-          if (toolCall.function) {
-            toolCalls.push({
-              toolName: toolCall.function.name || "",
-              arguments: this.parseToolCallArguments(
-                toolCall.function.arguments,
-                true
-              ),
-            });
+          // Spec-compliant chunks carry `index`; servers that omit it send
+          // one call's fragments sequentially, so keep appending to lastSlot.
+          const slot =
+            typeof toolCall.index === "number" ? toolCall.index : lastSlot;
+          lastSlot = slot;
+          const entry = pendingToolCalls.get(slot) ?? {
+            toolName: "",
+            argumentsBuffer: "",
+          };
+          if (toolCall.function?.name) {
+            entry.toolName = toolCall.function.name;
+          }
+          if (toolCall.function?.arguments) {
+            entry.argumentsBuffer += toolCall.function.arguments;
           }
+          pendingToolCalls.set(slot, entry);
         }
       }
 
@@ -753,6 +738,20 @@ export abstract class OpenAICompatibleProvider implements AiProvider {
       }
     }
 
+    const toolCalls: Array<{
+      toolName: string;
+      arguments: Record<string, unknown>;
+    }> = [];
+    for (const [, entry] of [...pendingToolCalls.entries()].sort(
+      ([a], [b]) => a - b
+    )) {
+      if (!entry.toolName) continue;
+      toolCalls.push({
+        toolName: entry.toolName,
+        arguments: this.parseToolCallArguments(entry.argumentsBuffer, true),
+      });
+    }
+
     // Include tool calls in structured response (even without JSON schema)
     if (toolCalls.length > 0) {
       structured = {

package/src/providers/OpenAIProvider.ts

@@ -19,7 +19,7 @@ export interface OpenAIProviderOptions {
   apiKey: string;
   /** Organization ID (optional) */
   organization?: string;
-  /** Model to use (required) - e.g., "gpt-5.5", "gpt-5.4" */
+  /** Model to use (required) - e.g., "gpt-5.6", "gpt-5.4-mini" */
   model: string;
   /** Backup models to try if primary fails (default: []) */
   backupModels?: string[];
@@ -64,7 +64,7 @@ export class OpenAIProvider extends OpenAICompatibleProvider {
     }
 
     if (!model) {
-      throw new Error("Model is required. Example: 'gpt-5.5' or 'gpt-5.4'");
+      throw new Error("Model is required. Example: 'gpt-5.6' or 'gpt-5.5'");
     }
 
     super({

package/src/providers/errorClassification.ts

@@ -150,6 +150,40 @@ export function isBackupEligible(code: ProviderErrorCode): boolean {
   return code === "rate_limited" || code === "overloaded";
 }
 
+/** Errors whose name marks them as caller- or SDK-initiated aborts. */
+function isAbortLikeError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  // OpenAI SDK: APIUserAbortError. Generic fetch/DOM: AbortError / TimeoutError
+  // handled below via classification (a timeout IS retriable; a caller abort is not).
+  return (
+    error.name === "AbortError" ||
+    error.name === "APIUserAbortError" ||
+    /abort/i.test(error.message)
+  );
+}
+
+/**
+ * Whether an error is worth retrying with backoff: transient availability,
+ * rate-limiting, timeouts and network faults only. Deterministic failures —
+ * auth (401/403), invalid request (400/404/422) and caller aborts — must fail
+ * fast instead of burning the retry budget on the same outcome.
+ */
+export function isRetriableProviderError(
+  error: unknown,
+  options?: ErrorClassificationOptions
+): boolean {
+  if (isAbortLikeError(error)) {
+    return false;
+  }
+  const code = classifyProviderError(error, options);
+  return (
+    code === "rate_limited" ||
+    code === "overloaded" ||
+    code === "timeout" ||
+    code === "network"
+  );
+}
+
 /**
  * Wrap a terminal failure (after retries/backup exhaustion) in a
  * normalized ProviderError, preserving the original error as `cause`.

package/src/types/agent.ts

@@ -126,6 +126,13 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
    * Rendered into the system prompt as "who you are and how you communicate."
    */
   persona?: Template<TContext>;
+  /**
+   * Hard bound on session.history length (default: 400). The oldest entries
+   * are trimmed — never splitting an assistant/tool pair — when the bound is
+   * exceeded and no compaction strategy shrank the history first. Set 0 to
+   * disable bounding entirely.
+   */
+  maxHistoryMessages?: number;
   /** Enable debug logging */
   debug?: boolean;
   /** Default context data available to the agent */
@@ -187,6 +194,15 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
    * @default 10
    */
   maxDirectiveChain?: number;
+  /**
+   * Maximum number of tool loop iterations allowed within a single response
+   * generation before the pipeline stops executing further tool calls.
+   * Guards against runaway recursive tool calling. An explicit `0` is honored
+   * (no tool loops). Applies to both `respond()` and streaming paths.
+   *
+   * @default 5
+   */
+  maxToolLoops?: number;
   /**
    * Optional compaction configuration for managing conversation history size.
    * When provided, the agent will validate the options and make them available
@@ -321,6 +337,13 @@ export interface AppliedInstruction {
   scopeRef?: string;
 }
 
+/** A flow that left its active position during a turn. */
+export interface EndedFlow {
+  flowId: string;
+  title?: string;
+  reason: StoppedReason;
+}
+
 export interface AgentResponse<TData = Record<string, unknown>> {
   message: string;
   session?: SessionState<TData>;
@@ -341,6 +364,17 @@ export interface AgentResponse<TData = Record<string, unknown>> {
    * Mirrors the observability framing of `executedSteps` and `appliedInstructions`.
    */
   triggeredSignals?: SignalFiring<unknown, TData>[];
+  /**
+   * Provider-reported usage for this turn's primary generation (routing and
+   * extraction sub-calls are not included).
+   */
+  metadata?: { tokensUsed?: number };
+  /**
+   * Flows that LEFT their active position this turn — completions, redirects,
+   * resets. planTurn knows these internally; surfaced so consumers stop
+   * re-deriving them from executedSteps + session cursor inspection.
+   */
+  endedFlows?: EndedFlow[];
 }
 
 export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {