@absolutejs/ai 0.6.4 → 0.6.6

package/dist/ai/index.js

@@ -266,16 +266,191 @@ var toolResultBlock = (toolUseId, output, content = toolOutputText(output)) => {
   return images ? { content, images, tool_use_id: toolUseId, type: "tool_result" } : { content, tool_use_id: toolUseId, type: "tool_result" };
 };
 
+// src/ai/errors/providerError.ts
+var PROVIDER_STATUS_PAGES = {
+  anthropic: "https://status.claude.com",
+  gemini: "https://status.cloud.google.com",
+  google: "https://status.cloud.google.com",
+  openai: "https://status.openai.com",
+  openrouter: "https://status.openrouter.ai"
+};
+var RETRYABLE_STATUSES = new Set([
+  408,
+  409,
+  425,
+  429,
+  500,
+  502,
+  503,
+  504,
+  529
+]);
+var CONNECTION_ERROR_PATTERNS = [
+  "econnreset",
+  "econnrefused",
+  "etimedout",
+  "enotfound",
+  "eai_again",
+  "socket hang up",
+  "fetch failed",
+  "network",
+  "terminated",
+  "timed out",
+  "timeout",
+  "and not retryable",
+  "no response body"
+];
+var isAbortError = (err) => err instanceof Error && (err.name === "AbortError" || /\babort(ed)?\b/i.test(err.message));
+var providerStatusPage = (provider) => PROVIDER_STATUS_PAGES[provider] ?? null;
+var BILLING_ERROR_TYPES = new Set([
+  "credit_balance_exhausted",
+  "insufficient_quota",
+  "billing_hard_limit_reached",
+  "billing_not_active",
+  "insufficient_credits"
+]);
+
+class ProviderError extends Error {
+  provider;
+  status;
+  type;
+  retryable;
+  billingUnavailable;
+  notSent;
+  metadata;
+  statusPageUrl;
+  constructor(init) {
+    super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+    this.name = "ProviderError";
+    this.provider = init.provider;
+    this.status = init.status ?? null;
+    this.type = init.type ?? (typeof init.metadata?.code === "string" ? init.metadata.code : typeof init.metadata?.type === "string" ? init.metadata.type : null);
+    this.billingUnavailable = BILLING_ERROR_TYPES.has(this.type ?? "") || init.status === 402 || init.provider === "anthropic" && init.status === 400 && /credit balance is too low/i.test(String(init.metadata?.message ?? init.message));
+    this.notSent = init.notSent === true;
+    this.retryable = !this.billingUnavailable && init.retryable;
+    this.metadata = init.metadata;
+    this.statusPageUrl = providerStatusPage(init.provider);
+  }
+  static fromResponse(provider, status, body, type) {
+    let metadata;
+    try {
+      const parsed = JSON.parse(body);
+      const details = parsed?.error ?? parsed;
+      if (details && typeof details === "object" && !Array.isArray(details))
+        metadata = details;
+    } catch {}
+    return new ProviderError({
+      metadata,
+      message: `${capitalize(provider)} API error ${status}: ${body}`,
+      provider,
+      retryable: RETRYABLE_STATUSES.has(status),
+      status,
+      type: type ?? null
+    });
+  }
+  static from(err, provider) {
+    if (err instanceof ProviderError)
+      return err;
+    if (isProviderError(err))
+      return new ProviderError({
+        provider: err.provider,
+        message: err.message,
+        status: err.status,
+        type: err.type,
+        retryable: err.retryable,
+        notSent: err.notSent,
+        metadata: err.metadata,
+        cause: err
+      });
+    if (isAbortError(err))
+      throw err;
+    const rawMessage = err instanceof Error ? err.message : String(err ?? "");
+    const lower = rawMessage.toLowerCase();
+    const statusMatch = lower.match(/api error\s+(\d{3})/);
+    const status = statusMatch ? Number(statusMatch[1]) : null;
+    const retryable = status !== null && RETRYABLE_STATUSES.has(status) || status === null && CONNECTION_ERROR_PATTERNS.some((pattern) => lower.includes(pattern));
+    return new ProviderError({
+      cause: err,
+      message: rawMessage || `${capitalize(provider)} request failed`,
+      provider,
+      retryable,
+      status
+    });
+  }
+}
+var capitalize = (value) => value.charAt(0).toUpperCase() + value.slice(1);
+var isProviderError = (error) => error instanceof Error && error.name === "ProviderError" && ("provider" in error) && typeof error.provider === "string" && ("status" in error) && (error.status === null || typeof error.status === "number") && ("retryable" in error) && typeof error.retryable === "boolean" && ("billingUnavailable" in error) && typeof error.billingUnavailable === "boolean" && ("notSent" in error) && typeof error.notSent === "boolean";
+
+// src/ai/providerFallback.ts
+var providerFallbackModels = (model, recovery) => [
+  ...new Set([
+    model,
+    ...recovery ? typeof recovery.models === "function" ? recovery.models(model) : recovery.models : []
+  ])
+];
+var isAIProviderFailure = (error) => {
+  if (isProviderError(error))
+    return error.billingUnavailable || error.retryable || error.notSent || error.status !== null && [400, 401, 403, 404, 413, 422].includes(error.status);
+  return error instanceof Error && error.name === "AIInputError" && "code" in error && error.code === "capacity_unavailable" && "providerStatus" in error && typeof error.providerStatus === "number" && error.providerStatus >= 400;
+};
+var isPermanentAIProviderFailure = (error) => {
+  if (isProviderError(error))
+    return !error.retryable;
+  if (error instanceof Error && "providerError" in error && isProviderError(error.providerError))
+    return !error.providerError.retryable;
+  return isAIProviderFailure(error) && "providerStatus" in error && typeof error.providerStatus === "number" && error.providerStatus < 500 && ![408, 409, 425, 429].includes(error.providerStatus);
+};
+var inspectWithProviderFallback = async (options) => {
+  const models = providerFallbackModels(options.model, options.recovery);
+  for (const [index, model] of models.entries()) {
+    options.signal?.throwIfAborted();
+    try {
+      return { model, value: await options.inspect(model) };
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      const next = models[index + 1];
+      if (!next || !isAIProviderFailure(error))
+        throw error;
+      await options.recovery?.onFallback?.({ from: model, to: next, error });
+    }
+  }
+  throw new Error("No approved model available");
+};
+async function* streamWithProviderFallback(options) {
+  const models = [...new Set(options.models)];
+  if (!models.length)
+    throw new Error("At least one approved model is required");
+  for (const [index, model] of models.entries()) {
+    options.signal?.throwIfAborted();
+    let emitted = false;
+    try {
+      for await (const chunk of options.stream(model)) {
+        emitted = true;
+        yield chunk;
+      }
+      return;
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      const next = models[index + 1];
+      if (emitted || !next || !isAIProviderFailure(error))
+        throw error;
+      await options.onFallback?.({ from: model, to: next, error });
+    }
+  }
+}
+
 // src/ai/inputCapacity.ts
 class AIInputError extends Error {
   code;
   providerStatus;
   requestId;
-  constructor(code, message, providerStatus, requestId) {
+  providerError;
+  constructor(code, message, providerStatus, requestId, providerError) {
     super(message);
     this.code = code;
     this.providerStatus = providerStatus;
     this.requestId = requestId;
+    this.providerError = providerError;
     this.name = "AIInputError";
   }
 }
@@ -298,7 +473,7 @@ var inspectAIInput = async (provider, params) => {
     provider.inputCapacity.countTokens(params)
   ]).catch((error) => {
     if (error instanceof Error && error.name === "AIInputError" && "code" in error && (error.code === "capacity_unavailable" || error.code === "input_too_large" || error.code === "unsupported_content"))
-      throw new AIInputError(error.code, error.message, "providerStatus" in error && typeof error.providerStatus === "number" ? error.providerStatus : undefined, "requestId" in error && typeof error.requestId === "string" ? error.requestId : undefined);
+      throw new AIInputError(error.code, error.message, "providerStatus" in error && typeof error.providerStatus === "number" ? error.providerStatus : undefined, "requestId" in error && typeof error.requestId === "string" ? error.requestId : undefined, "providerError" in error && isProviderError(error.providerError) ? ProviderError.from(error.providerError, error.providerError.provider) : undefined);
     throw error;
   });
   const inputTokens = inputTokenCount(tokens);
@@ -330,7 +505,7 @@ var cacheModelLimits = (load, ttlMs = 300000) => {
     return limits;
   };
 };
-var capacityJson = async (response) => {
+var capacityJson = async (response, provider = "unknown") => {
   if (!response.ok) {
     const payload = await response.json().catch(() => {
       return;
@@ -341,7 +516,7 @@ var capacityJson = async (response) => {
     const message = nested?.message ?? record?.message;
     const detail = typeof message === "string" ? message.slice(0, 1000) : undefined;
     const id = response.headers.get("request-id") ?? response.headers.get("x-request-id") ?? record?.request_id;
-    throw new AIInputError("capacity_unavailable", `Model capacity request failed (${response.status}).${detail ? ` ${detail}` : ""}`, response.status, typeof id === "string" ? id.slice(0, 200) : undefined);
+    throw new AIInputError("capacity_unavailable", `Model capacity request failed (${response.status}).${detail ? ` ${detail}` : ""}`, response.status, typeof id === "string" ? id.slice(0, 200) : undefined, ProviderError.fromResponse(provider, response.status, JSON.stringify({ error: nested ?? record ?? {} })));
   }
   const value = await response.json();
   if (!value || typeof value !== "object" || Array.isArray(value))
@@ -395,6 +570,16 @@ var snapshot = (params) => ({
 var tooLarge = () => new AIInputError("input_too_large", "The request exceeds the model's working context budget. Preserve the original input and reduce or retrieve context before retrying.");
 var streamWithAIContext = async function* (provider, params, policy = {}, onPrepared) {
   params.signal?.throwIfAborted();
+  if (policy !== false && policy.providerFallback) {
+    const { providerFallback, ...singlePolicy } = policy;
+    yield* streamWithProviderFallback({
+      models: providerFallbackModels(params.model, providerFallback),
+      signal: params.signal,
+      onFallback: providerFallback.onFallback,
+      stream: (model) => streamWithAIContext(provider, { ...params, model }, singlePolicy, onPrepared)
+    });
+    return;
+  }
   if (policy === false) {
     onPrepared?.(params);
     yield* provider.stream(params);
@@ -2044,6 +2229,7 @@ var streamAIWithTools = async function* (options) {
     const policy = contextPolicy ?? (validateInput === false ? false : undefined);
     const stream = streamWithAIContext(provider, request, policy, (prepared) => {
       messages.splice(0, messages.length, ...prepared.messages);
+      base.model = prepared.model;
     });
     const blocks = [];
     const pending = [];
@@ -2197,109 +2383,6 @@ var streamAIWithTools = async function* (options) {
   yield { ...summary, type: "done" };
   return summary;
 };
-// src/ai/errors/providerError.ts
-var PROVIDER_STATUS_PAGES = {
-  anthropic: "https://status.claude.com",
-  gemini: "https://status.cloud.google.com",
-  google: "https://status.cloud.google.com",
-  openai: "https://status.openai.com",
-  openrouter: "https://status.openrouter.ai"
-};
-var RETRYABLE_STATUSES = new Set([
-  408,
-  409,
-  425,
-  429,
-  500,
-  502,
-  503,
-  504,
-  529
-]);
-var CONNECTION_ERROR_PATTERNS = [
-  "econnreset",
-  "econnrefused",
-  "etimedout",
-  "enotfound",
-  "eai_again",
-  "socket hang up",
-  "fetch failed",
-  "network",
-  "terminated",
-  "timed out",
-  "timeout",
-  "and not retryable",
-  "no response body"
-];
-var isAbortError = (err) => err instanceof Error && (err.name === "AbortError" || /\babort(ed)?\b/i.test(err.message));
-var providerStatusPage = (provider) => PROVIDER_STATUS_PAGES[provider] ?? null;
-var BILLING_ERROR_TYPES = new Set([
-  "credit_balance_exhausted",
-  "insufficient_quota",
-  "billing_hard_limit_reached",
-  "billing_not_active",
-  "insufficient_credits"
-]);
-
-class ProviderError extends Error {
-  provider;
-  status;
-  type;
-  retryable;
-  billingUnavailable;
-  notSent;
-  metadata;
-  statusPageUrl;
-  constructor(init) {
-    super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
-    this.name = "ProviderError";
-    this.provider = init.provider;
-    this.status = init.status ?? null;
-    this.type = init.type ?? (typeof init.metadata?.code === "string" ? init.metadata.code : typeof init.metadata?.type === "string" ? init.metadata.type : null);
-    this.billingUnavailable = BILLING_ERROR_TYPES.has(this.type ?? "") || init.status === 402;
-    this.notSent = init.notSent === true;
-    this.retryable = !this.billingUnavailable && init.retryable;
-    this.metadata = init.metadata;
-    this.statusPageUrl = providerStatusPage(init.provider);
-  }
-  static fromResponse(provider, status, body, type) {
-    let metadata;
-    try {
-      const parsed = JSON.parse(body);
-      const details = parsed?.error ?? parsed;
-      if (details && typeof details === "object" && !Array.isArray(details))
-        metadata = details;
-    } catch {}
-    return new ProviderError({
-      metadata,
-      message: `${capitalize(provider)} API error ${status}: ${body}`,
-      provider,
-      retryable: RETRYABLE_STATUSES.has(status),
-      status,
-      type: type ?? null
-    });
-  }
-  static from(err, provider) {
-    if (err instanceof ProviderError)
-      return err;
-    if (isAbortError(err))
-      throw err;
-    const rawMessage = err instanceof Error ? err.message : String(err ?? "");
-    const lower = rawMessage.toLowerCase();
-    const statusMatch = lower.match(/api error\s+(\d{3})/);
-    const status = statusMatch ? Number(statusMatch[1]) : null;
-    const retryable = status !== null && RETRYABLE_STATUSES.has(status) || status === null && CONNECTION_ERROR_PATTERNS.some((pattern) => lower.includes(pattern));
-    return new ProviderError({
-      cause: err,
-      message: rawMessage || `${capitalize(provider)} request failed`,
-      provider,
-      retryable,
-      status
-    });
-  }
-}
-var capitalize = (value) => value.charAt(0).toUpperCase() + value.slice(1);
-
 // src/ai/providerProxy.ts
 var DEFAULT_HEARTBEAT_MS2 = 5000;
 var encoder = new TextEncoder;
@@ -4577,6 +4660,76 @@ var createAIStream = (path, conversationId) => {
     }
   };
 };
+// src/ai/providers/openaiSchema.ts
+var record2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var openaiSchema = (schema) => {
+  const result = { ...schema };
+  for (const key of [
+    "properties",
+    "$defs",
+    "definitions",
+    "patternProperties"
+  ]) {
+    const value = result[key];
+    if (record2(value))
+      result[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [
+        name,
+        record2(child) ? openaiSchema(child) : child
+      ]));
+  }
+  for (const key of [
+    "items",
+    "additionalProperties",
+    "not",
+    "if",
+    "then",
+    "else"
+  ])
+    if (record2(result[key]))
+      result[key] = openaiSchema(result[key]);
+  for (const key of ["anyOf", "oneOf", "allOf", "prefixItems"])
+    if (Array.isArray(result[key]))
+      result[key] = result[key].map((child) => record2(child) ? openaiSchema(child) : child);
+  const names = result.propertyNames;
+  if (record2(names) && Array.isArray(names.enum) && names.enum.every((key) => typeof key === "string") && Object.keys(names).every((key) => ["enum", "type", "description", "title"].includes(key)) && !result.patternProperties) {
+    const existing = record2(result.properties) ? result.properties : {};
+    const additional = result.additionalProperties;
+    const entries = names.enum.filter((key) => Object.hasOwn(existing, key) || additional !== false).map((key) => [
+      key,
+      Object.hasOwn(existing, key) ? existing[key] : record2(additional) ? additional : {}
+    ]);
+    result.properties = Object.fromEntries(entries);
+    result.additionalProperties = false;
+    delete result.propertyNames;
+  }
+  return result;
+};
+var isStrictCompatible = (schema) => {
+  if (Array.isArray(schema))
+    return schema.every(isStrictCompatible);
+  if (!record2(schema))
+    return true;
+  if (schema.propertyNames || schema.patternProperties)
+    return false;
+  const properties = record2(schema.properties) ? schema.properties : {};
+  if (schema.type === "object" || schema.properties || schema.additionalProperties !== undefined) {
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    if (schema.additionalProperties !== false || !Object.keys(properties).every((key) => required.includes(key)))
+      return false;
+  }
+  const nested = [
+    schema.items,
+    schema.anyOf,
+    schema.oneOf,
+    schema.allOf,
+    schema.additionalProperties
+  ];
+  for (const map of [properties, schema.$defs, schema.definitions])
+    if (record2(map))
+      nested.push(...Object.values(map));
+  return nested.every(isStrictCompatible);
+};
+
 // src/ai/providers/openaiCapacity.ts
 var LIMITS = {
   "gpt-4.1": {
@@ -4799,7 +4952,7 @@ var openaiInputCapacity = (config) => ({
       body: JSON.stringify(counted),
       signal: params.signal ? AbortSignal.any([params.signal, AbortSignal.timeout(15000)]) : AbortSignal.timeout(15000)
     });
-    return inputTokenCount((await capacityJson(response)).input_tokens);
+    return inputTokenCount((await capacityJson(response, "openai")).input_tokens);
   }
 });
 
@@ -4932,6 +5085,29 @@ var withResilience = (provider, providerName = "unknown") => {
   let billingFailure = null;
   let billingRetryAt = 0;
   let billingProbe = false;
+  const inspectAvailable = async (inspect) => {
+    if (billingFailure && Date.now() < billingRetryAt) {
+      throw new ProviderError({
+        provider: providerName,
+        message: "Provider billing is unavailable",
+        type: billingFailure.type,
+        status: billingFailure.status,
+        metadata: billingFailure.metadata,
+        retryable: false,
+        notSent: true
+      });
+    }
+    try {
+      return await inspect();
+    } catch (error) {
+      const nested = error instanceof Error && "providerError" in error ? error.providerError : error;
+      if (isProviderError(nested) && nested.billingUnavailable) {
+        billingFailure = ProviderError.from(nested, providerName);
+        billingRetryAt = Date.now() + billingCooldownMs;
+      }
+      throw error;
+    }
+  };
   const billingCooldownMs = 5 * 60000;
   const attempt = async function* (params, attemptNo) {
     let yielded = false;
@@ -4959,33 +5135,39 @@ var withResilience = (provider, providerName = "unknown") => {
       if (providerError.retryable)
         noteFailure(providerName, providerError);
       throw providerError;
+    } finally {
+      billingProbe = false;
     }
   };
   return {
     ...provider,
-    stream: (params) => {
+    ...provider.inputCapacity ? {
+      inputCapacity: {
+        ...provider.inputCapacity,
+        getLimits: (params) => inspectAvailable(() => provider.inputCapacity.getLimits(params)),
+        countTokens: (params) => inspectAvailable(() => provider.inputCapacity.countTokens(params))
+      }
+    } : {},
+    stream: async function* (params) {
       if (billingFailure && (Date.now() < billingRetryAt || billingProbe)) {
         const failure = billingFailure;
-        return async function* () {
-          throw new ProviderError({
-            provider: providerName,
-            message: "Provider billing is unavailable",
-            type: failure.type,
-            status: failure.status,
-            retryable: false,
-            notSent: true
-          });
-        }();
+        throw new ProviderError({
+          provider: providerName,
+          message: "Provider billing is unavailable",
+          type: failure.type,
+          status: failure.status,
+          metadata: failure.metadata,
+          retryable: false,
+          notSent: true
+        });
       }
-      if (billingFailure)
-        billingProbe = true;
       const tripped = circuitOpen(providerName);
       if (tripped) {
-        return async function* () {
-          throw tripped;
-        }();
+        throw tripped;
       }
-      return attempt(params, 0);
+      if (billingFailure)
+        billingProbe = true;
+      yield* attempt(params, 0);
     }
   };
 };
@@ -4994,7 +5176,7 @@ var withResilience = (provider, providerName = "unknown") => {
 var instrumentAIProvider = (provider, providerName) => {
   const resilient = withResilience(provider, providerName);
   return {
-    ...provider,
+    ...resilient,
     stream: (params) => {
       if (!params.onUsage && !params.onSpan) {
         return resilient.stream(params);
@@ -5354,30 +5536,11 @@ var buildInput = (messages) => {
   }
   return input;
 };
-var isStrictCompatible = (schema) => {
-  if (Array.isArray(schema))
-    return schema.every(isStrictCompatible);
-  if (!isRecord2(schema))
-    return true;
-  const { properties } = schema;
-  if (isRecord2(properties)) {
-    const required = Array.isArray(schema.required) ? schema.required : [];
-    if (schema.additionalProperties !== false)
-      return false;
-    if (!Object.keys(properties).every((key) => required.includes(key)))
-      return false;
-  }
-  const nested = [schema.items, schema.anyOf];
-  for (const map of [properties, schema.$defs, schema.definitions])
-    if (isRecord2(map))
-      nested.push(...Object.values(map));
-  return nested.every(isStrictCompatible);
-};
 var mapToolDefinition = (tool) => ({
   description: tool.description,
   name: tool.name,
-  parameters: tool.input_schema,
-  strict: isStrictCompatible(tool.input_schema),
+  parameters: openaiSchema(tool.input_schema),
+  strict: isStrictCompatible(openaiSchema(tool.input_schema)),
   type: "function"
 });
 var buildTools = (tools, isImageModel) => {
@@ -5434,7 +5597,7 @@ var buildResponsesRequestBody = (params, isImageModel, capabilityModel = params.
       body.text = {
         format: {
           name: params.responseFormat.name,
-          schema: params.responseFormat.schema,
+          schema: openaiSchema(params.responseFormat.schema),
           strict: params.responseFormat.strict ?? true,
           type: "json_schema"
         }
@@ -5901,7 +6064,7 @@ var mapToolDefinitions = (tools) => tools.map((tool) => ({
   function: {
     description: tool.description,
     name: tool.name,
-    parameters: tool.input_schema
+    parameters: openaiSchema(tool.input_schema)
   },
   type: "function"
 }));
@@ -6027,7 +6190,7 @@ var buildRequestBody = (params, capabilityModel = params.model, providerName = "
       body.response_format = {
         json_schema: {
           name: params.responseFormat.name,
-          schema: params.responseFormat.schema,
+          schema: openaiSchema(params.responseFormat.schema),
           strict: params.responseFormat.strict ?? true
         },
         type: "json_schema"
@@ -7528,7 +7691,7 @@ var anthropic = (config) => {
       headers,
       body: body ? JSON.stringify(body) : undefined,
       signal: params.signal ? AbortSignal.any([params.signal, AbortSignal.timeout(15000)]) : AbortSignal.timeout(15000)
-    }));
+    }), "anthropic");
   };
   const countingRequest = (params) => {
     const built = buildRequestBody3(params, configuredMax, promptCaching);
@@ -8900,8 +9063,17 @@ var hashText = async (text) => {
   return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
 };
 var prepareAITextInputInternal = async (provider, params, options, stopAfterSection) => {
+  if (options.providerFallback)
+    params = { ...params };
   const inspectBudget = async (_provider, request) => {
-    const inspected = await inspectAIContext(_provider, request, options.contextBudget);
+    const selected = await inspectWithProviderFallback({
+      model: request.model,
+      recovery: options.providerFallback,
+      signal: request.signal,
+      inspect: (model) => inspectAIContext(_provider, { ...request, model }, options.contextBudget)
+    });
+    request.model = selected.model;
+    const inspected = selected.value;
     return {
       ...inspected,
       fits: inspected.withinWorkingLimit,
@@ -8939,28 +9111,43 @@ var prepareAITextInputInternal = async (provider, params, options, stopAfterSect
     throw new AIInputError("input_too_large", "The instructions and tools leave no room for input in this model.");
   if (options.preparationModel !== undefined && !options.preparationModel.trim())
     throw new AIInputError("capacity_unavailable", "A preparation model must be nonempty.");
-  const preparationModel = options.preparationModel ?? params.model;
-  const preparationCapacity = options.preparationModel === undefined ? capacity : await inspectBudget(provider, {
-    model: preparationModel,
+  const preparationProbe = {
+    model: options.preparationModel ?? params.model,
     signal: params.signal,
     maxTokens: 1,
     messages: [{ role: "user", content: "." }]
-  });
+  };
+  const preparationCapacity = options.preparationModel === undefined ? capacity : await inspectBudget(provider, preparationProbe);
+  const preparationModel = preparationProbe.model;
   const taskHash = await hashText(JSON.stringify({
-    preparationPolicyVersion: 3,
-    preparationModel: options.preparationModel,
-    model: params.model,
+    preparationPolicyVersion: options.providerFallback ? 4 : 3,
+    preparationModel: options.providerFallback ? undefined : options.preparationModel,
+    model: options.providerFallback ? undefined : params.model,
     systemPrompt: params.systemPrompt,
     tools: params.tools,
     compactedContext: options.compactedContext,
     contextBudget: options.contextBudget
   }));
+  const compatibleHashes = new Set([taskHash]);
+  if (options.providerFallback && options.checkpoint) {
+    for (const model of providerFallbackModels(params.model, options.providerFallback)) {
+      compatibleHashes.add(await hashText(JSON.stringify({
+        preparationPolicyVersion: 3,
+        preparationModel: options.preparationModel,
+        model,
+        systemPrompt: params.systemPrompt,
+        tools: params.tools,
+        compactedContext: options.compactedContext,
+        contextBudget: options.contextBudget
+      })));
+    }
+  }
   const last = params.messages.at(-1);
   let notes = "";
   let offset = 0;
   let sectionsProcessed = 0;
   const saved = options.checkpoint;
-  if (saved?.version === 1 && saved.taskHash === taskHash && Number.isSafeInteger(saved.processedCharacters) && saved.processedCharacters > 0 && saved.processedCharacters <= text.length && Number.isSafeInteger(saved.sectionsProcessed) && saved.sectionsProcessed > 0 && typeof saved.notes === "string" && saved.notes.trim() && saved.prefixHash === await hashText(text.slice(0, saved.processedCharacters))) {
+  if (saved?.version === 1 && compatibleHashes.has(saved.taskHash) && Number.isSafeInteger(saved.processedCharacters) && saved.processedCharacters > 0 && saved.processedCharacters <= text.length && Number.isSafeInteger(saved.sectionsProcessed) && saved.sectionsProcessed > 0 && typeof saved.notes === "string" && saved.notes.trim() && saved.prefixHash === await hashText(text.slice(0, saved.processedCharacters))) {
     notes = saved.notes;
     offset = saved.processedCharacters;
     sectionsProcessed = saved.sectionsProcessed;
@@ -9030,7 +9217,10 @@ var prepareAITextInputInternal = async (provider, params, options, stopAfterSect
     params.signal?.throwIfAborted();
     let updated = "";
     let ended = false;
-    for await (const chunk of provider.stream(request)) {
+    for await (const chunk of options.providerFallback ? streamWithAIContext(provider, request, {
+      ...options.contextBudget,
+      providerFallback: options.providerFallback
+    }) : provider.stream(request)) {
       if (chunk.type === "text")
         updated += chunk.content;
       if (chunk.type === "done") {
@@ -9110,7 +9300,7 @@ var boundary = (text, offset) => {
   const next = text.charCodeAt(offset);
   return code >= 55296 && code <= 56319 && next >= 56320 && next <= 57343 ? offset - 1 : offset;
 };
-var record2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+var record3 = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 var createAITextSource = (messages) => {
   const sources = messages.map((message, index) => {
     if (typeof message.content !== "string")
@@ -9177,7 +9367,7 @@ var createAITextSource = (messages) => {
         additionalProperties: false
       },
       handler: (input) => {
-        const value = record2(input);
+        const value = record3(input);
         if (typeof value.query !== "string")
           return "Provide a text query.";
         return JSON.stringify({
@@ -9200,7 +9390,7 @@ var createAITextSource = (messages) => {
         additionalProperties: false
       },
       handler: (input) => {
-        const value = record2(input);
+        const value = record3(input);
         if (typeof value.sourceId !== "string" || typeof value.start !== "number")
           return "Provide a source ID and start offset.";
         return JSON.stringify({
@@ -9269,29 +9459,6 @@ var createAIProviderRouter = (routes) => {
     stream: (params) => resolve(params).stream(params)
   };
 };
-// src/ai/providerFallback.ts
-async function* streamWithProviderFallback(options) {
-  const models = [...new Set(options.models)];
-  if (!models.length)
-    throw new Error("At least one approved model is required");
-  for (const [index, model] of models.entries()) {
-    options.signal?.throwIfAborted();
-    let emitted = false;
-    try {
-      for await (const chunk of options.stream(model)) {
-        emitted = true;
-        yield chunk;
-      }
-      return;
-    } catch (error) {
-      options.signal?.throwIfAborted();
-      const next = models[index + 1];
-      if (emitted || !next || !(error instanceof ProviderError) || !(error.billingUnavailable || error.retryable || error.notSent))
-        throw error;
-      await options.onFallback?.({ from: model, to: next, error });
-    }
-  }
-}
 export {
   AIInputError,
   BUILTIN_UI_CARDS,
@@ -9362,7 +9529,11 @@ export {
   google,
   inspectAIContext,
   inspectAIInput,
+  inspectWithProviderFallback,
   isAIContextRejection,
+  isAIProviderFailure,
+  isPermanentAIProviderFailure,
+  isProviderError,
   meta,
   mistralai,
   moonshot,
@@ -9411,5 +9582,5 @@ export {
   xai
 };
 
-//# debugId=15DF9981B943EAAB64756E2164756E21
+//# debugId=3224ABE1580A431764756E2164756E21
 //# sourceMappingURL=index.js.map