@falai/agent 3.2.5 → 3.4.0

package/src/providers/AnthropicProvider.ts

@@ -8,18 +8,21 @@
  * `@providerkit/core`; this file is the constructor.
  */
 
-import { createAnthropicProvider } from "@providerkit/core";
+import { createAnthropicProvider, type FallbackOptions, type Provider } from "@providerkit/core";
 
-import type { ProviderCapabilities } from "../types/ai.js";
+import type { AiProvider, ProviderCapabilities } from "../types/ai.js";
 import { ProviderAdapter, type RequestConfig } from "./ProviderAdapter.js";
 
 export interface AnthropicProviderOptions {
   /** Anthropic API key */
   apiKey: string;
-  /** Model to use (required) — e.g. "claude-sonnet-5", "claude-opus-5" */
+  /** Model to use (required) — e.g. "claude-sonnet-5" or "claude-opus-5" */
   model: string;
   /** Backup models to try if the primary fails (default: []) */
   backupModels?: string[];
+  /** Fallback providers to try if this provider fails/exhausts */
+  fallbacks?: Array<AiProvider | Provider>;
+  fallbackOptions?: FallbackOptions<Provider>;
   /** Any endpoint speaking the Anthropic Messages dialect. */
   baseUrl?: string;
   /** Request defaults sent with every call */
@@ -65,6 +68,8 @@ export class AnthropicProvider extends ProviderAdapter {
       model: options.model,
       ...(options.config ? { defaults: options.config } : {}),
       ...(options.backupModels ? { backupModels: options.backupModels } : {}),
+      ...(options.fallbacks ? { fallbacks: options.fallbacks } : {}),
+      ...(options.fallbackOptions ? { fallbackOptions: options.fallbackOptions } : {}),
       ...(options.retryConfig ? { retryConfig: options.retryConfig } : {}),
     });
   }

package/src/providers/FallbackAiProvider.ts

@@ -0,0 +1,94 @@
+/**
+ * Fallback AI Provider: runs an ordered list of AiProviders.
+ *
+ * Each child AiProvider is tried in turn using `@providerkit/core`'s FallbackPool,
+ * preserving per-provider cooldowns (e.g. 5h or weekly rate limit / quota resets)
+ * across calls.
+ */
+
+import {
+  FallbackPool,
+  type FallbackOptions,
+  type ErrorKind,
+} from "@providerkit/core";
+
+import type {
+  AgentStructuredResponse,
+  AiProvider,
+  GenerateMessageInput,
+  GenerateMessageOutput,
+  GenerateMessageStreamChunk,
+  ProviderCapabilities,
+} from "../types/ai.js";
+import { logger } from "../utils/logger.js";
+
+export interface FallbackAiProviderOptions {
+  /** The ordered list of providers to try. The first is primary. */
+  providers: AiProvider[];
+  /** Optional cooldown configuration overrides. */
+  cooldownMs?: Partial<Record<ErrorKind, number | null>>;
+  /** Optional callback when a provider enters cooldown. */
+  onCooldown?: FallbackOptions<AiProvider>["onCooldown"];
+}
+
+export class FallbackAiProvider implements AiProvider {
+  public readonly name: string;
+  public readonly capabilities: ProviderCapabilities;
+  public readonly pool: FallbackPool<AiProvider>;
+
+  constructor(options: FallbackAiProviderOptions) {
+    if (!options.providers || options.providers.length === 0) {
+      throw new Error("FallbackAiProvider requires at least one provider");
+    }
+
+    this.name = `fallback(${options.providers.map((p) => p.name).join("->")})`;
+
+    // Capabilities represent the intersection of supported critical features
+    // while inheriting primary's defaults.
+    this.capabilities = {
+      supportsTools: options.providers.every((p) => p.capabilities.supportsTools),
+      supportsNativeJsonSchema: options.providers.every(
+        (p) => p.capabilities.supportsNativeJsonSchema,
+      ),
+      supportsStreaming: options.providers.every((p) => p.capabilities.supportsStreaming),
+      supportsStreamingToolCalls: options.providers.every(
+        (p) => p.capabilities.supportsStreamingToolCalls,
+      ),
+      supportsPromptCaching: options.providers.every((p) => p.capabilities.supportsPromptCaching),
+    };
+
+    this.pool = new FallbackPool<AiProvider>(options.providers, {
+      ...(options.cooldownMs ? { cooldownMs: options.cooldownMs } : {}),
+      onCooldown: (info) => {
+        logger.warn(
+          `[${this.name}] Provider "${info.candidate.name}" cooled down until ${new Date(
+            info.retryAtMs,
+          ).toISOString()} (${info.kind}${info.window ? ` / ${info.window}` : ""})`,
+        );
+        options.onCooldown?.(info);
+      },
+    });
+  }
+
+  async generateMessage<TContext = unknown, TStructured = AgentStructuredResponse>(
+    input: GenerateMessageInput<TContext>,
+  ): Promise<GenerateMessageOutput<TStructured>> {
+    return this.pool.with(async (provider, signal) => {
+      return provider.generateMessage<TContext, TStructured>({
+        ...input,
+        signal,
+      });
+    }, input.signal);
+  }
+
+  async *generateMessageStream<TContext = unknown, TStructured = AgentStructuredResponse>(
+    input: GenerateMessageInput<TContext>,
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    yield* this.pool.stream(async function* (provider, signal) {
+      yield* provider.generateMessageStream<TContext, TStructured>({
+        ...input,
+        signal,
+      });
+    }, input.signal);
+  }
+}

package/src/providers/GeminiProvider.ts

@@ -10,9 +10,9 @@
  * holds — a sibling codebase runs the combination in production today.
  */
 
-import { createGeminiProvider } from "@providerkit/core";
+import { createGeminiProvider, type FallbackOptions, type Provider } from "@providerkit/core";
 
-import type { ProviderCapabilities } from "../types/ai.js";
+import type { AiProvider, ProviderCapabilities } from "../types/ai.js";
 import type { JsonWithTools } from "./OpenAICompatibleProvider.js";
 import { ProviderAdapter, type RequestConfig } from "./ProviderAdapter.js";
 
@@ -23,6 +23,9 @@ export interface GeminiProviderOptions {
   model: string;
   /** Backup models to try if the primary fails (default: []) */
   backupModels?: string[];
+  /** Fallback providers to try if this provider fails/exhausts */
+  fallbacks?: Array<AiProvider | Provider>;
+  fallbackOptions?: FallbackOptions<Provider>;
   /** Any endpoint speaking the Gemini generateContent dialect. */
   baseUrl?: string;
   /**
@@ -71,6 +74,8 @@ export class GeminiProvider extends ProviderAdapter {
       model: options.model,
       ...(options.config ? { defaults: options.config } : {}),
       ...(options.backupModels ? { backupModels: options.backupModels } : {}),
+      ...(options.fallbacks ? { fallbacks: options.fallbacks } : {}),
+      ...(options.fallbackOptions ? { fallbackOptions: options.fallbackOptions } : {}),
       ...(options.retryConfig ? { retryConfig: options.retryConfig } : {}),
     });
   }

package/src/providers/OpenAICompatibleProvider.ts

@@ -72,6 +72,8 @@ export abstract class OpenAICompatibleProvider extends ProviderAdapter {
       model: init.model,
       ...(init.config ? { defaults: init.config } : {}),
       ...(init.backupModels ? { backupModels: init.backupModels } : {}),
+      ...(init.fallbacks ? { fallbacks: init.fallbacks } : {}),
+      ...(init.fallbackOptions ? { fallbackOptions: init.fallbackOptions } : {}),
       ...(init.retryConfig ? { retryConfig: init.retryConfig } : {}),
     });
     this.config = init.config;

package/src/providers/ProviderAdapter.ts

@@ -27,9 +27,11 @@ import {
   streamWatch,
   streamWithBackupModels,
   watchChunks,
+  withFallbackProviders,
   withStreamRetry,
   type ChatMessage,
   type Effort,
+  type FallbackOptions,
   type JsonObjectSchema,
   type JsonWithToolsProbe,
   type ProbeOptions,
@@ -119,6 +121,12 @@ export interface ProviderAdapterInit {
   defaults?: RequestConfig;
   /** Tried in order after the primary. */
   backupModels?: string[];
+  /**
+   * Fallback providers to try if this provider fails/exhausts.
+   * Accepts both @falai/agent AiProviders (like ZaiProvider) and @providerkit/core Providers.
+   */
+  fallbacks?: Array<AiProvider | Provider>;
+  fallbackOptions?: FallbackOptions<Provider>;
   retryConfig?: { timeout?: number; retries?: number };
 }
 
@@ -212,6 +220,9 @@ interface Accumulator {
 }
 
 function fold(acc: Accumulator, chunk: ProviderChunk): string {
+  if (chunk.source) {
+    acc.model = chunk.source.model;
+  }
   if (chunk.usage) {
     acc.promptTokens = chunk.usage.inputTokens;
     acc.completionTokens = chunk.usage.outputTokens;
@@ -256,12 +267,31 @@ export abstract class ProviderAdapter implements AiProvider {
   protected readonly retryConfig: RetryConfig;
   private readonly defaults: ProviderAdapterInit["defaults"];
 
+  public get coreProvider(): Provider {
+    return this.provider;
+  }
+
   protected constructor(init: ProviderAdapterInit) {
     this.defaults = init.defaults;
-    this.provider = init.provider;
     this.primaryModel = init.model;
     this.backupModels = init.backupModels ?? [];
     this.retryConfig = resolveRetryConfig(init.retryConfig);
+
+    if (init.fallbacks && init.fallbacks.length > 0) {
+      const coreProviders: Provider[] = [
+        init.provider,
+        ...init.fallbacks.map((f) => {
+          if (f instanceof ProviderAdapter) return f.coreProvider;
+          if ("coreProvider" in f && (f as { coreProvider: Provider }).coreProvider) {
+            return (f as { coreProvider: Provider }).coreProvider;
+          }
+          return f as Provider;
+        }),
+      ];
+      this.provider = withFallbackProviders(coreProviders, init.fallbackOptions);
+    } else {
+      this.provider = init.provider;
+    }
   }
 
   /**

package/src/providers/ZaiProvider.ts

@@ -0,0 +1,72 @@
+/**
+ * Z.ai Coding Plan.
+ *
+ * The flat-rate plan hosts GLM on an Anthropic-compatible endpoint with
+ * Bearer auth and its own thinking dialect — all of that lives in
+ * `@providerkit/core` (adapter + preset); this file is the constructor, the
+ * family default for cheap high-volume work.
+ *
+ * Dialect notes (measured 2026-09-13, see the core preset for detail):
+ * model ids are BARE (`glm-5.3-flash`, not `z-ai/glm-5.3-flash`), and
+ * "no thinking" must be an explicit marker — silence means the model default,
+ * which is thinking ON.
+ */
+
+import { createZaiCodingProvider, type FallbackOptions, type Provider } from "@providerkit/core";
+
+import type { AiProvider, ProviderCapabilities } from "../types/ai.js";
+import { ProviderAdapter, type RequestConfig } from "./ProviderAdapter.js";
+
+export interface ZaiProviderOptions {
+  /** Z.ai Coding Plan key */
+  apiKey: string;
+  /** Model to use. Defaults to the fleet workhorse `glm-5.3-flash`. */
+  model?: string;
+  /** Backup models to try on this provider if the primary fails (default: []) */
+  backupModels?: string[];
+  /** Fallback providers to try if this provider fails/exhausts */
+  fallbacks?: Array<AiProvider | Provider>;
+  fallbackOptions?: FallbackOptions<Provider>;
+  /** Any endpoint speaking the Anthropic Messages dialect with the plan's
+   *  auth. Defaults to the coding endpoint. */
+  baseUrl?: string;
+  /** Request defaults sent with every call */
+  config?: RequestConfig;
+  /** Idle-stream deadline and retry budget */
+  retryConfig?: { timeout?: number; retries?: number };
+  /** Replacement `fetch`, for tests that script the wire. */
+  fetchImpl?: typeof fetch;
+}
+
+export class ZaiProvider extends ProviderAdapter {
+  public readonly name = "zai";
+  public readonly capabilities: ProviderCapabilities = {
+    supportsTools: true,
+    supportsNativeJsonSchema: false,
+    supportsStreaming: true,
+    supportsStreamingToolCalls: true,
+    supportsPromptCaching: true,
+  };
+
+  constructor(options: ZaiProviderOptions) {
+    if (!options.apiKey) throw new Error("Z.ai Coding Plan API key is required");
+
+    const model = options.model ?? "glm-5.3-flash";
+    super({
+      provider: createZaiCodingProvider({
+        apiKey: options.apiKey,
+        model,
+        ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+        ...(options.config?.maxTokens ? { maxTokens: options.config.maxTokens } : {}),
+        ...(options.config?.effort ? { effort: options.config.effort } : {}),
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+      }),
+      model,
+      ...(options.config ? { defaults: options.config } : {}),
+      ...(options.backupModels ? { backupModels: options.backupModels } : {}),
+      ...(options.fallbacks ? { fallbacks: options.fallbacks } : {}),
+      ...(options.fallbackOptions ? { fallbackOptions: options.fallbackOptions } : {}),
+      ...(options.retryConfig ? { retryConfig: options.retryConfig } : {}),
+    });
+  }
+}

package/src/providers/index.ts

@@ -33,3 +33,6 @@ export type { OpenAICompatibleOptions } from "./GenericOpenAICompatibleProvider.
 
 export { ProviderAdapter, resolveRetryConfig } from "./ProviderAdapter.js";
 export type { ProviderAdapterInit, RequestConfig, RetryConfig } from "./ProviderAdapter.js";
+
+export { ZaiProvider } from "./ZaiProvider.js";
+export type { ZaiProviderOptions } from "./ZaiProvider.js";