npm - workers-ai-provider - Versions diffs - 3.2.1 → 3.3.1 - Mend

workers-ai-provider 3.2.1 → 3.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md +28 -19
package/dist/anthropic.d.mts +1 -1
package/dist/{gateway-delegate-BfaUTwDZ.d.mts → gateway-delegate-D_zkIp5r.d.mts} +90 -15
package/dist/{gateway-provider-1USFWm7c.mjs → gateway-provider-CQU-v2IO.mjs} +562 -170
package/dist/gateway-provider-CQU-v2IO.mjs.map +1 -0
package/dist/gateway-provider.mjs +1 -1
package/dist/google.d.mts +1 -1
package/dist/index.d.mts +1 -1
package/dist/index.mjs +348 -284
package/dist/index.mjs.map +1 -1
package/dist/openai.d.mts +1 -1
package/package.json +5 -4
package/src/gateway-delegate.ts +318 -89
package/src/gateway-provider.ts +10 -34
package/src/gateway-providers.ts +13 -455
package/src/index.ts +64 -20
package/src/resumable-stream.ts +9 -221
package/src/streaming.ts +1 -41
package/src/utils.ts +40 -125
package/src/workersai-chat-language-model.ts +37 -16
package/src/workersai-embedding-model.ts +22 -11
package/src/workersai-error.ts +70 -0
package/src/workersai-image-model.ts +19 -11
package/src/workersai-reranking-model.ts +16 -5
package/src/workersai-speech-model.ts +35 -13
package/src/workersai-transcription-model.ts +15 -4
package/dist/gateway-provider-1USFWm7c.mjs.map +0 -1

package/dist/index.mjs CHANGED Viewed

@@ -1,6 +1,52 @@
-import { a as findProviderBySlug, c as WorkersAIGatewayError, i as detectProviderByUrl, l as _defineProperty, n as createGatewayProvider, o as wireableProviders, r as GATEWAY_PROVIDERS, s as WorkersAIFallbackError, t as createGatewayFetch } from "./gateway-provider-1USFWm7c.mjs";
-import { TooManyEmbeddingValuesForCallError, UnsupportedFunctionalityError } from "@ai-sdk/provider";
+import { C as GatewayDelegateError, S as headersToObject, _ as detectProviderByUrl, a as WORKERS_AI_ERROR_CODE_TO_STATUS, b as asText, c as parseWorkersAIErrorCode, d as isForcedToolChoice, f as normalizeMessagesForBinding$1, g as GATEWAY_PROVIDERS, h as createResumableStream, i as WorkersAIGatewayError, l as SSEDecoder, m as processText, n as createGatewayProvider, o as isAbortError, p as parseLeakedToolCalls$1, r as WorkersAIFallbackError, s as messageOf, t as createGatewayFetch, u as getToolNames, v as findProviderBySlug, w as _defineProperty, x as buildGatewayEntry, y as wireableProviders } from "./gateway-provider-CQU-v2IO.mjs";
+import { APICallError, TooManyEmbeddingValuesForCallError, UnsupportedFunctionalityError } from "@ai-sdk/provider";
 import { generateId } from "ai";
+//#region src/workersai-error.ts
+/**
+* Normalize an error thrown by the Workers AI **binding** (`env.AI.run`) into an
+* `APICallError` so the AI SDK can classify and retry it.
+*
+* Cancellations (`AbortError` / `TimeoutError` / `ResponseAborted`, including
+* `DOMException` aborts) and errors that are already an `APICallError` pass
+* through unchanged. Everything else becomes an
+* `APICallError`; when the internal code maps to a known HTTP status, that
+* `statusCode` is attached and `APICallError` derives `isRetryable` from it.
+* Unrecognized errors get no `statusCode`, so they stay non-retryable (the
+* prior behavior).
+*/
+function normalizeBindingError(error, context) {
+	if (APICallError.isInstance(error) || isAbortError(error)) return error;
+	const code = parseWorkersAIErrorCode(error);
+	const statusCode = code != null ? WORKERS_AI_ERROR_CODE_TO_STATUS[code] : void 0;
+	const message = messageOf(error);
+	return new APICallError({
+		message,
+		url: `workers-ai:binding/run/${context.model}`,
+		requestBodyValues: context.requestBodyValues,
+		statusCode,
+		responseBody: message,
+		cause: error,
+		...code != null ? { data: { workersAIErrorCode: code } } : {}
+	});
+}
+/**
+* Build an `APICallError` from a non-OK Workers AI **REST** response. The HTTP
+* status is authoritative here, so `APICallError` derives `isRetryable` from it
+* directly (429 / 5xx → retryable). Response headers are preserved so the AI
+* SDK can honor `Retry-After`. The message keeps the historical
+* `"Workers AI API error (<status> <statusText>): <body>"` shape.
+*/
+function apiCallErrorFromResponse(response, errorBody, context) {
+	return new APICallError({
+		message: `Workers AI API error (${response.status} ${response.statusText}): ${errorBody}`,
+		url: context.url,
+		requestBodyValues: context.requestBodyValues,
+		statusCode: response.status,
+		responseHeaders: headersToObject(response.headers),
+		responseBody: errorBody
+	});
+}
+//#endregion
 //#region src/utils.ts
 /**
 * Normalize messages before passing to the Workers AI binding.
@@ -9,11 +55,7 @@ import { generateId } from "ai";
 * - `content` must not be null
 */
 function normalizeMessagesForBinding(messages) {
-	return messages.map((msg) => {
-		const normalized = { ...msg };
-		if (normalized.content === null || normalized.content === void 0) normalized.content = "";
-		return normalized;
-	});
+	return normalizeMessagesForBinding$1(messages);
 }
 /**
 * Creates a run method that emulates the Cloudflare Workers AI binding,
@@ -62,7 +104,10 @@ function createRun(config) {
 			} catch {
 				errorBody = "<unable to read response body>";
 			}
-			throw new Error(`Workers AI API error (${response.status} ${response.statusText}): ${errorBody}`);
+			throw apiCallErrorFromResponse(response, errorBody, {
+				url,
+				requestBodyValues: inputs
+			});
 		}
 		if (returnRawResponse) return response;
 		if (inputs.stream === true) {
@@ -85,7 +130,10 @@ function createRun(config) {
 				} catch {
 					errorBody = "<unable to read response body>";
 				}
-				throw new Error(`Workers AI API error (${retryResponse.status} ${retryResponse.statusText}): ${errorBody}`);
+				throw apiCallErrorFromResponse(retryResponse, errorBody, {
+					url,
+					requestBodyValues: inputs
+				});
 			}
 			return (await retryResponse.json()).result;
 		}
@@ -123,7 +171,13 @@ async function createRunBinary(config, model, audioBytes, contentType, signal) {
 		} catch {
 			errorBody = "<unable to read response body>";
 		}
-		throw new Error(`Workers AI API error (${response.status} ${response.statusText}): ${errorBody}`);
+		throw apiCallErrorFromResponse(response, errorBody, {
+			url,
+			requestBodyValues: {
+				contentType,
+				byteLength: audioBytes.byteLength
+			}
+		});
 	}
 	const data = await response.json();
 	return data.result ?? data;
@@ -235,56 +289,20 @@ function processToolCalls(output) {
 	return [];
 }
 /**
-* Was a specific tool forced for this request?
-*
-* True for both `tool_choice: "required"` and the named-function form
-* `{ type: "function", function: { name } }`.
-*/
-function isForcedToolChoice(toolChoice) {
-	if (toolChoice === "required") return true;
-	return typeof toolChoice === "object" && toolChoice !== null && toolChoice.type === "function";
-}
-/**
 * Parse tool calls that a model leaked as JSON text instead of structured
-* `tool_calls`. Shared by the non-streaming salvage and the streaming buffer.
+* `tool_calls`, assigning AI-SDK tool-call ids.
 *
-* Only JSON objects whose `name` is one of `knownToolNames` are recovered;
-* everything else (prose, harmony channel/role leaks like `{"name":"analysis"}`,
-* hallucinated names) is ignored to avoid fabricating bogus calls.
+* The recovery logic (which JSON shapes count as a leaked call) lives in
+* `@cloudflare/gateway-core`; this wrapper only layers the framework id on each
+* neutral result so the existing `LanguageModelV3ToolCall` shape is preserved.
 */
 function parseLeakedToolCalls(text, knownToolNames) {
-	let parsed;
-	try {
-		parsed = JSON.parse(text.trim());
-	} catch {
-		return [];
-	}
-	const candidates = Array.isArray(parsed) ? parsed : [parsed];
-	const salvaged = [];
-	for (const candidate of candidates) {
-		if (typeof candidate !== "object" || candidate === null) continue;
-		const obj = candidate;
-		const name = obj.name;
-		if (typeof name !== "string" || !knownToolNames.has(name)) continue;
-		let args;
-		if ("arguments" in obj) args = obj.arguments;
-		else if ("parameters" in obj) args = obj.parameters;
-		else {
-			const { name: _name, ...rest } = obj;
-			args = rest;
-		}
-		salvaged.push({
-			input: typeof args === "string" ? args : JSON.stringify(args ?? {}),
-			toolCallId: createAISDKToolCallId(void 0),
-			type: "tool-call",
-			toolName: name
-		});
-	}
-	return salvaged;
-}
-/** Collect the requested tool names from mapped tools. */
-function getToolNames(tools) {
-	return new Set((tools ?? []).map((tool) => tool.function?.name).filter((name) => typeof name === "string"));
+	return parseLeakedToolCalls$1(text, knownToolNames).map((call) => ({
+		input: call.input,
+		toolCallId: createAISDKToolCallId(void 0),
+		type: "tool-call",
+		toolName: call.toolName
+	}));
 }
 /**
 * Salvage a tool call that a model leaked into text content instead of the
@@ -320,24 +338,6 @@ function salvageToolCallsFromText(output, context) {
 	const salvaged = parseLeakedToolCalls(text, knownToolNames);
 	return salvaged.length > 0 ? salvaged : null;
 }
-/**
-* Extract text from a Workers AI response, handling multiple response formats:
-* - OpenAI format: { choices: [{ message: { content: "..." } }] }
-* - Native format: { response: "..." }
-* - Structured output quirk: { response: { ... } } (object instead of string)
-* - Structured output quirk: { response: "{ ... }" } (JSON string)
-*/
-function processText(output) {
-	const choiceContent = output.choices?.[0]?.message?.content;
-	if (choiceContent != null && String(choiceContent).length > 0) return String(choiceContent);
-	if ("response" in output) {
-		const response = output.response;
-		if (typeof response === "object" && response !== null) return JSON.stringify(response);
-		if (typeof response === "number") return String(response);
-		if (response === null || response === void 0) return;
-		return String(response);
-	}
-}
 //#endregion
 //#region src/convert-to-workersai-chat-messages.ts
 /**
@@ -945,37 +945,6 @@ function getMappedStream(response, salvageContext) {
 		}
 	}
 }
-/**
-* TransformStream that decodes a raw byte stream into SSE `data:` payloads.
-* Each output chunk is the string content after "data: " (one per SSE event).
-* Handles line buffering for partial chunks.
-*/
-var SSEDecoder = class extends TransformStream {
-	constructor() {
-		let buffer = "";
-		const decoder = new TextDecoder();
-		super({
-			transform(chunk, controller) {
-				buffer += decoder.decode(chunk, { stream: true });
-				const lines = buffer.split("\n");
-				buffer = lines.pop() || "";
-				for (const line of lines) {
-					const trimmed = line.trim();
-					if (!trimmed) continue;
-					if (trimmed.startsWith("data: ")) controller.enqueue(trimmed.slice(6));
-					else if (trimmed.startsWith("data:")) controller.enqueue(trimmed.slice(5));
-				}
-			},
-			flush(controller) {
-				if (buffer.trim()) {
-					const trimmed = buffer.trim();
-					if (trimmed.startsWith("data: ")) controller.enqueue(trimmed.slice(6));
-					else if (trimmed.startsWith("data:")) controller.enqueue(trimmed.slice(5));
-				}
-			}
-		});
-	}
-};
 //#endregion
 //#region src/aisearch-chat-language-model.ts
 var AISearchChatLanguageModel = class {
@@ -1089,12 +1058,21 @@ var WorkersAIEmbeddingModel = class {
 			values
 		});
 		const { gateway, maxEmbeddingsPerCall: _maxEmbeddingsPerCall, supportsParallelCalls: _supportsParallelCalls, ...passthroughOptions } = this.settings;
-		return {
-			embeddings: (await this.config.binding.run(this.modelId, { text: values }, {
+		let response;
+		try {
+			response = await this.config.binding.run(this.modelId, { text: values }, {
 				gateway: this.config.gateway ?? gateway,
 				signal: abortSignal,
 				...passthroughOptions
-			})).data,
+			});
+		} catch (error) {
+			throw normalizeBindingError(error, {
+				model: this.modelId,
+				requestBodyValues: { text: values }
+			});
+		}
+		return {
+			embeddings: response.data,
 			warnings: []
 		};
 	}
@@ -1254,10 +1232,18 @@ var WorkersAIChatLanguageModel = class {
 		const { messages } = convertToWorkersAIChatMessages(options.prompt);
 		const inputs = this.buildRunInputs(args, messages, { providerOptions: options.providerOptions });
 		const runOptions = this.getRunOptions();
-		const output = await this.config.binding.run(args.model, inputs, {
-			...runOptions,
-			signal: options.abortSignal
-		});
+		let output;
+		try {
+			output = await this.config.binding.run(args.model, inputs, {
+				...runOptions,
+				signal: options.abortSignal
+			});
+		} catch (error) {
+			throw normalizeBindingError(error, {
+				model: args.model,
+				requestBodyValues: inputs
+			});
+		}
 		if (output instanceof ReadableStream) throw new Error("Unexpected streaming response from non-streaming request. Check that `stream: true` was not passed.");
 		const outputRecord = output;
 		const { reasoningContent, text, toolCalls, finishReason } = this.extractContent(outputRecord, args, warnings);
@@ -1286,10 +1272,18 @@ var WorkersAIChatLanguageModel = class {
 			providerOptions: options.providerOptions
 		});
 		const runOptions = this.getRunOptions();
-		const response = await this.config.binding.run(args.model, inputs, {
-			...runOptions,
-			signal: options.abortSignal
-		});
+		let response;
+		try {
+			response = await this.config.binding.run(args.model, inputs, {
+				...runOptions,
+				signal: options.abortSignal
+			});
+		} catch (error) {
+			throw normalizeBindingError(error, {
+				model: args.model,
+				requestBodyValues: inputs
+			});
+		}
 		if (response instanceof ReadableStream) return { stream: prependStreamStart(getMappedStream(response, {
 			tools: args.tools,
 			toolChoice: args.tool_choice
@@ -1369,15 +1363,25 @@ var WorkersAIImageModel = class {
 			type: "unsupported"
 		});
 		const generateImage = async () => {
-			return toUint8Array$1(await this.config.binding.run(this.modelId, {
+			const inputs = {
 				height,
 				prompt: prompt ?? "",
 				seed,
 				width
-			}, {
-				gateway: this.config.gateway,
-				signal: abortSignal
-			}));
+			};
+			let output;
+			try {
+				output = await this.config.binding.run(this.modelId, inputs, {
+					gateway: this.config.gateway,
+					signal: abortSignal
+				});
+			} catch (error) {
+				throw normalizeBindingError(error, {
+					model: this.modelId,
+					requestBodyValues: inputs
+				});
+			}
+			return toUint8Array$1(output);
 		};
 		return {
 			images: await Promise.all(Array.from({ length: n }, () => generateImage())),
@@ -1466,8 +1470,15 @@ var WorkersAITranscriptionModel = class {
 		const audioBytes = typeof audio === "string" ? Uint8Array.from(atob(audio), (c) => c.charCodeAt(0)) : audio;
 		const isNova3 = this.modelId === "@cf/deepgram/nova-3";
 		let rawResult;
-		if (isNova3) rawResult = await this.runNova3(audioBytes, mediaType, abortSignal);
-		else rawResult = await this.runWhisper(audioBytes, abortSignal);
+		try {
+			if (isNova3) rawResult = await this.runNova3(audioBytes, mediaType, abortSignal);
+			else rawResult = await this.runWhisper(audioBytes, abortSignal);
+		} catch (error) {
+			throw normalizeBindingError(error, {
+				model: this.modelId,
+				requestBodyValues: { mediaType }
+			});
+		}
 		const result = rawResult;
 		if (isNova3) return this.normalizeNova3Response(result, warnings);
 		return this.normalizeWhisperResponse(result, warnings);
@@ -1581,12 +1592,28 @@ var WorkersAISpeechModel = class {
 		const inputs = { text };
 		if (voice) inputs.voice = voice;
 		if (speed != null) inputs.speed = speed;
-		return {
-			audio: await toUint8Array(await this.config.binding.run(this.modelId, inputs, {
+		let result;
+		try {
+			result = await this.config.binding.run(this.modelId, inputs, {
 				gateway: this.config.gateway,
 				signal: abortSignal,
 				returnRawResponse: true
-			})),
+			});
+		} catch (error) {
+			throw normalizeBindingError(error, {
+				model: this.modelId,
+				requestBodyValues: inputs
+			});
+		}
+		if (result instanceof Response && !result.ok) {
+			const errorBody = await result.text().catch(() => "<unable to read response body>");
+			throw apiCallErrorFromResponse(result, errorBody, {
+				url: `workers-ai:run/${this.modelId}`,
+				requestBodyValues: inputs
+			});
+		}
+		return {
+			audio: await toUint8Array(result),
 			warnings,
 			response: {
 				timestamp: /* @__PURE__ */ new Date(),
@@ -1661,11 +1688,20 @@ var WorkersAIRerankingModel = class {
 			contexts: documentsToContexts(documents, warnings)
 		};
 		if (topN != null) inputs.top_k = topN;
-		return {
-			ranking: ((await this.config.binding.run(this.modelId, inputs, {
+		let result;
+		try {
+			result = await this.config.binding.run(this.modelId, inputs, {
 				gateway: this.config.gateway,
 				signal: abortSignal
-			})).response ?? []).map((item) => ({
+			});
+		} catch (error) {
+			throw normalizeBindingError(error, {
+				model: this.modelId,
+				requestBodyValues: inputs
+			});
+		}
+		return {
+			ranking: (result.response ?? []).map((item) => ({
 				index: item.id ?? 0,
 				relevanceScore: item.score ?? 0
 			})).sort((a, b) => b.relevanceScore - a.relevanceScore),
@@ -1750,110 +1786,6 @@ function createClientFallbackModel(legs) {
 	};
 }
 //#endregion
-//#region src/resumable-stream.ts
-function concat(a, b) {
-	const out = new Uint8Array(new ArrayBuffer(a.length + b.length));
-	out.set(a, 0);
-	out.set(b, a.length);
-	return out;
-}
-/** Index just past the last `\n\n` in `buf`, or -1 if there is no complete event. */
-function lastEventBoundary(buf) {
-	for (let i = buf.length - 2; i >= 0; i--) if (buf[i] === 10 && buf[i + 1] === 10) return i + 2;
-	return -1;
-}
-/** Count of `\n\n` terminators (= complete SSE events) in `buf`. */
-function countEvents(buf) {
-	let n = 0;
-	for (let i = 0; i + 1 < buf.length; i++) if (buf[i] === 10 && buf[i + 1] === 10) {
-		n++;
-		i++;
-	}
-	return n;
-}
-function resumeUrl(gateway, runId, from) {
-	return `https://workers-binding.ai/ai-gateway/gateways/${gateway}/run/${runId}/resume?from=${from}`;
-}
-function createResumableStream(options) {
-	const { binding, gateway, runId } = options;
-	const maxReconnects = options.maxReconnects ?? 5;
-	const onExpired = options.onResumeExpired ?? "error";
-	let emittedEvents = options.fromEvent ?? 0;
-	let pending = new Uint8Array(/* @__PURE__ */ new ArrayBuffer(0));
-	let reconnects = 0;
-	async function fetchResume(controller) {
-		let res;
-		try {
-			res = await binding.fetch(resumeUrl(gateway, runId, emittedEvents), { method: "GET" });
-		} catch (fetchErr) {
-			controller.error(new GatewayDelegateError("dispatch", `Resume request threw at event ${emittedEvents}.`, fetchErr));
-			return null;
-		}
-		if (res.status === 404) {
-			if (onExpired === "accept-partial") {
-				controller.close();
-				return null;
-			}
-			controller.error(new GatewayDelegateError("resume-expired", `Resume buffer expired (404) at event ${emittedEvents}. The gateway buffer TTL (~5.5 min) elapsed; fall back to continuation or regeneration.`));
-			return null;
-		}
-		if (!res.ok || !res.body) {
-			controller.error(new GatewayDelegateError("dispatch", `Resume failed (${res.status}) at event ${emittedEvents}.`));
-			return null;
-		}
-		return res.body;
-	}
-	return new ReadableStream({ async start(controller) {
-		let current;
-		if (options.initial) current = options.initial;
-		else {
-			const body = await fetchResume(controller);
-			if (!body) return;
-			current = body;
-		}
-		for (;;) {
-			const reader = current.getReader();
-			try {
-				for (;;) {
-					const { done, value } = await reader.read();
-					if (done) {
-						if (pending.length > 0) {
-							controller.enqueue(pending);
-							pending = new Uint8Array(/* @__PURE__ */ new ArrayBuffer(0));
-						}
-						controller.close();
-						return;
-					}
-					if (!value || value.length === 0) continue;
-					pending = concat(pending, value);
-					const boundary = lastEventBoundary(pending);
-					if (boundary > 0) {
-						const complete = pending.slice(0, boundary);
-						controller.enqueue(complete);
-						emittedEvents += countEvents(complete);
-						options.onProgress?.(emittedEvents);
-						pending = pending.slice(boundary);
-					}
-				}
-			} catch (err) {
-				try {
-					reader.releaseLock();
-				} catch {}
-				if (reconnects >= maxReconnects) {
-					controller.error(new GatewayDelegateError("resume-expired", `Exceeded ${maxReconnects} reconnect attempts at event ${emittedEvents}.`, err));
-					return;
-				}
-				pending = new Uint8Array(/* @__PURE__ */ new ArrayBuffer(0));
-				reconnects++;
-				options.onReconnect?.(emittedEvents, reconnects);
-				const body = await fetchResume(controller);
-				if (!body) return;
-				current = body;
-			}
-		}
-	} });
-}
-//#endregion
 //#region src/gateway-delegate.ts
 /**
 * Parse a `vendor/model` slug. The first segment is the resolver key (which
@@ -1893,7 +1825,7 @@ function selectTransport(opts, resumeExplicitlyTrue, runCatalog = true, gatewayA
 	const wantsCaching = opts.cacheTtl !== void 0 || opts.skipCache === true;
 	const gatewayOnly = wantsServerFallback || wantsCaching;
 	const feature = wantsServerFallback ? "fallback.mode:\"server\"" : "caching (cacheTtl/skipCache)";
-	if (runCatalog && !gatewayAvailable && (opts.transport === "gateway" || gatewayOnly)) throw new GatewayDelegateError("config", `${opts.transport === "gateway" ? "transport:\"gateway\"" : feature} is unavailable: this provider is on the unified run catalog but is not a native gateway provider, so it has no gateway path (no caching, server-side fallback, or transport:"gateway"). Use the default run path, or fallback.mode:"client".`);
+	if (runCatalog && !gatewayAvailable && (opts.transport === "gateway" || opts.byok || gatewayOnly)) throw new GatewayDelegateError("config", `${opts.transport === "gateway" ? "transport:\"gateway\"" : opts.byok ? "byok" : feature} is unavailable: this provider is on the unified run catalog but is not a native gateway provider, so it has no gateway path (no caching, server-side fallback, BYOK, or transport:"gateway"). Use the default run path, or fallback.mode:"client".`);
 	if (!runCatalog) {
 		if (opts.transport === "run") throw new GatewayDelegateError("config", "transport:\"run\" is unavailable: this provider is not on the unified-billing run catalog, so it can only be reached through the gateway path (BYOK).");
 		if (resumeExplicitlyTrue) throw new GatewayDelegateError("config", "resume:true is unavailable: this provider is not on the resumable run catalog (cf-aig-run-id requires the unified-billing run path).");
@@ -1903,6 +1835,15 @@ function selectTransport(opts, resumeExplicitlyTrue, runCatalog = true, gatewayA
 			warnings
 		};
 	}
+	if (opts.byok) {
+		if (opts.transport === "run") throw new GatewayDelegateError("config", "transport:\"run\" cannot forward a BYOK key — BYOK is a gateway-path feature. Drop transport:\"run\" (or set transport:\"gateway\").");
+		if (resumeExplicitlyTrue) throw new GatewayDelegateError("config", "byok cannot provide resume — cf-aig-run-id is only on the unified-billing run path.");
+		return {
+			transport: "gateway",
+			resumeEnabled: false,
+			warnings
+		};
+	}
 	if (opts.transport === "run" && gatewayOnly) throw new GatewayDelegateError("config", `transport:"run" cannot satisfy ${feature}: those features are only available on the gateway path. Use the gateway transport, or fallback.mode:"client".`);
 	if (opts.transport === "gateway" && resumeExplicitlyTrue) throw new GatewayDelegateError("config", "transport:\"gateway\" cannot provide resume — cf-aig-run-id is only on the run path.");
 	if (gatewayOnly) {
@@ -1921,31 +1862,6 @@ function selectTransport(opts, resumeExplicitlyTrue, runCatalog = true, gatewayA
 		warnings
 	};
 }
-var GatewayDelegateError = class extends Error {
-	constructor(kind, message, cause) {
-		super(message);
-		_defineProperty(this, "kind", void 0);
-		_defineProperty(this, "cause", void 0);
-		this.name = "GatewayDelegateError";
-		this.kind = kind;
-		this.cause = cause;
-	}
-};
-const STRIP_HEADERS_BASE = new Set(["content-length", "host"]);
-function asText(body) {
-	if (typeof body === "string") return body;
-	if (body instanceof Uint8Array) return new TextDecoder().decode(body);
-	if (body instanceof ArrayBuffer) return new TextDecoder().decode(body);
-	return "{}";
-}
-function headersToObject(h) {
-	const out = {};
-	if (!h) return out;
-	if (h instanceof Headers) for (const [k, v] of h) out[k] = v;
-	else if (Array.isArray(h)) for (const [k, v] of h) out[k] = v;
-	else Object.assign(out, h);
-	return out;
-}
 function normalizeGateway(gateway) {
 	if (!gateway) throw new GatewayDelegateError("config", "A gateway is required for the delegate (resume needs a gateway). Pass `gateway: \"<gateway-id>\"` to createGatewayDelegate or per call.");
 	if (typeof gateway === "string") return {
@@ -2005,6 +1921,49 @@ function createGatewayDelegate(config) {
 				};
 			}));
 		}
+		if (options.fallback?.mode === "server") {
+			const resolved = [slug, ...options.fallback.models].map((s) => {
+				const parsed = parseSlug(s);
+				return {
+					slug: s,
+					modelId: parsed.modelId,
+					info: resolveProvider(s, parsed)
+				};
+			});
+			if (resolved.some((r) => r.info.gatewayProviderId !== resolved[0].info.gatewayProviderId)) {
+				const resumeExplicitlyTrue = options.resume === true;
+				const effectiveOptions = {
+					...options,
+					resume: options.resume ?? defaultResume,
+					onResumeExpired: options.onResumeExpired ?? config.onResumeExpired
+				};
+				const primaryInfo = resolved[0].info;
+				const selection = selectTransport(effectiveOptions, resumeExplicitlyTrue, primaryInfo.runCatalog, primaryInfo.gatewayPath !== false);
+				for (const w of selection.warnings) console.warn(w);
+				const { id: gatewayId, options: gatewayOptions } = normalizeGateway(options.gateway ?? config.gateway);
+				const legs = resolved.map((r) => {
+					if (r.info.gatewayPath === false) throw new GatewayDelegateError("config", `Server-side fallback cannot use "${r.slug}": it is on the unified run catalog but has no native gateway path.`);
+					const wire = r.info.wireFormat;
+					const plugin = plugins.get(wire);
+					if (!plugin) throw new GatewayDelegateError("config", `No provider plugin for wire format "${wire}" (needed by "${r.slug}" for server-side fallback). Registered: ${[...plugins.keys()].join(", ") || "<none>"}.`);
+					return {
+						slug: r.slug,
+						modelId: r.modelId,
+						info: r.info,
+						plugin
+					};
+				});
+				return makeServerFallbackModel({
+					binding: config.binding,
+					gatewayId,
+					gatewayOptions,
+					legs,
+					opts: effectiveOptions,
+					selection,
+					callOptions: options
+				});
+			}
+		}
 		return buildOne(slug, options).model;
 	};
 }
@@ -2029,9 +1988,27 @@ function mergeMetadata(base, override) {
 		...override
 	};
 }
-/** JSON-encode metadata for the `cf-aig-metadata` header (bigint → string). */
-function serializeMetadata(metadata) {
-	return JSON.stringify(metadata, (_k, v) => typeof v === "bigint" ? v.toString() : v);
+/**
+* Build the `cf-aig-*` request controls for a gateway-path entry. First-class
+* call options (`cacheTtl`, `skipCache`, `collectLog`, `metadata`, `byokAlias`,
+* `zdr`) are layered over the binding-style gateway options (`cacheKey`,
+* `eventId`, `requestTimeoutMs`, `retries`) so the gateway path reaches parity
+* with the run path, which forwards the whole `GatewayOptions` to `binding.run`.
+*/
+function buildGatewayControls(gatewayOptions, opts) {
+	const metadata = mergeMetadata(gatewayOptions.metadata, opts.metadata);
+	return {
+		cacheTtl: opts.cacheTtl,
+		skipCache: opts.skipCache,
+		...gatewayOptions.cacheKey !== void 0 ? { cacheKey: gatewayOptions.cacheKey } : {},
+		...metadata ? { metadata } : {},
+		...opts.collectLog !== void 0 ? { collectLog: opts.collectLog } : {},
+		...gatewayOptions.eventId !== void 0 ? { eventId: gatewayOptions.eventId } : {},
+		...gatewayOptions.requestTimeoutMs !== void 0 ? { requestTimeoutMs: gatewayOptions.requestTimeoutMs } : {},
+		...gatewayOptions.retries ? { retries: gatewayOptions.retries } : {},
+		...opts.byokAlias !== void 0 ? { byokAlias: opts.byokAlias } : {},
+		...opts.zdr !== void 0 ? { zdr: opts.zdr } : {}
+	};
 }
 function makeRunFetch(binding, slug, gatewayOptions, opts, selection, callOptions) {
 	return (async (_input, init) => {
@@ -2041,10 +2018,12 @@ function makeRunFetch(binding, slug, gatewayOptions, opts, selection, callOption
 		const mergedMeta = mergeMetadata(gatewayOptions.metadata, opts.metadata);
 		if (mergedMeta) mergedGateway.metadata = mergedMeta;
 		if (opts.collectLog !== void 0) mergedGateway.collectLog = opts.collectLog;
+		const extraHeaders = { ...opts.extraHeaders };
+		if (opts.zdr !== void 0) extraHeaders["cf-aig-zdr"] = String(opts.zdr);
 		const runOptions = {
 			gateway: mergedGateway,
 			returnRawResponse: true,
-			...opts.extraHeaders ? { extraHeaders: opts.extraHeaders } : {},
+			...Object.keys(extraHeaders).length > 0 ? { extraHeaders } : {},
 			...init?.signal ? { signal: init.signal } : {}
 		};
 		const resp = await binding.run(slug, body, runOptions);
@@ -2068,31 +2047,24 @@ function makeRunFetch(binding, slug, gatewayOptions, opts, selection, callOption
 	});
 }
 function makeGatewayFetch(binding, info, gatewayId, gatewayOptions, opts, selection, callOptions) {
-	const strip = new Set(STRIP_HEADERS_BASE);
-	if (!opts.byok) for (const h of info.authHeaders) strip.add(h.toLowerCase());
 	return (async (input, init) => {
 		const rawUrl = typeof input === "string" ? input : input.toString();
 		const endpoint = info.transformEndpoint ? info.transformEndpoint(rawUrl) : new URL(rawUrl).pathname.replace(/^\//, "") + (new URL(rawUrl).search || "");
 		const body = JSON.parse(asText(init?.body));
-		const headers = {};
-		for (const [k, v] of Object.entries(headersToObject(init?.headers))) if (!strip.has(k.toLowerCase())) headers[k] = v;
-		if (opts.extraHeaders) Object.assign(headers, opts.extraHeaders);
-		if (opts.cacheTtl !== void 0) headers["cf-aig-cache-ttl"] = String(opts.cacheTtl);
-		if (opts.skipCache) headers["cf-aig-skip-cache"] = "true";
-		const metadata = mergeMetadata(gatewayOptions.metadata, opts.metadata);
-		if (metadata) headers["cf-aig-metadata"] = serializeMetadata(metadata);
-		if (opts.collectLog !== void 0) headers["cf-aig-collect-log"] = String(opts.collectLog);
-		const primary = {
-			provider: info.gatewayProviderId,
+		const primary = buildGatewayEntry({
+			providerId: info.gatewayProviderId,
 			endpoint,
-			headers,
-			query: body
-		};
+			initHeaders: init?.headers,
+			body,
+			...opts.byok ? {} : { stripAuthHeaders: info.authHeaders },
+			...opts.extraHeaders ? { extraHeaders: opts.extraHeaders } : {},
+			cache: buildGatewayControls(gatewayOptions, opts)
+		});
 		const entries = [primary];
 		if (opts.fallback?.mode === "server") for (const fb of opts.fallback.models) {
 			const fbParsed = parseSlug(fb);
 			const fbInfo = resolveProvider(fb, fbParsed);
-			if (fbInfo.gatewayProviderId !== info.gatewayProviderId) throw new GatewayDelegateError("config", `Cross-vendor server-side fallback (${info.gatewayProviderId} → ${fbInfo.gatewayProviderId}) is not supported yet. Use fallback.mode:"client", or same-vendor fallback models.`);
+			if (fbInfo.gatewayProviderId !== info.gatewayProviderId) throw new GatewayDelegateError("dispatch", `Internal: cross-vendor server fallback (${info.gatewayProviderId} → ${fbInfo.gatewayProviderId}) reached the same-vendor gateway fetch. This should have been routed through makeServerFallbackModel.`);
 			entries.push({
 				...primary,
 				query: {
@@ -2109,6 +2081,92 @@ function makeGatewayFetch(binding, info, gatewayId, gatewayOptions, opts, select
 		return resp;
 	});
 }
+/** Sentinel thrown by the capture fetch to stop a leg before it hits the network. */
+var ServerFallbackCaptureStop = class extends Error {};
+/**
+* Cross-vendor server-side fallback via the gateway universal endpoint.
+*
+* Unlike same-vendor fallback (which just swaps `model` in one body), legs here
+* are DIFFERENT providers with possibly different wire formats, so each leg's own
+* `@ai-sdk` model must shape its native request. Mirrors ai-gateway-provider's
+* `processModelRequest`: run each leg's builder with a capture `fetch` that
+* sentinel-throws before the network, reshape each captured request into a
+* `{ provider, endpoint, headers, query }` entry, dispatch all N as one
+* `env.AI.gateway(id).run([...])`, then read `cf-aig-step` to find the leg the
+* gateway actually served and feed the raw response back into that leg's model.
+*/
+function makeServerFallbackModel(params) {
+	const { binding, gatewayId, gatewayOptions, legs, opts, selection, callOptions } = params;
+	const first = legs[0];
+	const refModel = first.plugin.create({
+		modelId: first.modelId,
+		fetch: (async () => {
+			throw new ServerFallbackCaptureStop();
+		}),
+		...first.info.baseURL ? { baseURL: first.info.baseURL } : {}
+	});
+	const cache = buildGatewayControls(gatewayOptions, opts);
+	const dispatch = async (method, options) => {
+		const entries = [];
+		for (const leg of legs) {
+			let captured;
+			const captureFetch = (async (input, init) => {
+				captured = {
+					url: typeof input === "string" ? input : input.toString(),
+					init
+				};
+				throw new ServerFallbackCaptureStop();
+			});
+			const model = leg.plugin.create({
+				modelId: leg.modelId,
+				fetch: captureFetch,
+				...leg.info.baseURL ? { baseURL: leg.info.baseURL } : {}
+			});
+			try {
+				await model[method](options);
+			} catch (e) {
+				if (!(e instanceof ServerFallbackCaptureStop)) throw e;
+			}
+			if (!captured) throw new GatewayDelegateError("dispatch", `Server-side fallback leg "${leg.slug}" produced no request to dispatch.`);
+			const url = captured.url;
+			const endpoint = leg.info.transformEndpoint ? leg.info.transformEndpoint(url) : new URL(url).pathname.replace(/^\//, "") + (new URL(url).search || "");
+			const body = JSON.parse(asText(captured.init?.body));
+			entries.push(buildGatewayEntry({
+				providerId: leg.info.gatewayProviderId,
+				endpoint,
+				initHeaders: captured.init?.headers,
+				body,
+				...opts.byok ? {} : { stripAuthHeaders: leg.info.authHeaders },
+				...opts.extraHeaders ? { extraHeaders: opts.extraHeaders } : {},
+				cache
+			}));
+		}
+		const gw = binding.gateway(gatewayId);
+		const abortSignal = options.abortSignal;
+		const runOptions = {};
+		if (abortSignal) runOptions.signal = abortSignal;
+		const resp = await gw.run(entries, runOptions);
+		fireDispatch(resp, selection, callOptions);
+		const winner = legs[Number.parseInt(resp.headers.get("cf-aig-step") ?? "0", 10)] ?? first;
+		return winner.plugin.create({
+			modelId: winner.modelId,
+			fetch: (async () => resp),
+			...winner.info.baseURL ? { baseURL: winner.info.baseURL } : {}
+		})[method](options);
+	};
+	return {
+		specificationVersion: "v3",
+		provider: refModel.provider,
+		modelId: refModel.modelId,
+		supportedUrls: refModel.supportedUrls,
+		doGenerate(options) {
+			return dispatch("doGenerate", options);
+		},
+		doStream(options) {
+			return dispatch("doStream", options);
+		}
+	};
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -2140,8 +2198,11 @@ function createWorkersAI(options) {
 		isBinding
 	});
 	const toGatewayOptions = (gateway) => typeof gateway === "string" ? { id: gateway } : gateway;
-	const createDynamicRouteModel = (modelId, settings = {}) => {
-		if (settings.fallback || settings.transport === "gateway" || settings.resume === true || settings.onProgress || settings.onResumeExpired || settings.byok) throw new Error(`"${modelId}" is an AI Gateway dynamic route. Dynamic routes use AI.run with OpenAI-compatible chat-completions wire format; fallback, gateway transport, resume, BYOK, and resume callbacks must be configured on the dynamic route or gateway instead of per call.`);
+	const createRunPathModel = (modelId, settings = {}, kind) => {
+		if (settings.fallback || settings.transport === "gateway" || settings.resume === true || settings.onProgress || settings.onResumeExpired || settings.byok) {
+			const subject = kind === "dynamic" ? `"${modelId}" is an AI Gateway dynamic route` : `"${modelId}" routes through the bare unified-billing run path because no \`providers\` are configured`;
+			throw new Error(`${subject}. It uses AI.run with OpenAI-compatible chat-completions wire format; fallback, gateway transport, resume, BYOK, and resume callbacks are gateway-delegate features — configure provider plugins to use them (createWorkersAI({ binding: env.AI, providers: [openai] })), and for dynamic routes set caching/fallback on the route or gateway instead of per call.`);
+		}
 		const gateway = { ...toGatewayOptions(settings.gateway) ?? options.gateway ?? { id: DEFAULT_GATEWAY_ID } };
 		if (settings.metadata) gateway.metadata = {
 			...gateway.metadata ?? {},
@@ -2167,7 +2228,7 @@ function createWorkersAI(options) {
 		delete chatSettings.byok;
 		const plugin = options.providers?.find((p) => p.wireFormat === DYNAMIC_ROUTE_WIRE_FORMAT);
 		if (!plugin) {
-			if (options.providers?.length) throw new Error(`"${modelId}" is an AI Gateway dynamic route. Dynamic routes return OpenAI-compatible chat-completions wire format on the AI.run path, so configure the OpenAI provider plugin: import { openai } from "workers-ai-provider/openai"; createWorkersAI({ binding: env.AI, providers: [openai] }).`);
+			if (kind === "dynamic" && options.providers?.length) throw new Error(`"${modelId}" is an AI Gateway dynamic route. Dynamic routes return OpenAI-compatible chat-completions wire format on the AI.run path, so configure the OpenAI provider plugin: import { openai } from "workers-ai-provider/openai"; createWorkersAI({ binding: env.AI, providers: [openai] }).`);
 			return createChatModel(modelId, chatSettings);
 		}
 		const fetchImpl = (async (_input, init) => {
@@ -2214,8 +2275,11 @@ A gateway defaults to "default" but can be set via \`gateway\`. Otherwise use a
 	};
 	const isGatewaySlug = (id) => typeof id === "string" && !id.startsWith("@") && !id.startsWith("dynamic/") && id.includes("/");
 	const buildChat = (modelId, settings) => {
-		if (typeof modelId === "string" && modelId.startsWith("dynamic/")) return createDynamicRouteModel(modelId, settings);
-		if (isGatewaySlug(modelId)) return getDelegate(modelId)(modelId, settings);
+		if (typeof modelId === "string" && modelId.startsWith("dynamic/")) return createRunPathModel(modelId, settings, "dynamic");
+		if (isGatewaySlug(modelId)) {
+			if (!options.providers?.length) return createRunPathModel(modelId, settings, "catalog");
+			return getDelegate(modelId)(modelId, settings);
+		}
 		return createChatModel(modelId, settings);
 	};
 	const createImageModel = (modelId, settings = {}) => new WorkersAIImageModel(modelId, settings, {