ai-retry 1.8.0 → 1.9.1

package/README.md

@@ -1141,28 +1141,28 @@ ai_retry.doGenerate            outcome=success, attempts=2
 
 **Operation span** attributes:
 
-| Attribute                                                | Description                                             |
-| -------------------------------------------------------- | ------------------------------------------------------- |
-| `ai_retry.operation`                                     | `doGenerate`, `doStream`, or `doEmbed`                  |
-| `ai_retry.outcome`                                       | `success` or `failure`                                  |
-| `ai_retry.attempts`                                      | total number of attempts                                |
-| `ai_retry.model.start`                                   | the model the request started with (`provider/modelId`) |
-| `ai_retry.model.final`                                   | the model that produced the final outcome               |
-| `ai_retry.error.{name,message,cause.name,cause.message}` | the failing error (on failure)                          |
-| `ai_retry.function.id`, `ai_retry.metadata.*`            | from the telemetry settings                             |
+| Attribute                                                       | Description                                                                  |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `ai_retry.operation`                                            | `doGenerate`, `doStream`, or `doEmbed`                                       |
+| `ai_retry.outcome`                                              | `success` or `failure`                                                       |
+| `ai_retry.attempts`                                             | total number of attempts                                                     |
+| `ai_retry.model.start`                                          | the model the request started with (`provider/modelId`)                      |
+| `ai_retry.model.final`                                          | the model that produced the final outcome                                    |
+| `ai_retry.error.{name,message,status,cause.name,cause.message,cause.status}` | the failing error (on failure); `status` when it carries an HTTP status code |
+| `ai_retry.function.id`, `ai_retry.metadata.*`                   | from the telemetry settings                                                  |
 
 **Attempt span** (`ai_retry.attempt`) attributes:
 
-| Attribute                                                        | Description                               |
-| ---------------------------------------------------------------- | ----------------------------------------- |
-| `ai_retry.attempt.number`                                        | 1-based attempt index                     |
-| `ai_retry.attempt.model`                                         | model used (`provider/modelId`)           |
-| `ai_retry.attempt.outcome`                                       | `success`, `retry`, or `failure`          |
-| `ai_retry.attempt.type`                                          | `result` or `error`                       |
-| `ai_retry.attempt.finish_reason`                                 | finish reason (result attempts)           |
-| `ai_retry.attempt.delay_ms`                                      | backoff scheduled before the next attempt |
-| `ai_retry.attempt.timeout_ms`                                    | timeout budget, when the retry set one    |
-| `ai_retry.attempt.error.{name,message,cause.name,cause.message}` | the error (error attempts)                |
+| Attribute                                                               | Description                                                              |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `ai_retry.attempt.number`                                               | 1-based attempt index                                                    |
+| `ai_retry.attempt.model`                                                | model used (`provider/modelId`)                                          |
+| `ai_retry.attempt.outcome`                                              | `success`, `retry`, or `failure`                                         |
+| `ai_retry.attempt.type`                                                 | `result` or `error`                                                      |
+| `ai_retry.attempt.finish_reason`                                        | finish reason (result attempts)                                          |
+| `ai_retry.attempt.delay_ms`                                             | backoff scheduled before the next attempt                                |
+| `ai_retry.attempt.timeout_ms`                                           | timeout budget, when the retry set one                                   |
+| `ai_retry.attempt.error.{name,message,status,cause.name,cause.message,cause.status}` | the error (error attempts); `status` when it carries an HTTP status code |
 
 Attempt spans also carry the standard `gen_ai.request.model` / `gen_ai.provider.name` attributes so observability tools (Langfuse, etc.) recognize and render them.
 
@@ -1183,6 +1183,13 @@ In the second case, errors during stream processing will not always be retried,
 > [!IMPORTANT]
 > **Streaming limitation:** Retries and fallbacks only apply before the first content chunk is emitted. Once streaming begins delivering content, the response is committed to the current model. Mid-stream errors will propagate to the caller rather than triggering a fallback. If reliable retries are critical for your use case, consider using `generateText` instead of `streamText`.
 
+#### Preamble buffering
+
+Every stream begins with a non-content preamble (`stream-start`, then optionally `response-metadata` and `text-start` / `reasoning-start`) that providers emit as soon as the response headers arrive, before any content flows. Because a retry can still happen during this window, `ai-retry` does not forward the preamble immediately. It buffers the leading non-content parts and flushes them only when the first content chunk arrives (or when the stream finishes with no content). If a retry fires before any content, the buffered preamble is discarded and replaced by the fallback's, so the consumer always sees exactly one preamble — the one belonging to the model that actually produced the output, with its own `warnings` and `response-metadata`. Without this, a fallback's `stream-start` would be emitted a second time after the primary's, which some consumers (e.g. `streamText`) reject.
+
+> [!NOTE]
+> One side effect: the consumer's "stream started" signal now arrives at first-content time rather than when the response headers arrive (typically a sub-second difference). For UIs that show a typing indicator off `stream-start` this is negligible.
+
 ### API Reference
 
 #### `createRetryable(options: RetryableModelOptions): LanguageModelV3 | EmbeddingModelV3 | ImageModelV3`

package/dist/{create-retryable-model-BdA-OoIc.mjs → create-retryable-model-Ch2cqC3Z.mjs}

@@ -311,13 +311,18 @@ function loadOtelApi() {
 	return otelApiPromise;
 }
 /**
-* Coarse error label for the `*.error.name` / `*.error.cause.name` attributes.
-* Matches the SDK's habit of using the error class name (e.g. `AI_APICallError`,
-* `TimeoutError`).
+* Normalize an unknown thrown value into the fields recorded on error spans:
+* - `name`: the error class name (e.g. `AI_APICallError`, `TimeoutError`), or
+*   `typeof` for non-`Error` values.
+* - `message`: the error message.
+* - `status`: HTTP status code, when the error carries one (e.g. `APICallError`).
 */
-function errorType(error) {
-	if (error instanceof Error) return error.name;
-	return typeof error;
+function describeError(error) {
+	return {
+		name: error instanceof Error ? error.name : typeof error,
+		message: error instanceof Error ? error.message : String(error),
+		status: typeof error === "object" && error !== null && "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : void 0
+	};
 }
 /**
 * Translates retry telemetry events into OpenTelemetry spans.
@@ -394,18 +399,22 @@ var OpenTelemetrySink = class {
 	}
 	#recordError(span, error, errorAttribute) {
 		const exception = error instanceof Error ? error : new Error(String(error));
-		span.setAttribute(`${errorAttribute}.name`, errorType(error));
-		span.setAttribute(`${errorAttribute}.message`, exception.message);
+		const info = describeError(error);
+		span.setAttribute(`${errorAttribute}.name`, info.name);
+		span.setAttribute(`${errorAttribute}.message`, info.message);
+		if (info.status !== void 0) span.setAttribute(`${errorAttribute}.status`, info.status);
 		/** One level of the error chain — the underlying cause, when present. */
 		const cause = error instanceof Error ? error.cause : void 0;
 		if (cause !== void 0) {
-			span.setAttribute(`${errorAttribute}.cause.name`, errorType(cause));
-			span.setAttribute(`${errorAttribute}.cause.message`, cause instanceof Error ? cause.message : String(cause));
+			const causeInfo = describeError(cause);
+			span.setAttribute(`${errorAttribute}.cause.name`, causeInfo.name);
+			span.setAttribute(`${errorAttribute}.cause.message`, causeInfo.message);
+			if (causeInfo.status !== void 0) span.setAttribute(`${errorAttribute}.cause.status`, causeInfo.status);
 		}
 		span.recordException(exception);
 		span.setStatus({
 			code: this.#api.SpanStatusCode.ERROR,
-			message: exception.message
+			message: info.message
 		});
 	}
 };
@@ -1193,6 +1202,16 @@ var RetryableLanguageModel = class extends BaseRetryableModel {
 					let capturedWarnings = [];
 					let capturedResponseMetadata = {};
 					/**
+					* Buffer for the leading non-content parts (`stream-start`,
+					* `response-metadata`, `text-start`, `reasoning-start`, …) of this
+					* attempt. While no content has been forwarded the preamble is held
+					* here rather than enqueued, so a pre-content retry can discard it
+					* and the consumer sees exactly one preamble — the one belonging to
+					* the model that actually produced the output. Reset per attempt;
+					* flushed on the first content part or at completion.
+					*/
+					let preambleBuffer = [];
+					/**
 					* Set when a `finish` part triggers a retry decision. Causes the
 					* inner read loop to exit without enqueuing the finish part, and
 					* the outer loop to re-stream against the next model.
@@ -1261,11 +1280,25 @@ var RetryableLanguageModel = class extends BaseRetryableModel {
 								}
 							}
 							/**
-							* Mark that streaming has started once we receive actual content
+							* Mark that streaming has started once we receive actual
+							* content. On the first content part, flush this attempt's
+							* buffered preamble (in order) ahead of the content, then
+							* forward normally from here on.
 							*/
-							if (isStreamContentPart(value)) isStreaming = true;
-							/**
-							* Enqueue the chunk to the consumer of the stream
+							if (isStreamContentPart(value)) {
+								isStreaming = true;
+								for (const buffered of preambleBuffer) controller.enqueue(buffered);
+								preambleBuffer = [];
+								controller.enqueue(value);
+							} else if (!isStreaming)
+ /**
+							* Pre-content part: buffer it so a pre-content retry can
+							* replace it with the next attempt's preamble.
+							*/
+							preambleBuffer.push(value);
+							else
+ /**
+							* Content already flowing: forward directly.
 							*/
 							controller.enqueue(value);
 						}
@@ -1297,7 +1330,13 @@ var RetryableLanguageModel = class extends BaseRetryableModel {
 								currentRetry,
 								recorder
 							});
-							await reader?.cancel();
+							/**
+							* Cancelling a reader whose stream has already errored (e.g.
+							* a mid-stream `controller.error`) rejects with that stored
+							* error. Swallow it: the retry already succeeded and that
+							* rejection must not abort the wrapped stream.
+							*/
+							await reader?.cancel().catch(() => {});
 							result = retriedResult.result;
 							attempts = retriedResult.attempts;
 							finalCallOptions = retriedResult.callOptions;
@@ -1309,6 +1348,13 @@ var RetryableLanguageModel = class extends BaseRetryableModel {
 							outcome: "success",
 							finishReason: streamFinishReason
 						});
+						/**
+						* A stream that completes with no content part still has its
+						* preamble buffered. Flush it so a zero-content completion emits
+						* its `stream-start` (and any metadata/finish) before closing.
+						*/
+						for (const buffered of preambleBuffer) controller.enqueue(buffered);
+						preambleBuffer = [];
 						controller.close();
 						break;
 					} catch (error) {
@@ -1399,9 +1445,13 @@ var RetryableLanguageModel = class extends BaseRetryableModel {
 							recorder
 						});
 						/**
-						* Cancel the previous reader and stream if we are retrying
+						* Cancel the previous reader and stream if we are retrying.
+						* Cancelling a reader whose stream has already errored (e.g. a
+						* mid-stream `controller.error`) rejects with that stored
+						* error. Swallow it: the retry already succeeded and that
+						* rejection must not abort the wrapped stream.
 						*/
-						await reader?.cancel();
+						await reader?.cancel().catch(() => {});
 						result = retriedResult.result;
 						attempts = retriedResult.attempts;
 						finalCallOptions = retriedResult.callOptions;

package/dist/experimental/embedding-model/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRetryable$1 } from "../../create-retryable-model-BdA-OoIc.mjs";
+import { t as createRetryable$1 } from "../../create-retryable-model-Ch2cqC3Z.mjs";
 import "../../error-CaTT-xX8.mjs";
 import { aborted, error, httpStatus, timeout } from "./retryables/index.mjs";
 

package/dist/experimental/embedding-model/retryables/index.d.mts

@@ -1,6 +1,6 @@
 import { k as RetryContext } from "../../../types-ydxC71oc.mjs";
 import { n as Condition, t as StatusPattern } from "../../../error-CoF13EJO.mjs";
-import * as _ai_sdk_provider13 from "@ai-sdk/provider";
+import * as _ai_sdk_provider0 from "@ai-sdk/provider";
 
 //#region src/experimental/embedding-model/retryables/index.d.ts
 /**
@@ -11,10 +11,10 @@ import * as _ai_sdk_provider13 from "@ai-sdk/provider";
  *     from 'ai-retry/experimental/embedding-model/retryables';
  */
 declare const error: {
-    <MODEL extends _ai_sdk_provider13.EmbeddingModelV3 = _ai_sdk_provider13.EmbeddingModelV3, E = unknown>(predicate: (err: E, ctx: RetryContext<MODEL>) => boolean | Promise<boolean>): Condition<MODEL>;
-    isRetryable<MODEL extends _ai_sdk_provider13.EmbeddingModelV3 = _ai_sdk_provider13.EmbeddingModelV3>(flag?: boolean): Condition<MODEL>;
-    statusCode<MODEL extends _ai_sdk_provider13.EmbeddingModelV3 = _ai_sdk_provider13.EmbeddingModelV3>(...patterns: Array<number | RegExp>): Condition<MODEL>;
-    message<MODEL extends _ai_sdk_provider13.EmbeddingModelV3 = _ai_sdk_provider13.EmbeddingModelV3>(...patterns: Array<string | RegExp>): Condition<MODEL>;
-  }, httpStatus: <MODEL extends _ai_sdk_provider13.EmbeddingModelV3 = _ai_sdk_provider13.EmbeddingModelV3>(...patterns: Array<StatusPattern>) => Condition<MODEL>, timeout: <MODEL extends _ai_sdk_provider13.EmbeddingModelV3 = _ai_sdk_provider13.EmbeddingModelV3>() => Condition<MODEL>, aborted: <MODEL extends _ai_sdk_provider13.EmbeddingModelV3 = _ai_sdk_provider13.EmbeddingModelV3>() => Condition<MODEL>;
+    <MODEL extends _ai_sdk_provider0.EmbeddingModelV3 = _ai_sdk_provider0.EmbeddingModelV3, E = unknown>(predicate: (err: E, ctx: RetryContext<MODEL>) => boolean | Promise<boolean>): Condition<MODEL>;
+    isRetryable<MODEL extends _ai_sdk_provider0.EmbeddingModelV3 = _ai_sdk_provider0.EmbeddingModelV3>(flag?: boolean): Condition<MODEL>;
+    statusCode<MODEL extends _ai_sdk_provider0.EmbeddingModelV3 = _ai_sdk_provider0.EmbeddingModelV3>(...patterns: Array<number | RegExp>): Condition<MODEL>;
+    message<MODEL extends _ai_sdk_provider0.EmbeddingModelV3 = _ai_sdk_provider0.EmbeddingModelV3>(...patterns: Array<string | RegExp>): Condition<MODEL>;
+  }, httpStatus: <MODEL extends _ai_sdk_provider0.EmbeddingModelV3 = _ai_sdk_provider0.EmbeddingModelV3>(...patterns: Array<StatusPattern>) => Condition<MODEL>, timeout: <MODEL extends _ai_sdk_provider0.EmbeddingModelV3 = _ai_sdk_provider0.EmbeddingModelV3>() => Condition<MODEL>, aborted: <MODEL extends _ai_sdk_provider0.EmbeddingModelV3 = _ai_sdk_provider0.EmbeddingModelV3>() => Condition<MODEL>;
 //#endregion
 export { aborted, error, httpStatus, timeout };

package/dist/experimental/image-model/index.d.mts

@@ -1,6 +1,6 @@
 import { P as RetryableModelOptions, s as ImageModel } from "../../types-ydxC71oc.mjs";
 import "../../error-CoF13EJO.mjs";
-import { a as noImage, i as timeout, n as error, r as httpStatus, t as aborted } from "../../index-CTbSMr1u.mjs";
+import { a as noImage, i as timeout, n as error, r as httpStatus, t as aborted } from "../../index-D4w-HLk-.mjs";
 
 //#region src/experimental/image-model/index.d.ts
 declare function createRetryable<MODEL extends ImageModel>(options: RetryableModelOptions<MODEL>): ImageModel;

package/dist/experimental/image-model/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRetryable$1 } from "../../create-retryable-model-BdA-OoIc.mjs";
+import { t as createRetryable$1 } from "../../create-retryable-model-Ch2cqC3Z.mjs";
 import "../../error-CaTT-xX8.mjs";
 import { a as noImage, i as timeout, n as error, r as httpStatus, t as aborted } from "../../retryables-CPAbu_M3.mjs";
 

package/dist/experimental/image-model/retryables/index.d.mts

@@ -1,4 +1,4 @@
 import "../../../types-ydxC71oc.mjs";
 import "../../../error-CoF13EJO.mjs";
-import { a as noImage, i as timeout, n as error, r as httpStatus, t as aborted } from "../../../index-CTbSMr1u.mjs";
+import { a as noImage, i as timeout, n as error, r as httpStatus, t as aborted } from "../../../index-D4w-HLk-.mjs";
 export { aborted, error, httpStatus, noImage, timeout };

package/dist/experimental/language-model/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRetryable$1 } from "../../create-retryable-model-BdA-OoIc.mjs";
+import { t as createRetryable$1 } from "../../create-retryable-model-Ch2cqC3Z.mjs";
 import "../../error-CaTT-xX8.mjs";
 import { a as result, i as httpStatus, n as error, o as schemaInvalid, r as finishReason, s as timeout, t as aborted } from "../../retryables-M5l_6w9k.mjs";
 

package/dist/index-D4w-HLk-.d.mts

@@ -0,0 +1,34 @@
+import { k as RetryContext, s as ImageModel } from "./types-ydxC71oc.mjs";
+import { n as Condition, t as StatusPattern } from "./error-CoF13EJO.mjs";
+import * as _ai_sdk_provider13 from "@ai-sdk/provider";
+
+//#region src/experimental/internal/no-image.d.ts
+/**
+ * Match when image generation produced no images
+ * (`NoImageGeneratedError`).
+ *
+ * **Important:** returns a `Condition`, not a `Retryable`. Call
+ * `.switch()` or `.retry()` to plug it into `retries: [...]`.
+ *
+ * @example
+ * noImage().switch({ model: fallback })
+ * noImage().retry({ maxAttempts: 3 })
+ */
+declare function noImage<MODEL extends ImageModel = ImageModel>(): Condition<MODEL>;
+//#endregion
+//#region src/experimental/image-model/retryables/index.d.ts
+/**
+ * Experimental composable conditions bound to `ImageModel`. For use with
+ * `generateImage`.
+ *
+ *   import { error, noImage, ... }
+ *     from 'ai-retry/experimental/image-model/retryables';
+ */
+declare const error: {
+    <MODEL extends _ai_sdk_provider13.ImageModelV3 = _ai_sdk_provider13.ImageModelV3, E = unknown>(predicate: (err: E, ctx: RetryContext<MODEL>) => boolean | Promise<boolean>): Condition<MODEL>;
+    isRetryable<MODEL extends _ai_sdk_provider13.ImageModelV3 = _ai_sdk_provider13.ImageModelV3>(flag?: boolean): Condition<MODEL>;
+    statusCode<MODEL extends _ai_sdk_provider13.ImageModelV3 = _ai_sdk_provider13.ImageModelV3>(...patterns: Array<number | RegExp>): Condition<MODEL>;
+    message<MODEL extends _ai_sdk_provider13.ImageModelV3 = _ai_sdk_provider13.ImageModelV3>(...patterns: Array<string | RegExp>): Condition<MODEL>;
+  }, httpStatus: <MODEL extends _ai_sdk_provider13.ImageModelV3 = _ai_sdk_provider13.ImageModelV3>(...patterns: Array<StatusPattern>) => Condition<MODEL>, timeout: <MODEL extends _ai_sdk_provider13.ImageModelV3 = _ai_sdk_provider13.ImageModelV3>() => Condition<MODEL>, aborted: <MODEL extends _ai_sdk_provider13.ImageModelV3 = _ai_sdk_provider13.ImageModelV3>() => Condition<MODEL>;
+//#endregion
+export { noImage as a, timeout as i, error as n, httpStatus as r, aborted as t };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as getModelKey, t as createRetryable } from "./create-retryable-model-BdA-OoIc.mjs";
+import { n as getModelKey, t as createRetryable } from "./create-retryable-model-Ch2cqC3Z.mjs";
 import { n as isErrorAttempt, s as isResultAttempt } from "./guards-D8UJtxDK.mjs";
 
 export { createRetryable, getModelKey, isErrorAttempt, isResultAttempt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-retry",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Retry and fallback mechanisms for AI SDK",
   "keywords": [
     "ai",

package/dist/index-CTbSMr1u.d.mts

@@ -1,34 +0,0 @@
-import { k as RetryContext, s as ImageModel } from "./types-ydxC71oc.mjs";
-import { n as Condition, t as StatusPattern } from "./error-CoF13EJO.mjs";
-import * as _ai_sdk_provider0 from "@ai-sdk/provider";
-
-//#region src/experimental/internal/no-image.d.ts
-/**
- * Match when image generation produced no images
- * (`NoImageGeneratedError`).
- *
- * **Important:** returns a `Condition`, not a `Retryable`. Call
- * `.switch()` or `.retry()` to plug it into `retries: [...]`.
- *
- * @example
- * noImage().switch({ model: fallback })
- * noImage().retry({ maxAttempts: 3 })
- */
-declare function noImage<MODEL extends ImageModel = ImageModel>(): Condition<MODEL>;
-//#endregion
-//#region src/experimental/image-model/retryables/index.d.ts
-/**
- * Experimental composable conditions bound to `ImageModel`. For use with
- * `generateImage`.
- *
- *   import { error, noImage, ... }
- *     from 'ai-retry/experimental/image-model/retryables';
- */
-declare const error: {
-    <MODEL extends _ai_sdk_provider0.ImageModelV3 = _ai_sdk_provider0.ImageModelV3, E = unknown>(predicate: (err: E, ctx: RetryContext<MODEL>) => boolean | Promise<boolean>): Condition<MODEL>;
-    isRetryable<MODEL extends _ai_sdk_provider0.ImageModelV3 = _ai_sdk_provider0.ImageModelV3>(flag?: boolean): Condition<MODEL>;
-    statusCode<MODEL extends _ai_sdk_provider0.ImageModelV3 = _ai_sdk_provider0.ImageModelV3>(...patterns: Array<number | RegExp>): Condition<MODEL>;
-    message<MODEL extends _ai_sdk_provider0.ImageModelV3 = _ai_sdk_provider0.ImageModelV3>(...patterns: Array<string | RegExp>): Condition<MODEL>;
-  }, httpStatus: <MODEL extends _ai_sdk_provider0.ImageModelV3 = _ai_sdk_provider0.ImageModelV3>(...patterns: Array<StatusPattern>) => Condition<MODEL>, timeout: <MODEL extends _ai_sdk_provider0.ImageModelV3 = _ai_sdk_provider0.ImageModelV3>() => Condition<MODEL>, aborted: <MODEL extends _ai_sdk_provider0.ImageModelV3 = _ai_sdk_provider0.ImageModelV3>() => Condition<MODEL>;
-//#endregion
-export { noImage as a, timeout as i, error as n, httpStatus as r, aborted as t };