ai-retry 1.4.0 → 1.6.0

package/README.md

@@ -14,6 +14,7 @@ Automatically handle API failures, content filtering, timeouts and other errors
 `ai-retry` wraps the provided base model with a set of retry conditions (retryables). When a request fails with an error or the response is not satisfying, it iterates through the given retryables to find a suitable fallback model. It automatically tracks which models have been tried and how many attempts have been made to prevent infinite loops.
 
 It supports two types of retries:
+
 - Error-based retries: when the model throws an error (e.g. timeouts, API errors, etc.)
 - Result-based retries: when the model returns a successful response that needs retrying (e.g. content filtering, etc.)
 
@@ -24,7 +25,7 @@ This library supports both AI SDK v5 and v6. The main branch reflects the latest
 > [!WARNING]
 > Version compatibility:
 >
-> - Use `ai-retry` version 0.x for AI SDK v5. 
+> - Use `ai-retry` version 0.x for AI SDK v5.
 > - Use `ai-retry` version 1.x for AI SDK v6.
 
 ```bash
@@ -133,17 +134,13 @@ import { createRetryable } from 'ai-retry';
 
 const retryableModel = createRetryable({
   model: 'openai/gpt-5',
-  retries: [
-    'anthropic/claude-sonnet-4'
-  ]
+  retries: ['anthropic/claude-sonnet-4'],
 });
 
 // Is the same as:
 const retryableModel = createRetryable({
   model: gateway('openai/gpt-5'),
-  retries: [
-    gateway('anthropic/claude-sonnet-4')
-  ]
+  retries: [gateway('anthropic/claude-sonnet-4')],
 });
 ```
 
@@ -179,16 +176,16 @@ const retryableModel = createRetryable({
     // Dynamic retryables act like if-branches:
     // If error.code == 429 (too many requests) happens, retry with this model
     (context) => {
-      return context.current.error.statusCode === 429 
-        ? { model: azure('gpt-4-mini') }   // Retry 
-        : undefined;                       // Skip
+      return context.current.error.statusCode === 429
+        ? { model: azure('gpt-4-mini') } // Retry
+        : undefined; // Skip
     },
 
     // If error.message ~= "service overloaded", retry with this model
     (context) => {
-      return context.current.error.message.includes("service overloaded") 
-        ? { model: azure('gpt-4-mini') }   // Retry 
-        : undefined;                       // Skip
+      return context.current.error.message.includes('service overloaded')
+        ? { model: azure('gpt-4-mini') } // Retry
+        : undefined; // Skip
     },
 
     // Static retryables act like else branches:
@@ -245,7 +242,7 @@ const retryableModel = createRetryable({
   retries: [
     // Error-based: catches thrown errors like timeouts, rate limits, etc.
     errorBasedRetry,
-    
+
     // Result-based: catches successful responses that need retrying
     resultBasedRetry,
   ],
@@ -258,7 +255,7 @@ Result-based retryables are only available for generate calls like `generateText
 
 If you don't need precise error matching with custom logic and just want to fallback to different models on any error, you can simply provide a list of models.
 
-> [!NOTE] 
+> [!NOTE]
 > Use the object syntax `{ model: openai('gpt-4') }` if you need to provide additional options like `maxAttempts`, `delay`, etc.
 
 ```typescript
@@ -291,6 +288,9 @@ If you need more control over when to retry and which model to use, you can crea
 > [!NOTE]
 > You can return additional options like `maxAttempts`, `delay`, etc. along with the model.
 
+> [!TIP]
+> If you'd like the same flexibility with a typed, composable condition system, see [Experimental: Composable Conditions](#experimental-composable-conditions).
+
 ```typescript
 import { anthropic } from '@ai-sdk/anthropic';
 import { openai } from '@ai-sdk/openai';
@@ -318,10 +318,10 @@ const rateLimitRetry: Retryable = (context) => {
 
 const retryableModel = createRetryable({
   // Base model
-  model: openai('gpt-4-mini'), 
+  model: openai('gpt-4-mini'),
   retries: [
     // Use custom rate limit retryable
-    rateLimitRetry
+    rateLimitRetry,
 
     // Other retryables...
   ],
@@ -340,12 +340,12 @@ import { RetryError } from 'ai';
 
 const retryableModel = createRetryable({
   // Base model = first attempt
-  model: azure('gpt-4-mini'), 
+  model: azure('gpt-4-mini'),
   retries: [
     // Fallback model 1 = Second attempt
-    openai('gpt-3.5-turbo'), 
+    openai('gpt-3.5-turbo'),
     // Fallback model 2 = Third attempt
-    anthropic('claude-3-haiku-20240307') 
+    anthropic('claude-3-haiku-20240307'),
   ],
 });
 
@@ -373,6 +373,9 @@ There are several built-in dynamic retryables available for common use cases:
 > [!TIP]
 > You are missing a retryable for your use case? [Open an issue](https://github.com/zirkelc/ai-retry/issues/new) and let's discuss it!
 
+> [!NOTE]
+> Looking for a composable alternative? See [Experimental: Composable Conditions](#experimental-composable-conditions) for a `condition().action()` API that builds on small primitives.
+
 - [`contentFilterTriggered`](./src/retryables/content-filter-triggered.ts): Content filter was triggered based on the prompt or completion.
 - [`requestTimeout`](./src/retryables/request-timeout.ts): Request timeout occurred.
 - [`requestNotRetryable`](./src/retryables/request-not-retryable.ts): Request failed with a non-retryable error.
@@ -404,8 +407,8 @@ const retryableModel = createRetryable({
 
 Handle timeouts by switching to potentially faster models.
 
-> [!NOTE] 
-> You need to use an `abortSignal` with a timeout on your request. 
+> [!NOTE]
+> You need to use an `abortSignal` with a timeout on your request.
 
 When a request times out, the `requestTimeout` retryable will automatically create a fresh abort signal for the retry attempt. This prevents the retry from immediately failing due to the already-aborted signal from the original request. If you do not provide a `timeout` value, a default of 60 seconds is used for the retry attempt.
 
@@ -416,8 +419,8 @@ const retryableModel = createRetryable({
   model: azure('gpt-4'),
   retries: [
     // Defaults to 60 seconds timeout for the retry attempt
-    requestTimeout(azure('gpt-4-mini')), 
-    
+    requestTimeout(azure('gpt-4-mini')),
+
     // Or specify a custom timeout for the retry attempt
     requestTimeout(azure('gpt-4-mini'), { timeout: 30_000 }),
   ],
@@ -500,10 +503,9 @@ const result = await generateImage({
 
 Handle cases where the base model fails with a non-retryable error.
 
-> [!NOTE] 
+> [!NOTE]
 > You can check if an error is retryable with the `isRetryable` property on an [`APICallError`](https://ai-sdk.dev/docs/reference/ai-sdk-errors/ai-api-call-error#ai_apicallerror).
 
-
 ```typescript
 import { requestNotRetryable } from 'ai-retry/retryables';
 
@@ -517,7 +519,7 @@ const retryable = createRetryable({
 
 #### Retry After Delay
 
-If an error is retryable, such as 429 (Too Many Requests) or 503 (Service Unavailable) errors, it will be retried after a delay. 
+If an error is retryable, such as 429 (Too Many Requests) or 503 (Service Unavailable) errors, it will be retried after a delay.
 The delay and exponential backoff can be configured. If the response contains a [`retry-after`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) header, it will be prioritized over the configured delay.
 
 Note that this retryable does not accept a model parameter, it will always retry the model from the latest failed attempt.
@@ -546,7 +548,7 @@ By default, if a [`retry-after-ms`](https://learn.microsoft.com/en-us/azure/ai-f
 
 Automatically retry with a different model when the response JSON doesn't match the expected schema.
 
-This is a result-based retryable that validates the model's JSON output against the schema set by structured output modes like `Output.object()`, `Output.array()`, and `Output.choice()`. 
+This is a result-based retryable that validates the model's JSON output against the schema set by structured output modes like `Output.object()`, `Output.array()`, and `Output.choice()`.
 Normally, schema validation happens outside the model in `generateText`, so a schema validation error would not be seen by the retryable model. This retryable catches it early and retries with a fallback model.
 
 > [!NOTE]
@@ -582,6 +584,130 @@ const result = await generateText({
 console.log(result.object); // { name: "Alice", age: 30 }
 ```
 
+### Experimental: Composable Conditions
+
+> [!WARNING]
+> This API is experimental and may change. It is not exported from the package root; opt in via the deep import:
+>
+> ```ts
+> import { ... } from 'ai-retry/retryables/experimental';
+> ```
+
+A `condition().action()` API for retryables. Conditions are built from small primitives (`error(fn)`, `result(fn)`), composed with `and` / `or` / `not`, and turned into a `Retryable` by one of two terminal actions: `.switch({ model })` or `.retry({ delay })`. The result drops into the same `retries: [...]` array as the stable helpers, so you can mix the two styles freely.
+
+```typescript
+import { anthropic } from '@ai-sdk/anthropic';
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+import { createRetryable } from 'ai-retry';
+import {
+  error,
+  finishReason,
+  httpStatus,
+} from 'ai-retry/retryables/experimental';
+
+const retryableModel = createRetryable({
+  model: openai('gpt-4'),
+  retries: [
+    // Switch on 529 or any "overloaded" message
+    httpStatus(529, 'overloaded').switch({
+      model: anthropic('claude-3-haiku-20240307'),
+    }),
+
+    // Switch when the response was content-filtered
+    finishReason('content-filter').switch({ model: openai('gpt-4o') }),
+
+    // Retry the same model with exponential backoff on retryable errors
+    error.isRetryable(true).retry({ delay: 1_000, backoffFactor: 2 }),
+  ],
+});
+```
+
+#### High-level helpers
+
+These cover the common cases. Each returns a `Condition` that you finalize with `.switch(...)` or `.retry(...)`.
+
+| Helper                         | Matches when                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `httpStatus(...patterns)`      | Numbers match the status code; strings match the message (substring); regex matches either        |
+| `timeout()`                    | `Error.name === 'TimeoutError'` (`AbortSignal.timeout()` fired)                                    |
+| `aborted()`                    | `Error.name === 'AbortError'` (manual `controller.abort()`)                                        |
+| `noImage()`                    | The image model threw `NoImageGeneratedError`                                                      |
+| `finishReason(...reasons)`     | The result's `finishReason.unified` matches one of the given values                                |
+| `schemaInvalid()`              | The result text fails JSON-schema validation against the call's `responseFormat`                   |
+
+#### Actions
+
+Every `Condition` exposes two terminal actions that turn it into a `Retryable`:
+
+- **`.switch({ model, ...options })`** falls back to a different model when the condition matches. Optional fields (`maxAttempts`, `delay`, `backoffFactor`, `timeout`, `options`) are the same as on a normal `Retry` object.
+- **`.retry({ delay?, backoffFactor?, ... })`** retries the current model when the condition matches. Honors `Retry-After` and `Retry-After-Ms` response headers when present, capped at 60 seconds.
+
+#### Combinators
+
+Compose conditions with the free functions or the methods on `Condition`:
+
+```typescript
+import {
+  and,
+  error,
+  httpStatus,
+  not,
+  or,
+} from 'ai-retry/retryables/experimental';
+
+or(httpStatus(429), error.message('overloaded'));
+and(httpStatus(503), error.message('temporary'));
+not(error.isRetryable(true));
+
+// Method form
+httpStatus(429).or(error.message('overloaded'));
+```
+
+#### Primitives
+
+The two lowest-level builders. Reach for them when no helper covers your case:
+
+| Primitive          | Matches when                                                                  |
+| ------------------ | ----------------------------------------------------------------------------- |
+| `error(predicate)` | The current attempt failed and `predicate(err, ctx)` returns true             |
+| `result(predicate)`| The current attempt succeeded and `predicate(res, ctx)` returns true (language models only) |
+
+```typescript
+import { APICallError } from 'ai';
+import { error } from 'ai-retry/retryables/experimental';
+
+error<MODEL, APICallError>(
+  (e) => APICallError.isInstance(e) && e.statusCode === 418,
+).switch({ model: fallback });
+```
+
+A few common error fields have ready-made matchers on the `error` namespace:
+
+| Helper                          | Matches when                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------- |
+| `error.isRetryable(flag)`       | `APICallError.isRetryable === flag` (default `true`)                                  |
+| `error.statusCode(...patterns)` | Numbers match exactly; regex matches the stringified code (e.g. `/^5\d\d$/` for 5xx)  |
+| `error.message(...patterns)`    | Substring (case-insensitive) or regex match against the error message                 |
+
+#### Mapping from Built-in retryables
+
+Each stable retryable has an equivalent in the new shape:
+
+| Built-in                                        | Composable form                                                                                       |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `contentFilterTriggered(m)`                     | `or(error(/* check e.data.error.code === 'content_filter' */), finishReason('content-filter')).switch({ model: m })` |
+| `requestTimeout(m)`                             | `timeout().switch({ model: m, timeout: 60_000 })`                                                     |
+| `requestNotRetryable(m)`                        | `error.isRetryable(false).switch({ model: m })`                                                       |
+| `schemaMismatch(m)`                             | `schemaInvalid().switch({ model: m })`                                                                |
+| `serviceOverloaded(m)`                          | `httpStatus(529, 'overloaded').switch({ model: m })`                                                  |
+| `serviceUnavailable(m)`                         | `error.statusCode(503).switch({ model: m })`                                                          |
+| `noImageGenerated(m)`                           | `noImage().switch({ model: m })`                                                                      |
+| `retryAfterDelay({ delay, backoffFactor })`     | `error.isRetryable(true).retry({ delay, backoffFactor })`                                             |
+
+> [!NOTE]
+> `error.isRetryable(true)` matches whatever the AI SDK's `APICallError` marks retryable. By default that's status codes 408, 409, 429, and any 5xx, plus network errors and provider-specific overrides (e.g. Anthropic flips it on `error.type === 'overloaded_error'`). It picks up more cases than a manual status-code list.
+
 ### Options
 
 #### Disabling Retries
@@ -591,21 +717,27 @@ You can disable retries entirely, which is useful for testing or specific enviro
 ```typescript
 const retryableModel = createRetryable({
   model: openai('gpt-4'), // Base model
-  retries: [/* ... */],
+  retries: [
+    /* ... */
+  ],
   disabled: true, // Retries are completely disabled
 });
 
 // Or disable based on environment
 const retryableModel = createRetryable({
   model: openai('gpt-4'), // Base model
-  retries: [/* ... */],
+  retries: [
+    /* ... */
+  ],
   disabled: process.env.NODE_ENV === 'test', // Disable in test environment
 });
 
 // Or use a function for dynamic control
 const retryableModel = createRetryable({
   model: openai('gpt-4'), // Base model
-  retries: [/* ... */],
+  retries: [
+    /* ... */
+  ],
   disabled: () => !featureFlags.isEnabled('ai-retries'), // Check feature flag
 });
 ```
@@ -630,7 +762,7 @@ const result = await generateText({
   model: retryableModel,
   prompt: 'Write a vegetarian lasagna recipe for 4 people.',
   // Will be respected during delays
-  abortSignal: AbortSignal.timeout(60_000), 
+  abortSignal: AbortSignal.timeout(60_000),
 });
 ```
 
@@ -647,6 +779,7 @@ const retryableModel = createRetryable({
   ],
 });
 ```
+
 #### Timeouts
 
 When a retry specifies a `timeout` value, a fresh `AbortSignal.timeout()` is created for that retry attempt, replacing any existing abort signal. This is essential when retrying after timeout errors, as the original abort signal would already be in an aborted state.
@@ -656,9 +789,9 @@ const retryableModel = createRetryable({
   model: openai('gpt-4'),
   retries: [
     // Provide a fresh 30 second timeout for the retry
-    { 
-      model: openai('gpt-3.5-turbo'), 
-      timeout: 30_000 
+    {
+      model: openai('gpt-3.5-turbo'),
+      timeout: 30_000,
     },
   ],
 });
@@ -668,7 +801,7 @@ const result = await generateText({
   model: retryableModel,
   prompt: 'Write a story',
   // Original request timeout
-  abortSignal: AbortSignal.timeout(60_000), 
+  abortSignal: AbortSignal.timeout(60_000),
 });
 ```
 
@@ -681,11 +814,11 @@ const retryableModel = createRetryable({
   model: openai('gpt-4'),
   retries: [
     // Try this once
-    anthropic('claude-3-haiku-20240307'), 
+    anthropic('claude-3-haiku-20240307'),
     // Try this one more time (initial + 1 retry)
-    { model: openai('gpt-4'), maxAttempts: 2 }, 
+    { model: openai('gpt-4'), maxAttempts: 2 },
     // Already tried, won't be retried again
-    anthropic('claude-3-haiku-20240307') 
+    anthropic('claude-3-haiku-20240307'),
   ],
 });
 ```
@@ -757,42 +890,96 @@ The following options can be overridden:
 
 ##### Language Model Options
 
-| Option | Description |
-|--------|-------------|
-| [`prompt`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#prompt) | Override the entire prompt for the retry |
-| [`temperature`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#temperature) | Temperature setting for controlling randomness |
-| [`topP`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#topp) | Nucleus sampling parameter |
-| [`topK`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#topk) | Top-K sampling parameter |
-| [`maxOutputTokens`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#max-output-tokens) | Maximum number of tokens to generate |
-| [`seed`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#seed) | Random seed for deterministic generation |
-| [`stopSequences`](https://ai-sdk.dev/docs/reference/ai-sdk-types/generate-text#stopsequences) | Stop sequences to end generation |
-| [`presencePenalty`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#presencepenalty) | Presence penalty for reducing repetition |
-| [`frequencyPenalty`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#frequencypenalty) | Frequency penalty for reducing repetition |
-| [`headers`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#headers) | Additional HTTP headers |
-| [`providerOptions`](https://ai-sdk.dev/docs/reference/ai-sdk-types/generate-text#provideroptions) | Provider-specific options |
+| Option                                                                                             | Description                                    |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [`prompt`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#prompt)                     | Override the entire prompt for the retry       |
+| [`temperature`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#temperature)           | Temperature setting for controlling randomness |
+| [`topP`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#topp)                         | Nucleus sampling parameter                     |
+| [`topK`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#topk)                         | Top-K sampling parameter                       |
+| [`maxOutputTokens`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#max-output-tokens) | Maximum number of tokens to generate           |
+| [`seed`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#seed)                         | Random seed for deterministic generation       |
+| [`stopSequences`](https://ai-sdk.dev/docs/reference/ai-sdk-types/generate-text#stopsequences)      | Stop sequences to end generation               |
+| [`presencePenalty`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#presencepenalty)   | Presence penalty for reducing repetition       |
+| [`frequencyPenalty`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#frequencypenalty) | Frequency penalty for reducing repetition      |
+| [`headers`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#headers)                   | Additional HTTP headers                        |
+| [`providerOptions`](https://ai-sdk.dev/docs/reference/ai-sdk-types/generate-text#provideroptions)  | Provider-specific options                      |
 
 ##### Embedding Model Options
 
-| Option | Description |
-|--------|-------------|
-| [`values`](https://ai-sdk.dev/docs/reference/ai-sdk-core/embed#values) | Override the values to embed |
-| [`headers`](https://ai-sdk.dev/docs/reference/ai-sdk-core/embed#headers) | Additional HTTP headers |
-| [`providerOptions`](https://ai-sdk.dev/docs/reference/ai-sdk-core/embed#provideroptions) | Provider-specific options |
+| Option                                                                                   | Description                  |
+| ---------------------------------------------------------------------------------------- | ---------------------------- |
+| [`values`](https://ai-sdk.dev/docs/reference/ai-sdk-core/embed#values)                   | Override the values to embed |
+| [`headers`](https://ai-sdk.dev/docs/reference/ai-sdk-core/embed#headers)                 | Additional HTTP headers      |
+| [`providerOptions`](https://ai-sdk.dev/docs/reference/ai-sdk-core/embed#provideroptions) | Provider-specific options    |
 
 ##### Image Model Options
 
-| Option | Description |
-|--------|-------------|
-| [`n`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#n) | Number of images to generate |
-| [`size`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#size) | Size of generated images |
-| [`aspectRatio`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#aspectratio) | Aspect ratio of generated images |
-| [`seed`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#seed) | Random seed for reproducibility |
-| [`headers`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#headers) | Additional HTTP headers |
-| [`providerOptions`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#provideroptions) | Provider-specific options |
+| Option                                                                                            | Description                      |
+| ------------------------------------------------------------------------------------------------- | -------------------------------- |
+| [`n`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#n)                             | Number of images to generate     |
+| [`size`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#size)                       | Size of generated images         |
+| [`aspectRatio`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#aspectratio)         | Aspect ratio of generated images |
+| [`seed`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#seed)                       | Random seed for reproducibility  |
+| [`headers`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#headers)                 | Additional HTTP headers          |
+| [`providerOptions`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image#provideroptions) | Provider-specific options        |
+
+#### Dynamic Call Options
+
+You can also override call options dynamically from inside the `onRetry` callback, instead of declaring them statically on the retry object. This is useful when the override depends on something only known at runtime, like the prompt that just failed, the model that's about to be tried next, or the error that triggered the retry. The overrides apply to the upcoming retry attempt only, and can change the same fields as the static `options` on a retry plus the request `timeout`. The callback may also be `async` if computing the override needs to do work (e.g. fetching a fresh credential).
+
+A common use case is sanitizing provider-scoped metadata when falling back to a different provider, for example stripping `providerOptions.azure.itemId` references from the previous prompt before retrying on OpenAI:
+
+```typescript
+import { createRetryable } from 'ai-retry';
+import { azure } from '@ai-sdk/azure';
+import { openai } from '@ai-sdk/openai';
+
+const retryableModel = createRetryable({
+  model: azure('gpt-5-chat'),
+  retries: [openai('gpt-5-chat')],
+  onRetry: (context) => {
+    const { current, attempts } = context;
+    const previous = attempts.at(-1);
+
+    if (current.model.provider !== previous.model.provider) {
+      // Strip provider-scoped metadata from the prompt before retrying on a different provider
+      return {
+        options: {
+          prompt: stripProviderMetadata(current.options.prompt),
+        },
+      };
+    }
+  },
+});
+```
+
+Inside the `onRetry` callback, `context.current.model` is the model that's about to be tried next, while `context.current.options` and `context.current.error` describe the failed attempt that triggered the retry. The previous model is available at `context.attempts.at(-1).model`.
+
+`onRetry` may also be `async`, which is useful if computing the override needs to do work (e.g. fetching a fresh credential):
+
+```typescript
+const retryableModel = createRetryable({
+  model: openai('gpt-4o-mini'),
+  retries: [anthropic('claude-sonnet-4-20250514')],
+  onRetry: async (context) => {
+    const { current } = context;
+
+    const headers = await refreshAuthHeaders(current.model.provider);
+    return { options: { headers } };
+  },
+});
+```
+
+**Precedence** for the upcoming retry attempt (highest to lowest):
+
+1. The value returned from `onRetry`
+2. The `options` returned from the retryable
+3. The original call options from the request
 
 #### Logging
 
 You can use the following callbacks to log retry attempts and errors:
+
 - `onError` is invoked if an error occurs.
 - `onRetry` is invoked before attempting a retry.
 - `onSuccess` is invoked after a successful request with the model that handled it.
@@ -800,17 +987,24 @@ You can use the following callbacks to log retry attempts and errors:
 ```typescript
 const retryableModel = createRetryable({
   model: openai('gpt-4-mini'),
-  retries: [/* your retryables */],
+  retries: [
+    /* your retryables */
+  ],
   onError: (context) => {
-    console.error(`Attempt ${context.attempts.length} with ${context.current.model.provider}/${context.current.model.modelId} failed:`,
-      context.current.error
+    console.error(
+      `Attempt ${context.attempts.length} with ${context.current.model.provider}/${context.current.model.modelId} failed:`,
+      context.current.error,
     );
   },
   onRetry: (context) => {
-    console.log(`Retrying attempt ${context.attempts.length + 1} with model ${context.current.model.provider}/${context.current.model.modelId}...`);
+    console.log(
+      `Retrying attempt ${context.attempts.length + 1} with model ${context.current.model.provider}/${context.current.model.modelId}...`,
+    );
   },
   onSuccess: (context) => {
-    console.log(`Request handled by ${context.current.model.provider}/${context.current.model.modelId}`);
+    console.log(
+      `Request handled by ${context.current.model.provider}/${context.current.model.modelId}`,
+    );
   },
 });
 ```
@@ -819,11 +1013,11 @@ const retryableModel = createRetryable({
 
 By default, every new request starts with the base model, even if a previous request was retried with a different model. The `reset` option changes this behavior by making the last successfully retried model **sticky**, that means subsequent requests will continue using that model instead of switching back to the base model. The reset value controls how long the retry model stays sticky before resetting back to the base model.
 
-| Value | Description |
-|-------|-------------|
-| `after-request` | Reset immediately after the next request (default) |
+| Value              | Description                                                  |
+| ------------------ | ------------------------------------------------------------ |
+| `after-request`    | Reset immediately after the next request (default)           |
 | `after-N-requests` | Keep the retry model for the next **N** requests, then reset |
-| `after-N-seconds` | Keep the retry model for **N** seconds, then reset |
+| `after-N-seconds`  | Keep the retry model for **N** seconds, then reset           |
 
 ##### Reset after each request (default)
 
@@ -874,24 +1068,29 @@ In the second case, errors during stream processing will not always be retried,
 Creates a retryable model that works with language models, embedding models, and image models.
 
 ```ts
-interface RetryableModelOptions<MODEL extends LanguageModelV3 | EmbeddingModelV3 | ImageModelV3> {
+interface RetryableModelOptions<
+  MODEL extends LanguageModelV3 | EmbeddingModelV3 | ImageModelV3,
+> {
   model: MODEL;
   retries: Array<Retryable<MODEL> | MODEL>;
   disabled?: boolean | (() => boolean);
   reset?: Reset;
   onError?: (context: RetryContext<MODEL>) => void;
-  onRetry?: (context: RetryContext<MODEL>) => void;
+  onRetry?: (
+    context: RetryContext<MODEL>,
+  ) => void | OnRetryOverrides<MODEL> | Promise<void | OnRetryOverrides<MODEL>>;
   onSuccess?: (context: SuccessContext<MODEL>) => void;
 }
 ```
 
 **Options:**
+
 - `model`: The base model to use for the initial request.
 - `retries`: Array of retryables (functions, models, or retry objects) to attempt on failure.
 - `disabled`: Disable all retry logic. Can be a boolean or function returning boolean. Default: `false` (retries enabled).
 - `reset`: Controls when to reset back to the base model after a successful retry. Default: `after-request`.
 - `onError`: Callback invoked when an error occurs.
-- `onRetry`: Callback invoked before attempting a retry.
+- `onRetry`: Callback invoked before attempting a retry. May optionally return an `OnRetryOverrides` object (or a `Promise` of one) to override `options.*` and `timeout` for the upcoming attempt only. See [Dynamic Call Options via `onRetry`](#dynamic-call-options-via-onretry).
 - `onSuccess`: Callback invoked after a successful request. Receives the model that handled the request and all previous attempts.
 
 #### `Reset`
@@ -915,9 +1114,7 @@ A `Retryable` is a function that receives a `RetryContext` with the current erro
 It should evaluate the error/result and decide whether to retry by returning a `Retry` or to skip by returning `undefined`.
 
 ```ts
-type Retryable = (
-  context: RetryContext
-) => Retry | Promise<Retry> | undefined;
+type Retryable = (context: RetryContext) => Retry | Promise<Retry> | undefined;
 ```
 
 #### `Retry`
@@ -927,12 +1124,15 @@ A `Retry` specifies the model to retry and optional settings. The available opti
 ```typescript
 interface Retry {
   model: LanguageModelV3 | EmbeddingModelV3 | ImageModelV3;
-  maxAttempts?: number;      // Maximum retry attempts per model (default: 1)
-  delay?: number;            // Delay in milliseconds before retrying
-  backoffFactor?: number;    // Multiplier for exponential backoff
-  timeout?: number;          // Timeout in milliseconds for the retry attempt
+  maxAttempts?: number; // Maximum retry attempts per model (default: 1)
+  delay?: number; // Delay in milliseconds before retrying
+  backoffFactor?: number; // Multiplier for exponential backoff
+  timeout?: number; // Timeout in milliseconds for the retry attempt
   providerOptions?: ProviderOptions; // @deprecated - use options.providerOptions instead
-  options?: LanguageModelV3CallOptions | EmbeddingModelV3CallOptions | ImageModelV3CallOptions; // Call options to override for this retry
+  options?:
+    | LanguageModelV3CallOptions
+    | EmbeddingModelV3CallOptions
+    | ImageModelV3CallOptions; // Call options to override for this retry
 }
 ```
 
@@ -966,8 +1166,15 @@ A `SuccessAttempt` represents the successful attempt with the model, result, and
 interface SuccessAttempt {
   type: 'success';
   model: LanguageModelV3 | EmbeddingModelV3 | ImageModelV3;
-  result: LanguageModelGenerate | LanguageModelStream | EmbeddingModelEmbed | ImageModelGenerate;
-  options: LanguageModelV3CallOptions | EmbeddingModelV3CallOptions | ImageModelV3CallOptions;
+  result:
+    | LanguageModelGenerate
+    | LanguageModelStream
+    | EmbeddingModelEmbed
+    | ImageModelGenerate;
+  options:
+    | LanguageModelV3CallOptions
+    | EmbeddingModelV3CallOptions
+    | ImageModelV3CallOptions;
 }
 ```
 
@@ -982,7 +1189,10 @@ type RetryAttempt =
       type: 'error';
       error: unknown;
       model: LanguageModelV3 | EmbeddingModelV3 | ImageModelV3;
-      options: LanguageModelV3CallOptions | EmbeddingModelV3CallOptions | ImageModelV3CallOptions;
+      options:
+        | LanguageModelV3CallOptions
+        | EmbeddingModelV3CallOptions
+        | ImageModelV3CallOptions;
     }
   | {
       type: 'result';