feat: default-on auto-fallback in generateText

Author: jddunn

src/api/generateText.ts

@@ -1073,16 +1073,18 @@ export async function generateText(opts: GenerateTextOptions): Promise<GenerateT
     });
   } catch (error) {
     // ── Fallback chain ────────────────────────────────────────────────
-    // When the primary provider fails with a retryable error and
-    // fallbackProviders are configured, try each fallback in order.
-    // The first successful response wins; if all fail, the last error
-    // is re-thrown.
+    // Resolve fallback chain: caller-supplied wins, undefined triggers
+    // auto-build from env keys, empty array explicitly opts out.
+    const effectiveFallbacks = opts.fallbackProviders === undefined
+      ? buildFallbackChain(metricProviderId)
+      : opts.fallbackProviders;
+
     if (
-      opts.fallbackProviders?.length &&
+      effectiveFallbacks.length &&
       isRetryableError(error)
     ) {
       let lastError = error;
-      for (const fb of opts.fallbackProviders) {
+      for (const fb of effectiveFallbacks) {
         try {
           opts.onFallback?.(
             lastError instanceof Error ? lastError : new Error(String(lastError)),

src/api/runtime/__tests__/generateText.test.ts

@@ -369,4 +369,42 @@ describe('generateText', () => {
     ]);
     expect(result.text).toBe('I could not execute that tool call.');
   });
+
+  it('auto-builds fallback chain when fallbackProviders is undefined and primary throws 429', async () => {
+    hoisted.generateCompletion
+      .mockRejectedValueOnce(new Error('429 rate limit exceeded'))
+      .mockResolvedValueOnce({
+        modelId: 'gpt-4o-mini',
+        usage: { promptTokens: 5, completionTokens: 3, totalTokens: 8 },
+        choices: [{ message: { role: 'assistant', content: 'fallback reply' }, finishReason: 'stop' }],
+      });
+
+    process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+    try {
+      const result = await generateText({
+        model: 'openai:gpt-4o',
+        prompt: 'hello',
+      });
+      expect(result.text).toBe('fallback reply');
+    } finally {
+      delete process.env.ANTHROPIC_API_KEY;
+    }
+  });
+
+  it('does NOT fallback when fallbackProviders is explicitly []', async () => {
+    hoisted.generateCompletion.mockRejectedValueOnce(new Error('429 rate limit exceeded'));
+
+    process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+    try {
+      await expect(
+        generateText({
+          model: 'openai:gpt-4o',
+          prompt: 'hello',
+          fallbackProviders: [],
+        })
+      ).rejects.toThrow('429');
+    } finally {
+      delete process.env.ANTHROPIC_API_KEY;
+    }
+  });
 });