ai-retry 1.5.0 → 1.6.1

package/README.md

@@ -288,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';
@@ -370,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.
@@ -578,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
@@ -652,7 +782,9 @@ 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.
+When a retry specifies a `timeout` value, a fresh `AbortSignal.timeout()` is created for that retry attempt. If the original `abortSignal` is still alive, the fresh deadline is composed with it via `AbortSignal.any()` so user cancellation still works mid-retry. If the original signal is already aborted (for example it carried a request-level deadline that already fired), it is dropped so the retry runs against the fresh deadline alone.
+
+If the original `abortSignal` is already aborted at the time of retry and the chosen retry does **not** supply a `timeout`, ai-retry rethrows the original error rather than firing a misleading retry against the dead signal. `onError` still fires for observability, but `onRetry` is skipped. Setting `retry.timeout` is the explicit opt-in for retrying past an aborted signal.
 
 ```typescript
 const retryableModel = createRetryable({
@@ -795,7 +927,7 @@ The following options can be overridden:
 
 #### 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).
+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. 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:
 
@@ -815,10 +947,7 @@ const retryableModel = createRetryable({
       // Strip provider-scoped metadata from the prompt before retrying on a different provider
       return {
         options: {
-          prompt: sanitizePromptForProvider(
-            previous.options.prompt,
-            current.model.provider,
-          ),
+          prompt: stripProviderMetadata(current.options.prompt),
         },
       };
     }
@@ -826,6 +955,8 @@ const retryableModel = createRetryable({
 });
 ```
 
+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
@@ -844,7 +975,7 @@ const retryableModel = createRetryable({
 **Precedence** for the upcoming retry attempt (highest to lowest):
 
 1. The value returned from `onRetry`
-2. `Retry.options` (declared on the retryable)
+2. The `options` returned from the retryable
 3. The original call options from the request
 
 #### Logging
@@ -961,7 +1092,7 @@ interface RetryableModelOptions<
 - `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. 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).
+- `onRetry`: Callback invoked before attempting a retry. May optionally return an `OnRetryOverrides` object (or a `Promise` of one) to override `options.*` 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`

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as RetryResultAttempt, C as Result, D as RetryCallOptions, E as RetryAttempt, F as SuccessContext, M as RetryableModelOptions, N as RetryableOptions, O as RetryContext, P as SuccessAttempt, S as ResolvedModel, T as Retry, _ as OnRetryOverrides, a as EmbeddingModelRetryCallOptions, b as ResolvableLanguageModel, c as ImageModelCallOptions, d as LanguageModel, f as LanguageModelCallOptions, g as LanguageModelStreamPart, h as LanguageModelStream, i as EmbeddingModelEmbed, j as Retryable, k as RetryErrorAttempt, l as ImageModelGenerate, m as LanguageModelRetryCallOptions, n as EmbeddingModel, o as GatewayLanguageModelId, p as LanguageModelGenerate, r as EmbeddingModelCallOptions, s as ImageModel, t as CallOptions, u as ImageModelRetryCallOptions, v as ProviderOptions, w as Retries, x as ResolvableModel, y as Reset } from "./types-wrgO_vOH.mjs";
+import { A as RetryResultAttempt, C as Result, D as RetryCallOptions, E as RetryAttempt, F as SuccessContext, M as RetryableModelOptions, N as RetryableOptions, O as RetryContext, P as SuccessAttempt, S as ResolvedModel, T as Retry, _ as OnRetryOverrides, a as EmbeddingModelRetryCallOptions, b as ResolvableLanguageModel, c as ImageModelCallOptions, d as LanguageModel, f as LanguageModelCallOptions, g as LanguageModelStreamPart, h as LanguageModelStream, i as EmbeddingModelEmbed, j as Retryable, k as RetryErrorAttempt, l as ImageModelGenerate, m as LanguageModelRetryCallOptions, n as EmbeddingModel, o as GatewayLanguageModelId, p as LanguageModelGenerate, r as EmbeddingModelCallOptions, s as ImageModel, t as CallOptions, u as ImageModelRetryCallOptions, v as ProviderOptions, w as Retries, x as ResolvableModel, y as Reset } from "./types-CRKV-hdW.mjs";
 import * as _ai_sdk_provider0 from "@ai-sdk/provider";
 
 //#region src/create-retryable-model.d.ts

package/dist/index.mjs

@@ -197,14 +197,18 @@ function resolveProviderOptions(base, currentRetry, onRetryOverrides) {
 /**
 * Resolve `abortSignal` for the upcoming attempt.
 *
-* If either `onRetryOverrides.timeout` or `currentRetry.timeout` is set, a
-* fresh `AbortSignal.timeout(...)` is created (override wins). Otherwise
-* the base `abortSignal` is preserved unchanged.
+* If `currentRetry.timeout` is set, a fresh `AbortSignal.timeout(...)` is
+* created. When the base signal is still alive, the fresh deadline is
+* composed with it via `AbortSignal.any` so the user can still cancel
+* mid-retry. When the base is already aborted, it is dropped so the retry
+* runs against the fresh deadline alone. Without a retry timeout, the base
+* is preserved unchanged.
 */
-function resolveAbortSignal(base, currentRetry, onRetryOverrides) {
-	if (onRetryOverrides?.timeout !== void 0) return AbortSignal.timeout(onRetryOverrides.timeout);
-	if (currentRetry?.timeout !== void 0) return AbortSignal.timeout(currentRetry.timeout);
-	return base;
+function resolveAbortSignal(base, currentRetry) {
+	if (currentRetry?.timeout === void 0) return base;
+	const fresh = AbortSignal.timeout(currentRetry.timeout);
+	if (base !== void 0 && !base.aborted) return AbortSignal.any([base, fresh]);
+	return fresh;
 }
 /**
 * Merge call options for the upcoming language model retry attempt.
@@ -231,7 +235,7 @@ function mergeLanguageModelCallOptions(input) {
 		seed: overrideOptions.seed ?? retryOptions.seed ?? callOptions.seed,
 		headers: overrideOptions.headers ?? retryOptions.headers ?? callOptions.headers,
 		providerOptions: resolveProviderOptions(callOptions.providerOptions, currentRetry, onRetryOverrides),
-		abortSignal: resolveAbortSignal(callOptions.abortSignal, currentRetry, onRetryOverrides)
+		abortSignal: resolveAbortSignal(callOptions.abortSignal, currentRetry)
 	};
 }
 /**
@@ -246,7 +250,7 @@ function mergeEmbeddingModelCallOptions(input) {
 		values: overrideOptions.values ?? retryOptions.values ?? callOptions.values,
 		headers: overrideOptions.headers ?? retryOptions.headers ?? callOptions.headers,
 		providerOptions: resolveProviderOptions(callOptions.providerOptions, currentRetry, onRetryOverrides),
-		abortSignal: resolveAbortSignal(callOptions.abortSignal, currentRetry, onRetryOverrides)
+		abortSignal: resolveAbortSignal(callOptions.abortSignal, currentRetry)
 	};
 }
 /**
@@ -264,7 +268,7 @@ function mergeImageModelCallOptions(input) {
 		seed: overrideOptions.seed ?? retryOptions.seed ?? callOptions.seed,
 		headers: overrideOptions.headers ?? retryOptions.headers ?? callOptions.headers,
 		providerOptions: resolveProviderOptions(callOptions.providerOptions, currentRetry, onRetryOverrides),
-		abortSignal: resolveAbortSignal(callOptions.abortSignal, currentRetry, onRetryOverrides)
+		abortSignal: resolveAbortSignal(callOptions.abortSignal, currentRetry)
 	};
 }
 
@@ -331,9 +335,15 @@ var RetryableEmbeddingModel = class extends BaseRetryableModel {
 					callOptions: retryCallOptions
 				};
 			} catch (error) {
-				if (isAbortError(error)) throw error;
 				const { retryModel, attempt } = await this.handleError(error, attempts, retryCallOptions);
 				attempts.push(attempt);
+				/**
+				* If the inbound abort signal is already aborted and the chosen
+				* retry does not supply a fresh deadline, the retry would die
+				* instantly with the same abort. Rethrow rather than fire a
+				* misleading retry against a dead signal.
+				*/
+				if (input.callOptions.abortSignal?.aborted && retryModel.timeout === void 0) throw error;
 				if (retryModel.delay) {
 					/**
 					* Calculate exponential backoff delay based on the number of attempts for this specific model.
@@ -474,11 +484,15 @@ var RetryableImageModel = class extends BaseRetryableModel {
 					callOptions: retryCallOptions
 				};
 			} catch (error) {
-				/** Don't retry if user manually aborted the request. */
-				/** TimeoutError from AbortSignal.timeout() will still be handled by retry handlers. */
-				if (isAbortError(error)) throw error;
 				const { retryModel, attempt } = await this.handleError(error, attempts, retryCallOptions);
 				attempts.push(attempt);
+				/**
+				* If the inbound abort signal is already aborted and the chosen
+				* retry does not supply a fresh deadline, the retry would die
+				* instantly with the same abort. Rethrow rather than fire a
+				* misleading retry against a dead signal.
+				*/
+				if (input.callOptions.abortSignal?.aborted && retryModel.timeout === void 0) throw error;
 				if (retryModel.delay) {
 					/**
 					* Calculate exponential backoff delay based on the number of attempts for this specific model.
@@ -650,9 +664,15 @@ var RetryableLanguageModel = class extends BaseRetryableModel {
 					callOptions: retryCallOptions
 				};
 			} catch (error) {
-				if (isAbortError(error)) throw error;
 				const { retryModel, attempt } = await this.handleError(error, attempts, retryCallOptions);
 				attempts.push(attempt);
+				/**
+				* If the inbound abort signal is already aborted and the chosen
+				* retry does not supply a fresh deadline, the retry would die
+				* instantly with the same abort. Rethrow rather than fire a
+				* misleading retry against a dead signal.
+				*/
+				if (input.callOptions.abortSignal?.aborted && retryModel.timeout === void 0) throw error;
 				if (retryModel.delay) {
 					/**
 					* Calculate exponential backoff delay based on the number of attempts for this specific model.
@@ -825,6 +845,13 @@ var RetryableLanguageModel = class extends BaseRetryableModel {
 				* Save the attempt
 				*/
 				attempts.push(attempt);
+				/**
+				* If the inbound abort signal is already aborted and the chosen
+				* retry does not supply a fresh deadline, the retry would die
+				* instantly with the same abort. Rethrow rather than fire a
+				* misleading retry against a dead signal.
+				*/
+				if (callOptions.abortSignal?.aborted && retryModel.timeout === void 0) throw error;
 				if (retryModel.delay) {
 					/**
 					* Calculate exponential backoff delay based on the number of attempts for this specific model.

package/dist/parse-retry-headers-DIPVbwW5.mjs

@@ -0,0 +1,26 @@
+//#region src/parse-retry-headers.ts
+/**
+* Upper bound for `Retry-After` / `Retry-After-Ms` honored by retry actions.
+* Servers can technically request very long delays; cap to keep retries
+* responsive.
+*/
+const MAX_RETRY_AFTER_MS = 6e4;
+function parseRetryHeaders(headers) {
+	if (!headers) return null;
+	const retryAfterMs = headers["retry-after-ms"];
+	if (retryAfterMs) {
+		const delayMs = Number.parseFloat(retryAfterMs);
+		if (!Number.isNaN(delayMs) && delayMs >= 0) return delayMs;
+	}
+	const retryAfter = headers["retry-after"];
+	if (retryAfter) {
+		const seconds = Number.parseFloat(retryAfter);
+		if (!Number.isNaN(seconds)) return seconds * 1e3;
+		const date = Date.parse(retryAfter);
+		if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+	}
+	return null;
+}
+
+//#endregion
+export { parseRetryHeaders as n, MAX_RETRY_AFTER_MS as t };

package/dist/retryables/experimental/index.d.mts

@@ -0,0 +1,248 @@
+import { O as RetryContext, T as Retry, b as ResolvableLanguageModel, j as Retryable, n as EmbeddingModel, p as LanguageModelGenerate, s as ImageModel } from "../../types-CRKV-hdW.mjs";
+
+//#region src/retryables/experimental/condition.d.ts
+/**
+ * Any model the retryable system supports.
+ */
+type AnyModel = ResolvableLanguageModel | EmbeddingModel | ImageModel;
+/**
+ * Predicate over a `RetryContext`. May be sync or async.
+ */
+type Predicate<MODEL extends AnyModel> = (ctx: RetryContext<MODEL>) => boolean | Promise<boolean>;
+/**
+ * Argument shape for `Condition.switch`. The target `model` is required;
+ * all other `Retry` fields are optional.
+ */
+type SwitchTarget<MODEL extends AnyModel> = {
+  model: MODEL;
+} & Omit<Retry<MODEL>, 'model'>;
+/**
+ * Argument shape for `Condition.retry`. Same as `Retry` without `model`,
+ * since retry reuses the current model.
+ */
+type RetryOptions<MODEL extends AnyModel> = Omit<Retry<MODEL>, 'model'>;
+/**
+ * A predicate over a `RetryContext` paired with two terminal actions
+ * (`switch`, `retry`) that turn it into a `Retryable<MODEL>`. Compose
+ * conditions with `and`, `or`, `not`.
+ *
+ * @example
+ * const cond = httpStatus(429, 503);
+ * cond.switch({ model: fallback });
+ * cond.retry({ delay: 1000 });
+ */
+declare class Condition<MODEL extends AnyModel> {
+  private readonly predicate;
+  constructor(predicate: Predicate<MODEL>);
+  /**
+   * Run the predicate against a context and resolve to a boolean.
+   */
+  evaluate(ctx: RetryContext<MODEL>): Promise<boolean>;
+  /**
+   * Switch to a different model when the condition matches.
+   *
+   * @example
+   * httpStatus(529).switch({ model: fallback })
+   */
+  switch(target: SwitchTarget<MODEL>): Retryable<MODEL>;
+  /**
+   * Retry the same model when the condition matches. Honors
+   * `Retry-After` and `Retry-After-Ms` response headers when present,
+   * capped at 60 seconds, overriding any provided `delay`.
+   *
+   * @example
+   * error.isRetryable(true).retry({ delay: 1000, backoffFactor: 2 })
+   */
+  retry(options?: RetryOptions<MODEL>): Retryable<MODEL>;
+  /**
+   * Combine with another condition; matches when both match.
+   *
+   * @example
+   * httpStatus(429).and(error.message('overloaded'))
+   */
+  and(other: Condition<MODEL>): Condition<MODEL>;
+  /**
+   * Combine with another condition; matches when either matches.
+   *
+   * @example
+   * httpStatus(429).or(error.message('overloaded'))
+   */
+  or(other: Condition<MODEL>): Condition<MODEL>;
+  /**
+   * Invert the condition.
+   *
+   * @example
+   * error.isRetryable(true).not()
+   */
+  not(): Condition<MODEL>;
+}
+//#endregion
+//#region src/retryables/experimental/aborted.d.ts
+/**
+ * Match a manual abort: an `Error` with `name === 'AbortError'`, which
+ * `controller.abort()` produces. Distinct from `timeout()`, which
+ * matches `AbortSignal.timeout()` firing.
+ *
+ * @example
+ * aborted().switch({ model: fallback })
+ */
+declare function aborted<MODEL extends AnyModel = AnyModel>(): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/and.d.ts
+/**
+ * Match only when all of the given conditions match. Evaluates left to
+ * right and stops on the first miss.
+ *
+ * @example
+ * and(httpStatus(429), error.message('overloaded'))
+ */
+declare function and<MODEL extends AnyModel>(...conditions: Array<Condition<MODEL>>): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/error.d.ts
+/**
+ * Build a condition from a predicate over the current error. The
+ * predicate runs only when the current attempt failed with an error;
+ * result attempts return false.
+ *
+ * @example
+ * error<MODEL, APICallError>(
+ *   (e) => APICallError.isInstance(e) && e.statusCode === 418,
+ * )
+ */
+declare function error<MODEL extends AnyModel = AnyModel, E = unknown>(predicate: (err: E, ctx: RetryContext<MODEL>) => boolean | Promise<boolean>): Condition<MODEL>;
+/**
+ * Higher-level matchers for common error fields. Drop down to `error(fn)`
+ * for anything not covered.
+ *
+ * `Error.name` is intentionally not exposed here because the property
+ * name would clash with `Function.prototype.name`. Use `timeout()` or
+ * `aborted()` for the common cases, or `error(fn)` for custom names.
+ */
+declare namespace error {
+  /**
+   * Match when the error explicitly carries `isRetryable === flag`.
+   *
+   * @example
+   * error.isRetryable(true).retry({ delay: 1000 })
+   * error.isRetryable(false).switch({ model: fallback })
+   */
+  function isRetryable<MODEL extends AnyModel = AnyModel>(flag?: boolean): Condition<MODEL>;
+  /**
+   * Match by HTTP status code. Numbers match exactly; regular expressions
+   * match against the stringified code, useful for range checks.
+   *
+   * @example
+   * error.statusCode(429, 503)
+   * error.statusCode(/^5\d\d$/)
+   */
+  function statusCode<MODEL extends AnyModel = AnyModel>(...patterns: Array<number | RegExp>): Condition<MODEL>;
+  /**
+   * Match the error message against substrings or regular expressions.
+   * Substring matching is case-insensitive: both the pattern and the
+   * message are lowercased before matching. Regular expressions match
+   * as written; use the `i` flag for case-insensitive regex matching.
+   *
+   * @example
+   * error.message('overloaded')
+   * error.message(/rate.?limit/i)
+   * error.message('overloaded', /rate.?limit/i)
+   */
+  function message<MODEL extends AnyModel = AnyModel>(...patterns: Array<string | RegExp>): Condition<MODEL>;
+}
+//#endregion
+//#region src/retryables/experimental/finish-reason.d.ts
+/**
+ * Match the result's finish reason against one of the given values.
+ *
+ * @example
+ * finishReason('content-filter')
+ * finishReason('content-filter', 'length')
+ */
+declare function finishReason<MODEL extends ResolvableLanguageModel = ResolvableLanguageModel>(...reasons: Array<string>): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/http-status.d.ts
+/**
+ * A pattern accepted by `httpStatus`. Numbers match the response status
+ * code; strings match the error message as a substring; regular
+ * expressions match against both the stringified status code and the
+ * error message.
+ */
+type StatusPattern = number | string | RegExp;
+/**
+ * Match an `APICallError` by status code, message substring, or regular
+ * expression. Numbers match the status code; strings match the message;
+ * regular expressions match either the stringified status code or the
+ * message. Mix any combination in a single call; matches when any
+ * pattern matches.
+ *
+ * @example
+ * httpStatus(529)
+ * httpStatus(529, 'overloaded')
+ * httpStatus(/^5\d\d$/)
+ * httpStatus(529, 'overloaded', /rate.?limit/i)
+ */
+declare function httpStatus<MODEL extends AnyModel = AnyModel>(...patterns: Array<StatusPattern>): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/no-image.d.ts
+/**
+ * Match when image generation produced no images
+ * (`NoImageGeneratedError`).
+ *
+ * @example
+ * noImage().switch({ model: fallback })
+ */
+declare function noImage<MODEL extends ImageModel = ImageModel>(): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/not.d.ts
+/**
+ * Invert a condition.
+ *
+ * @example
+ * not(error.isRetryable(true))
+ */
+declare function not<MODEL extends AnyModel>(condition: Condition<MODEL>): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/or.d.ts
+/**
+ * Match when any of the given conditions match. Evaluates left to right
+ * and stops on the first match.
+ *
+ * @example
+ * or(httpStatus(429), error.message('overloaded'))
+ */
+declare function or<MODEL extends AnyModel>(...conditions: Array<Condition<MODEL>>): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/result.d.ts
+/**
+ * Build a condition from a predicate over the current generate result.
+ * Available for language models only. The predicate runs only when the
+ * current attempt succeeded; error attempts return false.
+ *
+ * @example
+ * result<MODEL>((res) => res.finishReason.unified === 'length')
+ */
+declare function result<MODEL extends ResolvableLanguageModel = ResolvableLanguageModel>(predicate: (res: LanguageModelGenerate, ctx: RetryContext<MODEL>) => boolean | Promise<boolean>): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/schema-invalid.d.ts
+/**
+ * Match when the result text fails JSON schema validation. The schema is
+ * read from the call's `responseFormat`, which `Output.object()` sets
+ * automatically. No-op when no schema is configured.
+ *
+ * @example
+ * schemaInvalid().switch({ model: fallback })
+ */
+declare function schemaInvalid<MODEL extends ResolvableLanguageModel = ResolvableLanguageModel>(): Condition<MODEL>;
+//#endregion
+//#region src/retryables/experimental/timeout.d.ts
+/**
+ * Match a timeout error: an `Error` with `name === 'TimeoutError'`,
+ * which `AbortSignal.timeout()` produces when the timeout fires.
+ * Distinct from `aborted()`, which matches manual aborts.
+ *
+ * @example
+ * timeout().switch({ model: fallback, timeout: 60_000 })
+ */
+declare function timeout<MODEL extends AnyModel = AnyModel>(): Condition<MODEL>;
+//#endregion
+export { AnyModel, Condition, Predicate, RetryOptions, StatusPattern, SwitchTarget, aborted, and, error, finishReason, httpStatus, noImage, not, or, result, schemaInvalid, timeout };

package/dist/retryables/experimental/index.mjs

@@ -0,0 +1,310 @@
+import { l as isResultAttempt, r as isErrorAttempt } from "../../utils-CfnsSGrw.mjs";
+import { n as parseRetryHeaders, t as MAX_RETRY_AFTER_MS } from "../../parse-retry-headers-DIPVbwW5.mjs";
+import { APICallError, NoImageGeneratedError } from "ai";
+import { safeParseJSON } from "@ai-sdk/provider-utils";
+import { fromJSONSchema } from "zod";
+
+//#region src/retryables/experimental/condition.ts
+/**
+* A predicate over a `RetryContext` paired with two terminal actions
+* (`switch`, `retry`) that turn it into a `Retryable<MODEL>`. Compose
+* conditions with `and`, `or`, `not`.
+*
+* @example
+* const cond = httpStatus(429, 503);
+* cond.switch({ model: fallback });
+* cond.retry({ delay: 1000 });
+*/
+var Condition = class Condition {
+	constructor(predicate) {
+		this.predicate = predicate;
+	}
+	/**
+	* Run the predicate against a context and resolve to a boolean.
+	*/
+	async evaluate(ctx) {
+		return this.predicate(ctx);
+	}
+	/**
+	* Switch to a different model when the condition matches.
+	*
+	* @example
+	* httpStatus(529).switch({ model: fallback })
+	*/
+	switch(target) {
+		return async (ctx) => {
+			if (!await this.evaluate(ctx)) return void 0;
+			return {
+				maxAttempts: 1,
+				...target
+			};
+		};
+	}
+	/**
+	* Retry the same model when the condition matches. Honors
+	* `Retry-After` and `Retry-After-Ms` response headers when present,
+	* capped at 60 seconds, overriding any provided `delay`.
+	*
+	* @example
+	* error.isRetryable(true).retry({ delay: 1000, backoffFactor: 2 })
+	*/
+	retry(options) {
+		return async (ctx) => {
+			if (!await this.evaluate(ctx)) return void 0;
+			const model = ctx.current.model;
+			if (isErrorAttempt(ctx.current)) {
+				const { error: err } = ctx.current;
+				if (APICallError.isInstance(err)) {
+					const headerDelay = parseRetryHeaders(err.responseHeaders);
+					if (headerDelay !== null) return {
+						model,
+						...options,
+						delay: Math.min(headerDelay, MAX_RETRY_AFTER_MS),
+						backoffFactor: 1
+					};
+				}
+			}
+			return {
+				model,
+				...options
+			};
+		};
+	}
+	/**
+	* Combine with another condition; matches when both match.
+	*
+	* @example
+	* httpStatus(429).and(error.message('overloaded'))
+	*/
+	and(other) {
+		return new Condition(async (ctx) => await this.evaluate(ctx) && await other.evaluate(ctx));
+	}
+	/**
+	* Combine with another condition; matches when either matches.
+	*
+	* @example
+	* httpStatus(429).or(error.message('overloaded'))
+	*/
+	or(other) {
+		return new Condition(async (ctx) => await this.evaluate(ctx) || await other.evaluate(ctx));
+	}
+	/**
+	* Invert the condition.
+	*
+	* @example
+	* error.isRetryable(true).not()
+	*/
+	not() {
+		return new Condition(async (ctx) => !await this.evaluate(ctx));
+	}
+};
+
+//#endregion
+//#region src/retryables/experimental/error.ts
+/**
+* Build a condition from a predicate over the current error. The
+* predicate runs only when the current attempt failed with an error;
+* result attempts return false.
+*
+* @example
+* error<MODEL, APICallError>(
+*   (e) => APICallError.isInstance(e) && e.statusCode === 418,
+* )
+*/
+function error(predicate) {
+	return new Condition(async (ctx) => {
+		if (!isErrorAttempt(ctx.current)) return false;
+		return predicate(ctx.current.error, ctx);
+	});
+}
+(function(_error) {
+	function isRetryable(flag = true) {
+		return error((e) => APICallError.isInstance(e) && e.isRetryable === flag);
+	}
+	_error.isRetryable = isRetryable;
+	function statusCode(...patterns) {
+		return error((e) => {
+			if (!APICallError.isInstance(e)) return false;
+			const code = e.statusCode;
+			if (code === void 0) return false;
+			return patterns.some((p) => typeof p === "number" ? p === code : p.test(String(code)));
+		});
+	}
+	_error.statusCode = statusCode;
+	function message(...patterns) {
+		return error((e) => {
+			if (!(e instanceof Error)) return false;
+			const lower = e.message.toLowerCase();
+			return patterns.some((p) => typeof p === "string" ? lower.includes(p.toLowerCase()) : p.test(e.message));
+		});
+	}
+	_error.message = message;
+})(error || (error = {}));
+
+//#endregion
+//#region src/retryables/experimental/aborted.ts
+/**
+* Match a manual abort: an `Error` with `name === 'AbortError'`, which
+* `controller.abort()` produces. Distinct from `timeout()`, which
+* matches `AbortSignal.timeout()` firing.
+*
+* @example
+* aborted().switch({ model: fallback })
+*/
+function aborted() {
+	return error((err) => err instanceof Error && err.name === "AbortError");
+}
+
+//#endregion
+//#region src/retryables/experimental/and.ts
+/**
+* Match only when all of the given conditions match. Evaluates left to
+* right and stops on the first miss.
+*
+* @example
+* and(httpStatus(429), error.message('overloaded'))
+*/
+function and(...conditions) {
+	return new Condition(async (ctx) => {
+		for (const c of conditions) if (!await c.evaluate(ctx)) return false;
+		return true;
+	});
+}
+
+//#endregion
+//#region src/retryables/experimental/result.ts
+/**
+* Build a condition from a predicate over the current generate result.
+* Available for language models only. The predicate runs only when the
+* current attempt succeeded; error attempts return false.
+*
+* @example
+* result<MODEL>((res) => res.finishReason.unified === 'length')
+*/
+function result(predicate) {
+	return new Condition(async (ctx) => {
+		if (!isResultAttempt(ctx.current)) return false;
+		return predicate(ctx.current.result, ctx);
+	});
+}
+
+//#endregion
+//#region src/retryables/experimental/finish-reason.ts
+/**
+* Match the result's finish reason against one of the given values.
+*
+* @example
+* finishReason('content-filter')
+* finishReason('content-filter', 'length')
+*/
+function finishReason(...reasons) {
+	return result((res) => reasons.includes(res.finishReason.unified));
+}
+
+//#endregion
+//#region src/retryables/experimental/or.ts
+/**
+* Match when any of the given conditions match. Evaluates left to right
+* and stops on the first match.
+*
+* @example
+* or(httpStatus(429), error.message('overloaded'))
+*/
+function or(...conditions) {
+	return new Condition(async (ctx) => {
+		for (const c of conditions) if (await c.evaluate(ctx)) return true;
+		return false;
+	});
+}
+
+//#endregion
+//#region src/retryables/experimental/http-status.ts
+/**
+* Match an `APICallError` by status code, message substring, or regular
+* expression. Numbers match the status code; strings match the message;
+* regular expressions match either the stringified status code or the
+* message. Mix any combination in a single call; matches when any
+* pattern matches.
+*
+* @example
+* httpStatus(529)
+* httpStatus(529, 'overloaded')
+* httpStatus(/^5\d\d$/)
+* httpStatus(529, 'overloaded', /rate.?limit/i)
+*/
+function httpStatus(...patterns) {
+	const numbers = patterns.filter((p) => typeof p === "number");
+	const strings = patterns.filter((p) => typeof p === "string");
+	const regexes = patterns.filter((p) => p instanceof RegExp);
+	const conditions = [];
+	if (numbers.length || regexes.length) conditions.push(error.statusCode(...numbers, ...regexes));
+	if (strings.length || regexes.length) conditions.push(error.message(...strings, ...regexes));
+	return or(...conditions);
+}
+
+//#endregion
+//#region src/retryables/experimental/no-image.ts
+/**
+* Match when image generation produced no images
+* (`NoImageGeneratedError`).
+*
+* @example
+* noImage().switch({ model: fallback })
+*/
+function noImage() {
+	return error((err) => NoImageGeneratedError.isInstance(err));
+}
+
+//#endregion
+//#region src/retryables/experimental/not.ts
+/**
+* Invert a condition.
+*
+* @example
+* not(error.isRetryable(true))
+*/
+function not(condition) {
+	return condition.not();
+}
+
+//#endregion
+//#region src/retryables/experimental/schema-invalid.ts
+/**
+* Match when the result text fails JSON schema validation. The schema is
+* read from the call's `responseFormat`, which `Output.object()` sets
+* automatically. No-op when no schema is configured.
+*
+* @example
+* schemaInvalid().switch({ model: fallback })
+*/
+function schemaInvalid() {
+	return result(async (res, ctx) => {
+		if (!isResultAttempt(ctx.current)) return false;
+		const callOptions = ctx.current.options;
+		const text = res.content.filter((part) => part.type === "text").map((part) => part.text).join("");
+		if (!text) return false;
+		const responseFormat = callOptions.responseFormat;
+		if (responseFormat?.type !== "json" || !responseFormat.schema) return false;
+		return !(await safeParseJSON({
+			text,
+			schema: fromJSONSchema(responseFormat.schema)
+		})).success;
+	});
+}
+
+//#endregion
+//#region src/retryables/experimental/timeout.ts
+/**
+* Match a timeout error: an `Error` with `name === 'TimeoutError'`,
+* which `AbortSignal.timeout()` produces when the timeout fires.
+* Distinct from `aborted()`, which matches manual aborts.
+*
+* @example
+* timeout().switch({ model: fallback, timeout: 60_000 })
+*/
+function timeout() {
+	return error((err) => err instanceof Error && err.name === "TimeoutError");
+}
+
+//#endregion
+export { Condition, aborted, and, error, finishReason, httpStatus, noImage, not, or, result, schemaInvalid, timeout };

package/dist/retryables/index.d.mts

@@ -1,4 +1,4 @@
-import { N as RetryableOptions, b as ResolvableLanguageModel, j as Retryable, n as EmbeddingModel, s as ImageModel } from "../types-wrgO_vOH.mjs";
+import { N as RetryableOptions, b as ResolvableLanguageModel, j as Retryable, n as EmbeddingModel, s as ImageModel } from "../types-CRKV-hdW.mjs";
 
 //#region src/retryables/content-filter-triggered.d.ts
 /**

package/dist/retryables/index.mjs

@@ -1,4 +1,5 @@
 import { c as isObject, f as isString, l as isResultAttempt, p as isTimeoutError, r as isErrorAttempt } from "../utils-CfnsSGrw.mjs";
+import { n as parseRetryHeaders, t as MAX_RETRY_AFTER_MS } from "../parse-retry-headers-DIPVbwW5.mjs";
 import { APICallError, NoImageGeneratedError } from "ai";
 import { safeParseJSON } from "@ai-sdk/provider-utils";
 import { fromJSONSchema } from "zod";
@@ -91,28 +92,8 @@ function requestTimeout(model, options) {
 	};
 }
 
-//#endregion
-//#region src/parse-retry-headers.ts
-function parseRetryHeaders(headers) {
-	if (!headers) return null;
-	const retryAfterMs = headers["retry-after-ms"];
-	if (retryAfterMs) {
-		const delayMs = Number.parseFloat(retryAfterMs);
-		if (!Number.isNaN(delayMs) && delayMs >= 0) return delayMs;
-	}
-	const retryAfter = headers["retry-after"];
-	if (retryAfter) {
-		const seconds = Number.parseFloat(retryAfter);
-		if (!Number.isNaN(seconds)) return seconds * 1e3;
-		const date = Date.parse(retryAfter);
-		if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
-	}
-	return null;
-}
-
 //#endregion
 //#region src/retryables/retry-after-delay.ts
-const MAX_RETRY_AFTER_MS = 6e4;
 /**
 * Retry the current failed attempt with the same model, if the error is retryable.
 * Uses the `Retry-After` or `Retry-After-Ms` headers if present.

package/dist/{types-wrgO_vOH.d.mts → types-CRKV-hdW.d.mts}

@@ -34,7 +34,7 @@ type RetryCallOptions<MODEL extends LanguageModel | EmbeddingModel | ImageModel>
 /**
  * Override returned by `onRetry` to influence the upcoming retry attempt.
  */
-type OnRetryOverrides<MODEL extends LanguageModel | EmbeddingModel | ImageModel> = Pick<Retry<MODEL>, 'options' | 'timeout'>;
+type OnRetryOverrides<MODEL extends LanguageModel | EmbeddingModel | ImageModel> = Pick<Retry<MODEL>, 'options'>;
 /**
  * Maps a model type to its call options type.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-retry",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Retry and fallback mechanisms for AI SDK",
   "keywords": [
     "ai",
@@ -22,6 +22,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./retryables": "./dist/retryables/index.mjs",
+    "./retryables/experimental": "./dist/retryables/experimental/index.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {