@axlsdk/axl 0.21.1 → 0.22.0

package/dist/index.cjs

@@ -130,10 +130,15 @@ __export(index_exports, {
   EventStreamOverflowError: () => EventStreamOverflowError,
   GROQ_PROFILE: () => GROQ_PROFILE,
   GeminiProvider: () => GeminiProvider,
+  GeminiTranscriptionProvider: () => GeminiTranscriptionProvider,
   GuardrailError: () => GuardrailError,
   InMemoryVectorStore: () => InMemoryVectorStore,
+  InvalidModelInputError: () => InvalidModelInputError,
+  InvalidTranscriptionInputError: () => InvalidTranscriptionInputError,
   LLAMACPP_PROFILE: () => LLAMACPP_PROFILE,
   LMSTUDIO_PROFILE: () => LMSTUDIO_PROFILE,
+  MAX_INLINE_MODEL_INPUT_BYTES: () => MAX_INLINE_MODEL_INPUT_BYTES,
+  MAX_INLINE_TRANSCRIPTION_BYTES: () => MAX_INLINE_TRANSCRIPTION_BYTES,
   MISTRAL_PROFILE: () => MISTRAL_PROFILE,
   MaxTurnsError: () => MaxTurnsError,
   McpManager: () => McpManager,
@@ -149,6 +154,8 @@ __export(index_exports, {
   OpenAIEmbedder: () => OpenAIEmbedder,
   OpenAIProvider: () => OpenAIProvider,
   OpenAIResponsesProvider: () => OpenAIResponsesProvider,
+  OpenAITranscriptionProvider: () => OpenAITranscriptionProvider,
+  OpenRouterTranscriptionProvider: () => OpenRouterTranscriptionProvider,
   ProviderError: () => ProviderError,
   ProviderRegistry: () => ProviderRegistry,
   QuorumNotMet: () => QuorumNotMet,
@@ -164,7 +171,11 @@ __export(index_exports, {
   TimeoutError: () => TimeoutError,
   ToolFailure: () => ToolFailure,
   ToolModelOutputError: () => ToolModelOutputError,
+  TranscriptionOperationError: () => TranscriptionOperationError,
+  TranscriptionProviderRegistry: () => TranscriptionProviderRegistry,
   UnsupportedEventSchemaVersionError: () => UnsupportedEventSchemaVersionError,
+  UnsupportedModelInputError: () => UnsupportedModelInputError,
+  UnsupportedTranscriptionInputError: () => UnsupportedTranscriptionInputError,
   VLLM_PROFILE: () => VLLM_PROFILE,
   ValidationError: () => ValidationError,
   VerifyError: () => VerifyError,
@@ -181,8 +192,10 @@ __export(index_exports, {
   findConfig: () => findConfig,
   getEventSchemaVersion: () => getEventSchemaVersion,
   getExecutionEventSchemaVersion: () => getExecutionEventSchemaVersion,
+  hasPositiveBillableWork: () => hasPositiveBillableWork,
   hasPositiveTokens: () => hasPositiveTokens,
   importModule: () => importModule,
+  inputText: () => inputText,
   isCostBearingLeaf: () => isCostBearingLeaf,
   isRetryableStatus: () => isRetryableStatus,
   isRootLevel: () => isRootLevel,
@@ -223,6 +236,75 @@ var AxlError = class extends Error {
     this.code = code;
   }
 };
+var InvalidModelInputError = class extends AxlError {
+  constructor(message) {
+    super("INVALID_MODEL_INPUT", message);
+    this.name = "InvalidModelInputError";
+  }
+};
+var UnsupportedModelInputError = class extends AxlError {
+  provider;
+  model;
+  modality;
+  source;
+  constructor(options) {
+    super(
+      "UNSUPPORTED_MODEL_INPUT",
+      `Provider '${options.provider}' model '${options.model}' does not support ${options.feature ?? options.modality}${options.source ? ` from ${options.source}` : ""}`
+    );
+    this.name = "UnsupportedModelInputError";
+    this.provider = options.provider;
+    this.model = options.model;
+    this.modality = options.modality;
+    this.source = options.source;
+  }
+};
+var InvalidTranscriptionInputError = class extends AxlError {
+  constructor(message) {
+    super("INVALID_TRANSCRIPTION_INPUT", message);
+    this.name = "InvalidTranscriptionInputError";
+  }
+};
+var UnsupportedTranscriptionInputError = class extends AxlError {
+  provider;
+  model;
+  constructor(options) {
+    super(
+      "UNSUPPORTED_TRANSCRIPTION_INPUT",
+      `Transcription provider '${options.provider}'${options.model ? ` model '${options.model}'` : ""} does not support ${options.feature ?? "this request"}`
+    );
+    this.name = "UnsupportedTranscriptionInputError";
+    this.provider = options.provider;
+    this.model = options.model;
+  }
+};
+var TranscriptionOperationError = class extends AxlError {
+  provider;
+  model;
+  usage;
+  pricingStatus;
+  cleanupStatus;
+  /** Safe HTTP diagnostics projected from ProviderError when available. */
+  status;
+  retryable;
+  retryAfterMs;
+  requestId;
+  constructor(options) {
+    super("TRANSCRIPTION_PROVIDER_ERROR", "Transcription provider operation failed");
+    this.name = "TranscriptionOperationError";
+    this.provider = options.provider;
+    this.model = options.model;
+    this.usage = options.usage;
+    this.pricingStatus = options.pricingStatus;
+    this.cleanupStatus = options.cleanupStatus;
+    this.status = options.status;
+    this.retryable = options.retryable;
+    this.retryAfterMs = options.retryAfterMs;
+    this.requestId = options.requestId;
+    if (options.cause !== void 0)
+      Object.defineProperty(this, "cause", { enumerable: false, value: options.cause });
+  }
+};
 var EventStreamOverflowError = class extends Error {
   maxQueued;
   eventType;
@@ -1195,6 +1277,38 @@ function unsafeTransportError(surface, remediation, exposedData) {
 }
 
 // src/providers/openai-compatible.ts
+var OPENROUTER_IMAGE_MODEL = "openai/gpt-4o-mini";
+function compatibleImageBase64(source) {
+  return source.type === "base64" ? source.data : Buffer.from(source.data.buffer, source.data.byteOffset, source.data.byteLength).toString(
+    "base64"
+  );
+}
+function openRouterImageParts(parts) {
+  const content = [];
+  for (const part of parts) {
+    if (part.type === "text") {
+      content.push({ type: "text", text: part.text });
+      continue;
+    }
+    const { source } = part;
+    if (source.type === "provider-file") {
+      throw new UnsupportedModelInputError({
+        provider: "openrouter",
+        model: OPENROUTER_IMAGE_MODEL,
+        modality: "image",
+        source: "provider-file"
+      });
+    }
+    content.push({
+      type: "image_url",
+      image_url: {
+        url: source.type === "url" ? source.url : `data:${source.mediaType};base64,${compatibleImageBase64(source)}`
+      }
+    });
+    if (part.label) content.push({ type: "text", text: `[Image: ${part.label}]` });
+  }
+  return content;
+}
 function resolvePerModel(value, model, fallback) {
   if (value === void 0) return fallback;
   return typeof value === "function" ? value(model) : value;
@@ -1310,6 +1424,41 @@ function normalizeMessageContent(content) {
 }
 var OpenAICompatibleProvider = class {
   name;
+  inputCapabilities(model) {
+    return this.name === "openrouter" && model === OPENROUTER_IMAGE_MODEL ? { image: { sources: ["url", "bytes", "base64"] } } : {};
+  }
+  validateInput(request) {
+    const effectiveModel = typeof request.providerOptions?.model === "string" ? request.providerOptions.model : request.model;
+    const fail = (source, feature) => {
+      throw new UnsupportedModelInputError({
+        provider: this.name,
+        model: effectiveModel || request.model,
+        modality: "image",
+        ...source ? { source } : {},
+        ...feature ? { feature } : {}
+      });
+    };
+    if (this.name !== "openrouter" || effectiveModel !== OPENROUTER_IMAGE_MODEL) {
+      fail(void 0, "image input for this model");
+    }
+    if (request.providerOptions && "messages" in request.providerOptions) {
+      fail(void 0, "raw messages providerOptions");
+    }
+    if (request.hasTools) fail(void 0, "tools with image input");
+    for (const message of request.history) {
+      if (!Array.isArray(message.content)) continue;
+      if (message.role !== "user") fail(void 0, "rich non-user history");
+      if (message.content.some(
+        (part) => part.type === "image" && part.source.type === "provider-file"
+      )) {
+        fail("provider-file");
+      }
+    }
+    if (Array.isArray(request.input) && request.input.some((part) => part.type === "image" && part.source.type === "provider-file")) {
+      fail("provider-file");
+    }
+    return { effectiveModel };
+  }
   /** `json_schema` is honored natively when the profile's `supportsJsonSchema`
    *  capability is true for this model (the default); otherwise the engine
    *  downgrades the request to plain `json_object` (see `buildRequestBody`),
@@ -1483,7 +1632,7 @@ var OpenAICompatibleProvider = class {
   formatMessage(msg, model) {
     const out = {
       role: this.profile.roleFor ? this.profile.roleFor(msg.role, model) : msg.role,
-      content: msg.content
+      content: Array.isArray(msg.content) && this.name === "openrouter" && model === OPENROUTER_IMAGE_MODEL ? openRouterImageParts(msg.content) : msg.content
     };
     if (msg.name && (this.profile.capabilities?.emitsMessageName ?? true)) out.name = msg.name;
     if (msg.tool_calls) out.tool_calls = msg.tool_calls;
@@ -2230,8 +2379,88 @@ var OpenAIProvider = class extends OpenAICompatibleProvider {
 };
 
 // src/providers/openai-responses.ts
+var OPENAI_RESPONSES_IMAGE_MODELS = /* @__PURE__ */ new Set([
+  "gpt-4o",
+  "gpt-4o-2024-08-06",
+  "gpt-4o-2024-11-20",
+  "gpt-4o-mini",
+  "gpt-4o-mini-2024-07-18"
+]);
+function base64FromSource(source) {
+  return source.type === "base64" ? source.data : Buffer.from(source.data.buffer, source.data.byteOffset, source.data.byteLength).toString(
+    "base64"
+  );
+}
+function responseImageParts(parts) {
+  const mapped = [];
+  for (const part of parts) {
+    if (part.type === "text") {
+      mapped.push({ type: "input_text", text: part.text });
+      continue;
+    }
+    const { source } = part;
+    if (source.type === "provider-file") {
+      if (source.provider !== "openai-responses") {
+        throw new UnsupportedModelInputError({
+          provider: "openai-responses",
+          model: "unknown",
+          modality: "image",
+          source: "provider-file"
+        });
+      }
+      mapped.push({ type: "input_image", file_id: source.reference });
+    } else if (source.type === "url") {
+      mapped.push({ type: "input_image", image_url: source.url });
+    } else {
+      mapped.push({
+        type: "input_image",
+        image_url: `data:${source.mediaType};base64,${base64FromSource(source)}`
+      });
+    }
+    if (part.label) mapped.push({ type: "input_text", text: `[Image: ${part.label}]` });
+  }
+  return mapped;
+}
 var OpenAIResponsesProvider = class {
   name = "openai-responses";
+  inputCapabilities(model) {
+    return OPENAI_RESPONSES_IMAGE_MODELS.has(model) ? { image: { sources: ["url", "bytes", "base64", "provider-file"] } } : {};
+  }
+  validateInput(request) {
+    const effectiveModel = typeof request.providerOptions?.model === "string" ? request.providerOptions.model : request.model;
+    const fail = (source, feature) => {
+      throw new UnsupportedModelInputError({
+        provider: this.name,
+        model: effectiveModel || request.model,
+        modality: "image",
+        ...source ? { source } : {},
+        ...feature ? { feature } : {}
+      });
+    };
+    if (!OPENAI_RESPONSES_IMAGE_MODELS.has(effectiveModel)) {
+      fail(void 0, "image input for this model");
+    }
+    if (request.providerOptions && "input" in request.providerOptions) {
+      fail(void 0, "raw input-container providerOptions");
+    }
+    for (const message of request.history) {
+      if (!Array.isArray(message.content)) continue;
+      if (message.role !== "user") fail(void 0, "rich non-user history");
+      for (const part of message.content) {
+        if (part.type === "image" && part.source.type === "provider-file" && part.source.provider !== this.name) {
+          fail("provider-file");
+        }
+      }
+    }
+    if (Array.isArray(request.input)) {
+      for (const part of request.input) {
+        if (part.type === "image" && part.source.type === "provider-file" && part.source.provider !== this.name) {
+          fail("provider-file");
+        }
+      }
+    }
+    return { effectiveModel };
+  }
   /** The Responses API honors `json_schema` (structured outputs) natively. */
   nativeStructuredOutputSupport() {
     return "schema";
@@ -2396,11 +2625,12 @@ var OpenAIResponsesProvider = class {
   buildInput(messages) {
     const input = [];
     for (const msg of messages) {
+      const text = typeof msg.content === "string" ? msg.content : "";
       if (msg.role === "tool") {
         input.push({
           type: "function_call_output",
           call_id: msg.tool_call_id ?? "",
-          output: msg.content
+          output: text
         });
       } else if (msg.role === "assistant" && msg.tool_calls && msg.tool_calls.length > 0) {
         const reasoningItems = msg.providerMetadata?.openaiReasoningItems;
@@ -2409,8 +2639,8 @@ var OpenAIResponsesProvider = class {
             input.push(item);
           }
         }
-        if (msg.content) {
-          input.push({ type: "message", role: "assistant", content: msg.content });
+        if (text) {
+          input.push({ type: "message", role: "assistant", content: text });
         }
         for (const tc of msg.tool_calls) {
           input.push({
@@ -2430,7 +2660,7 @@ var OpenAIResponsesProvider = class {
         input.push({
           type: "message",
           role: msg.role,
-          content: msg.content
+          content: typeof msg.content === "string" ? msg.content : responseImageParts(msg.content)
         });
       }
     }
@@ -2497,7 +2727,7 @@ var OpenAIResponsesProvider = class {
       cached_tokens: json.usage.input_tokens_details?.cached_tokens,
       cache_write_tokens: json.usage.input_tokens_details?.cache_write_tokens
     } : void 0;
-    const cost = usage ? estimateDirectOpenAICost(json.model ?? model, usage, {
+    const cost = usage && !this.requestContainsImages(request) ? estimateDirectOpenAICost(json.model ?? model, usage, {
       baseUrl: this.baseUrl,
       request,
       response: json
@@ -2512,6 +2742,16 @@ var OpenAIResponsesProvider = class {
       providerMetadata
     };
   }
+  /** Responses usage does not report a media-inclusive price, so rich calls stay unpriced. */
+  requestContainsImages(request) {
+    return Array.isArray(request?.input) && request.input.some((item) => {
+      if (!item || typeof item !== "object") return false;
+      const content = item.content;
+      return Array.isArray(content) && content.some(
+        (part) => part !== null && typeof part === "object" && part.type === "input_image"
+      );
+    });
+  }
   // ---------------------------------------------------------------------------
   // Internal: parse SSE stream
   // ---------------------------------------------------------------------------
@@ -2599,7 +2839,7 @@ var OpenAIResponsesProvider = class {
         return {
           type: "done",
           usage,
-          cost: usage ? estimateDirectOpenAICost(response?.model ?? model, usage, {
+          cost: usage && !this.requestContainsImages(request) ? estimateDirectOpenAICost(response?.model ?? model, usage, {
             baseUrl: this.baseUrl,
             request,
             response
@@ -2636,7 +2876,51 @@ var OpenAIResponsesProvider = class {
 };
 
 // src/providers/anthropic.ts
+function anthropicBase64(source) {
+  return source.type === "base64" ? source.data : Buffer.from(source.data.buffer, source.data.byteOffset, source.data.byteLength).toString(
+    "base64"
+  );
+}
+function anthropicImageBlocks(parts) {
+  const blocks = [];
+  for (const part of parts) {
+    if (part.type === "text") {
+      blocks.push({ type: "text", text: part.text });
+      continue;
+    }
+    const { source } = part;
+    if (source.type === "provider-file") {
+      if (source.provider !== "anthropic") {
+        throw new UnsupportedModelInputError({
+          provider: "anthropic",
+          model: "unknown",
+          modality: "image",
+          source: "provider-file"
+        });
+      }
+      blocks.push({ type: "image", source: { type: "file", file_id: source.reference } });
+    } else if (source.type === "url") {
+      blocks.push({ type: "image", source: { type: "url", url: source.url } });
+    } else {
+      blocks.push({
+        type: "image",
+        source: { type: "base64", media_type: source.mediaType, data: anthropicBase64(source) }
+      });
+    }
+    if (part.label) blocks.push({ type: "text", text: `[Image: ${part.label}]` });
+  }
+  return blocks;
+}
 var ANTHROPIC_API_VERSION = "2023-06-01";
+var ANTHROPIC_FILES_BETA = "files-api-2025-04-14";
+var ANTHROPIC_IMAGE_MODELS = /* @__PURE__ */ new Set(["claude-sonnet-4-5", "claude-opus-4-8"]);
+function hasAnthropicProviderFileImage(messages) {
+  return messages.some(
+    (message) => Array.isArray(message.content) && message.content.some(
+      (part) => part.type === "image" && part.source.type === "provider-file" && part.source.provider === "anthropic"
+    )
+  );
+}
 var CLAUDE_CAPABILITIES = {
   "claude-fable-5": {
     thinking: "adaptive-always-on",
@@ -2897,6 +3181,11 @@ function isEffortAtOrBelow(effort, ceiling) {
 function pricingContextFromBody(body) {
   return {
     model: typeof body.model === "string" ? body.model : void 0,
+    hasRichInput: Array.isArray(body.messages) && body.messages.some(
+      (message) => message !== null && typeof message === "object" && Array.isArray(message.content) && message.content.some(
+        (part) => part !== null && typeof part === "object" && part.type === "image"
+      )
+    ),
     unpricedModifier: isAnthropicModifier("inference_geo", body.inference_geo) || isAnthropicModifier("speed", body.speed) || hasAnthropicServerTool(body.tools) || body.fallbacks !== void 0
   };
 }
@@ -2991,6 +3280,44 @@ function mergeAnthropicUsage(initial, update) {
 }
 var AnthropicProvider = class {
   name = "anthropic";
+  inputCapabilities(model) {
+    return ANTHROPIC_IMAGE_MODELS.has(model) ? { image: { sources: ["url", "bytes", "base64", "provider-file"] } } : {};
+  }
+  validateInput(request) {
+    const effectiveModel = typeof request.providerOptions?.model === "string" ? request.providerOptions.model : request.model;
+    const fail = (source, feature) => {
+      throw new UnsupportedModelInputError({
+        provider: this.name,
+        model: effectiveModel || request.model,
+        modality: "image",
+        ...source ? { source } : {},
+        ...feature ? { feature } : {}
+      });
+    };
+    if (!ANTHROPIC_IMAGE_MODELS.has(effectiveModel)) {
+      fail(void 0, "image input for this model");
+    }
+    if (request.providerOptions && "messages" in request.providerOptions) {
+      fail(void 0, "raw messages providerOptions");
+    }
+    for (const message of request.history) {
+      if (!Array.isArray(message.content)) continue;
+      if (message.role !== "user") fail(void 0, "rich non-user history");
+      for (const part of message.content) {
+        if (part.type === "image" && part.source.type === "provider-file" && part.source.provider !== this.name) {
+          fail("provider-file");
+        }
+      }
+    }
+    if (Array.isArray(request.input)) {
+      for (const part of request.input) {
+        if (part.type === "image" && part.source.type === "provider-file" && part.source.provider !== this.name) {
+          fail("provider-file");
+        }
+      }
+    }
+    return { effectiveModel };
+  }
   /** Anthropic ignores native `json_schema` structurally — Axl uses a system
    *  prompt JSON instruction + client-side Zod validation (see buildRequest). */
   nativeStructuredOutputSupport() {
@@ -3028,7 +3355,10 @@ var AnthropicProvider = class {
   // chat - non-streaming completion
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
-    const headers = this.buildHeaders(await this.resolveKey());
+    const headers = this.buildHeaders(
+      await this.resolveKey(),
+      hasAnthropicProviderFileImage(messages)
+    );
     const body = this.buildRequestBody(messages, options, false);
     const pricingContext = pricingContextFromBody(body);
     const res = await fetchWithRetry(
@@ -3059,7 +3389,10 @@ var AnthropicProvider = class {
   // stream - SSE streaming completion
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
-    const headers = this.buildHeaders(await this.resolveKey());
+    const headers = this.buildHeaders(
+      await this.resolveKey(),
+      hasAnthropicProviderFileImage(messages)
+    );
     const body = this.buildRequestBody(messages, options, true);
     const pricingContext = pricingContextFromBody(body);
     const res = await fetchWithRetry(
@@ -3091,11 +3424,12 @@ var AnthropicProvider = class {
   // ---------------------------------------------------------------------------
   // Internal: request building
   // ---------------------------------------------------------------------------
-  buildHeaders(apiKey) {
+  buildHeaders(apiKey, requiresFilesBeta = false) {
     return {
       "Content-Type": "application/json",
       "x-api-key": apiKey,
-      "anthropic-version": ANTHROPIC_API_VERSION
+      "anthropic-version": ANTHROPIC_API_VERSION,
+      ...requiresFilesBeta ? { "anthropic-beta": ANTHROPIC_FILES_BETA } : {}
     };
   }
   /** Extract a human-readable message from an API error response body. */
@@ -3165,12 +3499,13 @@ ${jsonInstruction}` : jsonInstruction;
   mapMessages(messages) {
     const result = [];
     for (const msg of messages) {
+      const text = typeof msg.content === "string" ? msg.content : "";
       if (msg.role === "assistant") {
         const replayedThinking = this.getReplayedThinkingBlocks(msg);
         if (msg.tool_calls && msg.tool_calls.length > 0) {
           const content = [...replayedThinking];
-          if (msg.content) {
-            content.push({ type: "text", text: msg.content });
+          if (text) {
+            content.push({ type: "text", text });
           }
           for (const tc of msg.tool_calls) {
             let parsedArgs;
@@ -3189,10 +3524,10 @@ ${jsonInstruction}` : jsonInstruction;
           result.push({ role: "assistant", content });
         } else if (replayedThinking.length > 0) {
           const content = [...replayedThinking];
-          if (msg.content) content.push({ type: "text", text: msg.content });
+          if (text) content.push({ type: "text", text });
           result.push({ role: "assistant", content });
         } else {
-          result.push({ role: "assistant", content: msg.content });
+          result.push({ role: "assistant", content: text });
         }
       } else if (msg.role === "tool") {
         result.push({
@@ -3201,12 +3536,15 @@ ${jsonInstruction}` : jsonInstruction;
             {
               type: "tool_result",
               tool_use_id: msg.tool_call_id,
-              content: msg.content
+              content: text
             }
           ]
         });
       } else if (msg.role === "user") {
-        result.push({ role: "user", content: msg.content });
+        result.push({
+          role: "user",
+          content: typeof msg.content === "string" ? msg.content : anthropicImageBlocks(msg.content)
+        });
       }
     }
     return this.mergeConsecutiveRoles(result);
@@ -3311,7 +3649,7 @@ ${jsonInstruction}` : jsonInstruction;
         "Anthropic fallback responses cannot be continued safely; retry without fallbacks."
       );
     }
-    const cost = normalized && !pricingContext.unpricedModifier && !isModifiedAnthropicResponse(json, effectiveModel) && !hasFallbackBoundary && !refused ? estimateAnthropicCost(effectiveModel, normalized.pricingUsage) : void 0;
+    const cost = normalized && !pricingContext.hasRichInput && !pricingContext.unpricedModifier && !isModifiedAnthropicResponse(json, effectiveModel) && !hasFallbackBoundary && !refused ? estimateAnthropicCost(effectiveModel, normalized.pricingUsage) : void 0;
     return {
       content,
       thinking_content: thinkingContent || void 0,
@@ -3348,7 +3686,7 @@ ${jsonInstruction}` : jsonInstruction;
     const doneChunk = () => ({
       type: "done",
       usage,
-      cost: pricingUsage && !unpricedModifier && !hasFallbackBoundary && !refused ? estimateAnthropicCost(effectiveModel, pricingUsage) : void 0,
+      cost: pricingUsage && !pricingContext.hasRichInput && !unpricedModifier && !hasFallbackBoundary && !refused ? estimateAnthropicCost(effectiveModel, pricingUsage) : void 0,
       providerMetadata: thinkingBlocks.length > 0 && !hasFallbackBoundary && !hasFallbackIterationSignal ? { anthropicThinkingBlocks: thinkingBlocks } : void 0
     });
     try {
@@ -3496,6 +3834,60 @@ function lastFallbackIndex(blocks) {
 }
 
 // src/providers/gemini.ts
+function hasRichGeminiMessages(messages) {
+  return messages.some((message) => Array.isArray(message.content));
+}
+function geminiImageBase64(source) {
+  return source.type === "base64" ? source.data : Buffer.from(source.data.buffer, source.data.byteOffset, source.data.byteLength).toString(
+    "base64"
+  );
+}
+function geminiInteractionContent(parts, model) {
+  const content = [];
+  for (const part of parts) {
+    if (part.type === "text") {
+      content.push({ type: "text", text: part.text });
+      continue;
+    }
+    const { source } = part;
+    if (source.type === "provider-file") {
+      if (source.provider !== "google") {
+        throw new UnsupportedModelInputError({
+          provider: "google",
+          model,
+          modality: "image",
+          source: "provider-file"
+        });
+      }
+      if (!source.mediaType) {
+        throw new UnsupportedModelInputError({
+          provider: "google",
+          model,
+          modality: "image",
+          source: "provider-file",
+          feature: "Interactions URI image mediaType"
+        });
+      }
+      content.push({
+        type: "image",
+        uri: source.reference,
+        mime_type: source.mediaType
+      });
+    } else if (source.type === "url") {
+      throw new UnsupportedModelInputError({
+        provider: "google",
+        model,
+        modality: "image",
+        source: "url",
+        feature: "direct URL image input; pass bytes/base64 or a Gemini provider-file"
+      });
+    } else {
+      content.push({ type: "image", data: geminiImageBase64(source), mime_type: source.mediaType });
+    }
+    if (part.label) content.push({ type: "text", text: `[Image: ${part.label}]` });
+  }
+  return content;
+}
 var GEMINI_DISALLOWED_SCHEMA_KEYS = /* @__PURE__ */ new Set([
   "additionalProperties",
   "$schema",
@@ -3567,6 +3959,7 @@ var GEMINI_PRICING = {
   "gemini-3.5-flash-lite": { input: 3e-7, cached: 3e-8, output: 25e-7 },
   "gemini-3.6-flash": { input: 15e-7, cached: 15e-8, output: 75e-7 }
 };
+var GEMINI_INTERACTIONS_IMAGE_MODELS = /* @__PURE__ */ new Set(["gemini-3.7-flash"]);
 function isValidTokenCount2(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
@@ -3654,7 +4047,10 @@ var GEMINI_3X_MIN_THINKING_LEVEL = /* @__PURE__ */ new Map([
   ["gemini-3.1-flash-lite-preview", "minimal"],
   ["gemini-3.5-flash", "minimal"],
   ["gemini-3.5-flash-lite", "minimal"],
-  ["gemini-3.6-flash", "minimal"]
+  ["gemini-3.6-flash", "minimal"],
+  // L4 live evidence: Interactions gemini-3.7-flash accepts low/medium/high,
+  // but rejects minimal. Keep this exact entry isolated from legacy aliases.
+  ["gemini-3.7-flash", "low"]
 ]);
 var GEMINI_MODELS_WITHOUT_PORTABLE_TEMPERATURE = /* @__PURE__ */ new Set([
   "gemini-3.5-flash-lite",
@@ -3681,6 +4077,61 @@ function warnGemini3xEffortNone(model) {
 }
 var GeminiProvider = class {
   name = "google";
+  inputCapabilities(model) {
+    return GEMINI_INTERACTIONS_IMAGE_MODELS.has(model) ? { image: { sources: ["bytes", "base64", "provider-file"] } } : {};
+  }
+  validateInput(request) {
+    const effectiveModel = typeof request.providerOptions?.model === "string" ? request.providerOptions.model : request.model;
+    const fail = (source, feature) => {
+      throw new UnsupportedModelInputError({
+        provider: this.name,
+        model: effectiveModel || request.model,
+        modality: "image",
+        ...source ? { source } : {},
+        ...feature ? { feature } : {}
+      });
+    };
+    if (!GEMINI_INTERACTIONS_IMAGE_MODELS.has(effectiveModel)) {
+      fail(void 0, "image input for this model");
+    }
+    if (request.providerOptions) {
+      const forbidden = [
+        "input",
+        "contents",
+        "messages",
+        "previous_interaction_id",
+        "background",
+        "stream",
+        "store"
+      ].find((key) => key in request.providerOptions);
+      if (forbidden) fail(void 0, `raw ${forbidden} providerOptions`);
+    }
+    for (const message of request.history) {
+      if (!Array.isArray(message.content)) continue;
+      if (message.role !== "user") fail(void 0, "rich non-user history");
+      for (const part of message.content) {
+        if (part.type !== "image") continue;
+        if (part.source.type === "url")
+          fail("url", "direct URL image input; pass bytes/base64 or a Gemini provider-file");
+        if (part.source.type === "provider-file" && part.source.provider !== this.name)
+          fail("provider-file");
+        if (part.source.type === "provider-file" && !part.source.mediaType)
+          fail("provider-file", "Interactions URI image mediaType");
+      }
+    }
+    if (Array.isArray(request.input)) {
+      for (const part of request.input) {
+        if (part.type !== "image") continue;
+        if (part.source.type === "url")
+          fail("url", "direct URL image input; pass bytes/base64 or a Gemini provider-file");
+        if (part.source.type === "provider-file" && part.source.provider !== this.name)
+          fail("provider-file");
+        if (part.source.type === "provider-file" && !part.source.mediaType)
+          fail("provider-file", "Interactions URI image mediaType");
+      }
+    }
+    return { effectiveModel };
+  }
   /** Gemini accepts a `responseSchema` but `sanitizeSchemaForGemini` strips
    *  keywords it doesn't support (`$ref`/`$defs`/`additionalProperties`/…), so a
    *  derived schema can lose constraints — lossy, not faithful. */
@@ -3719,6 +4170,7 @@ var GeminiProvider = class {
   // chat - non-streaming completion
   // ---------------------------------------------------------------------------
   async chat(messages, options) {
+    if (hasRichGeminiMessages(messages)) return this.chatInteraction(messages, options);
     const body = this.buildRequestBody(messages, options);
     const pricingContext = this.pricingContext(this.requestModel(options), body);
     this.assertSafeGemini3Continuation(messages, pricingContext.model);
@@ -3751,6 +4203,10 @@ var GeminiProvider = class {
   // stream - SSE streaming completion
   // ---------------------------------------------------------------------------
   async *stream(messages, options) {
+    if (hasRichGeminiMessages(messages)) {
+      yield* this.streamInteraction(messages, options);
+      return;
+    }
     const body = this.buildRequestBody(messages, options);
     const pricingContext = this.pricingContext(this.requestModel(options), body);
     this.assertSafeGemini3Continuation(messages, pricingContext.model);
@@ -3782,6 +4238,339 @@ var GeminiProvider = class {
     yield* this.parseSSEStream(res.body, pricingContext);
   }
   // ---------------------------------------------------------------------------
+  // Rich image requests use Gemini Interactions. It is deliberately stateless:
+  // Axl sends the complete application-owned history and never asks Google to
+  // retain an interaction or follow a previous_interaction_id.
+  // ---------------------------------------------------------------------------
+  async chatInteraction(messages, options) {
+    this.assertSafeInteractionOptions(options);
+    const body = this.buildInteractionRequestBody(messages, options, false);
+    const headers = this.buildHeaders(await this.resolveKey());
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/interactions`,
+      { method: "POST", headers, body: JSON.stringify(body), signal: options.signal },
+      { governor: this.governor, provider: this.name }
+    );
+    if (!res.ok) {
+      const errorBody = await res.text();
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message: this.extractErrorMessage(errorBody, res.status),
+        body: errorBody
+      });
+    }
+    return this.parseInteractionResponse(await res.json());
+  }
+  async *streamInteraction(messages, options) {
+    this.assertSafeInteractionOptions(options);
+    const body = this.buildInteractionRequestBody(messages, options, true);
+    const headers = this.buildHeaders(await this.resolveKey());
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/interactions?alt=sse`,
+      { method: "POST", headers, body: JSON.stringify(body), signal: options.signal },
+      { governor: this.governor, provider: this.name }
+    );
+    if (!res.ok) {
+      const errorBody = await res.text();
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message: this.extractErrorMessage(errorBody, res.status),
+        body: errorBody
+      });
+    }
+    if (!res.body) throw new Error("Gemini Interactions stream has no body");
+    yield* this.parseInteractionSSEStream(res.body);
+  }
+  buildInteractionRequestBody(messages, options, stream) {
+    const model = this.requestModel(options);
+    const systemInstruction = messages.filter((message) => message.role === "system").map((message) => typeof message.content === "string" ? message.content : "").filter(Boolean).join("\n\n");
+    const body = {
+      model,
+      input: this.mapInteractionInput(
+        messages.filter((message) => message.role !== "system"),
+        model
+      ),
+      stream
+    };
+    if (systemInstruction) body.system_instruction = systemInstruction;
+    if (options.tools?.length) {
+      body.tools = options.tools.map((tool2) => ({
+        type: "function",
+        name: tool2.function.name,
+        description: tool2.function.description,
+        parameters: sanitizeSchemaForGemini(tool2.function.parameters)
+      }));
+    }
+    const generationConfig = {};
+    if (options.maxTokens !== void 0) generationConfig.max_output_tokens = options.maxTokens;
+    if (options.stop) generationConfig.stop_sequences = options.stop;
+    if (options.toolChoice !== void 0) {
+      generationConfig.tool_choice = typeof options.toolChoice === "string" ? options.toolChoice === "required" ? "any" : options.toolChoice : { allowed_tools: { mode: "any", tools: [options.toolChoice.function.name] } };
+    }
+    const thinking = resolveThinkingOptions(options);
+    if (thinking.thinkingDisabled) {
+      generationConfig.thinking_level = isGemini3x(model) ? minThinkingLevel(model) : "minimal";
+    } else if (thinking.hasBudgetOverride) {
+      generationConfig.thinking_level = budgetToThinkingLevel(thinking.thinkingBudget);
+    } else if (thinking.activeEffort) {
+      generationConfig.thinking_level = isGemini3x(model) ? THINKING_LEVELS[thinking.activeEffort] ?? "medium" : budgetToThinkingLevel(THINKING_BUDGETS2[thinking.activeEffort] ?? 5e3);
+    }
+    if (thinking.includeThoughts) generationConfig.thinking_summaries = "auto";
+    if (Object.keys(generationConfig).length) body.generation_config = generationConfig;
+    if (options.responseFormat?.type && options.responseFormat.type !== "text") {
+      body.response_format = {
+        type: "text",
+        mime_type: "application/json",
+        ...options.responseFormat.type === "json_schema" ? { schema: sanitizeSchemaForGemini(options.responseFormat.json_schema.schema) } : {}
+      };
+    }
+    if (options.providerOptions) {
+      const overrides = { ...options.providerOptions };
+      delete overrides.model;
+      delete overrides.input;
+      delete overrides.contents;
+      delete overrides.messages;
+      delete overrides.previous_interaction_id;
+      delete overrides.background;
+      delete overrides.stream;
+      delete overrides.store;
+      const rawGenerationConfig = overrides.generation_config;
+      if (rawGenerationConfig && typeof rawGenerationConfig === "object" && !Array.isArray(rawGenerationConfig)) {
+        const generationConfigOverrides = { ...rawGenerationConfig };
+        delete generationConfigOverrides.temperature;
+        if (Object.keys(generationConfigOverrides).length)
+          overrides.generation_config = generationConfigOverrides;
+        else delete overrides.generation_config;
+      }
+      Object.assign(body, overrides);
+    }
+    body.stream = stream;
+    body.store = false;
+    return body;
+  }
+  assertSafeInteractionOptions(options) {
+    const model = this.requestModel(options);
+    const fail = (feature) => {
+      throw new UnsupportedModelInputError({
+        provider: this.name,
+        model,
+        modality: "image",
+        feature
+      });
+    };
+    if (!GEMINI_INTERACTIONS_IMAGE_MODELS.has(model)) fail("image input for this model");
+    const forbidden = [
+      "input",
+      "contents",
+      "messages",
+      "previous_interaction_id",
+      "background",
+      "stream",
+      "store"
+    ].find((key) => key in (options.providerOptions ?? {}));
+    if (forbidden) fail(`raw ${forbidden} providerOptions`);
+  }
+  mapInteractionInput(messages, model) {
+    const steps = [];
+    for (const message of messages) {
+      if (message.role === "user") {
+        steps.push({
+          type: "user_input",
+          content: Array.isArray(message.content) ? geminiInteractionContent(message.content, model) : [{ type: "text", text: message.content }]
+        });
+      } else if (message.role === "assistant") {
+        const nativeSteps = message.providerMetadata?.geminiInteractionSteps;
+        if (Array.isArray(nativeSteps) && nativeSteps.every(isGeminiInteractionStep)) {
+          steps.push(...nativeSteps);
+          continue;
+        }
+        if (typeof message.content === "string" && message.content) {
+          steps.push({ type: "model_output", content: [{ type: "text", text: message.content }] });
+        }
+        for (const call of message.tool_calls ?? []) {
+          steps.push({
+            type: "function_call",
+            id: call.id,
+            name: call.function.name,
+            arguments: safeJsonObject(call.function.arguments)
+          });
+        }
+      } else if (message.role === "tool") {
+        steps.push({
+          type: "function_result",
+          call_id: message.tool_call_id ?? "",
+          result: [
+            { type: "text", text: typeof message.content === "string" ? message.content : "" }
+          ]
+        });
+      }
+    }
+    return steps;
+  }
+  parseInteractionResponse(json) {
+    let content = "";
+    let thinkingContent = "";
+    const toolCalls = [];
+    for (const step of json.steps ?? []) {
+      if (step.type === "model_output") content += interactionText(step.content);
+      else if (step.type === "thought") thinkingContent += interactionText(step.summary);
+      else if (step.type === "function_call" && step.id && step.name) {
+        toolCalls.push({
+          id: step.id,
+          type: "function",
+          function: { name: step.name, arguments: JSON.stringify(step.arguments ?? {}) }
+        });
+      }
+    }
+    this.assertInteractionTerminalStatus(json.status, toolCalls.length);
+    const usage = normalizeInteractionUsage(json.usage);
+    return {
+      content,
+      thinking_content: thinkingContent || void 0,
+      tool_calls: toolCalls.length ? toolCalls : void 0,
+      usage,
+      // Interactions returns modality usage but no authoritative monetary cost.
+      cost: void 0,
+      providerMetadata: json.steps?.length ? { geminiInteractionSteps: json.steps.filter(isGeminiInteractionStep) } : void 0
+    };
+  }
+  async *parseInteractionSSEStream(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const steps = /* @__PURE__ */ new Map();
+    const argumentBuffers = /* @__PURE__ */ new Map();
+    const stopped = /* @__PURE__ */ new Set();
+    let completed = false;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("data: ")) continue;
+          if (trimmed.slice(6) === "[DONE]") continue;
+          let event;
+          try {
+            event = JSON.parse(trimmed.slice(6));
+          } catch {
+            continue;
+          }
+          if (event.event_type === "error") {
+            throw new Error(event.error?.message ?? "Gemini Interactions stream failed");
+          }
+          if (event.event_type === "step.start" && event.step) {
+            const index = event.index;
+            if (index === void 0 || steps.has(index)) {
+              throw new Error("Gemini Interactions stream contained an invalid step.start index");
+            }
+            const step = cloneInteractionStep(event.step);
+            steps.set(index, step);
+            if (step.type === "model_output") {
+              for (const text of interactionTextChunks(step.content)) {
+                yield { type: "text_delta", content: text };
+              }
+            } else if (step.type === "thought") {
+              for (const text of interactionTextChunks(step.summary)) {
+                yield { type: "thinking_delta", content: text };
+              }
+            }
+            if (step.type === "function_call" && step.id && step.name) {
+              argumentBuffers.set(index, "");
+              yield { type: "tool_call_delta", id: step.id, name: step.name };
+            }
+          } else if (event.event_type === "step.delta" && event.delta) {
+            const delta = event.delta;
+            const index = event.index;
+            if (index === void 0 || stopped.has(index)) {
+              throw new Error("Gemini Interactions stream delta arrived outside an active step");
+            }
+            const step = steps.get(index);
+            if (!step)
+              throw new Error("Gemini Interactions stream delta arrived before step.start");
+            if (delta.type === "text" && typeof delta.text === "string" && step.type === "model_output") {
+              appendInteractionContent(step, "content", { type: "text", text: delta.text });
+              yield { type: "text_delta", content: delta.text };
+            } else if (delta.type === "thought_summary" && step.type === "thought" && delta.content) {
+              appendInteractionContent(step, "summary", delta.content);
+              for (const text of interactionTextChunks([delta.content])) {
+                yield { type: "thinking_delta", content: text };
+              }
+            } else if (delta.type === "thought_signature" && step.type === "thought" && typeof delta.signature === "string") {
+              step.signature = delta.signature;
+            } else if (delta.type === "arguments_delta" && step.type === "function_call" && typeof delta.arguments === "string") {
+              argumentBuffers.set(index, (argumentBuffers.get(index) ?? "") + delta.arguments);
+              if (step.id)
+                yield { type: "tool_call_delta", id: step.id, arguments: delta.arguments };
+            }
+          } else if (event.event_type === "step.stop") {
+            const index = event.index;
+            const step = index === void 0 ? void 0 : steps.get(index);
+            if (step === void 0 || stopped.has(index)) {
+              throw new Error("Gemini Interactions stream contained an invalid step.stop index");
+            }
+            if (step.type === "function_call") {
+              const rawArguments = argumentBuffers.get(index) ?? "";
+              if (rawArguments) {
+                try {
+                  const parsed = JSON.parse(rawArguments);
+                  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    throw new Error("not an object");
+                  }
+                  step.arguments = parsed;
+                } catch {
+                  throw new Error(
+                    "Gemini Interactions function_call arguments were not valid JSON"
+                  );
+                }
+              }
+            }
+            stopped.add(index);
+          } else if (event.event_type === "interaction.completed") {
+            if (steps.size !== stopped.size) {
+              throw new Error("Gemini Interactions stream completed before all steps stopped");
+            }
+            const toolCallCount = [...steps.values()].filter(
+              (step) => step.type === "function_call" && !!step.id && !!step.name
+            ).length;
+            this.assertInteractionTerminalStatus(event.interaction?.status, toolCallCount);
+            completed = true;
+            yield {
+              type: "done",
+              usage: normalizeInteractionUsage(event.interaction?.usage),
+              providerMetadata: steps.size ? {
+                geminiInteractionSteps: [...steps.entries()].sort(([a], [b]) => a - b).map(([, step]) => step)
+              } : void 0
+            };
+            return;
+          }
+        }
+      }
+      if (!completed)
+        throw new Error("Gemini Interactions stream ended before interaction.completed");
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  assertInteractionTerminalStatus(status, toolCallCount) {
+    if (status === "completed") return;
+    if (status === "requires_action" && toolCallCount > 0) return;
+    const normalizedStatus = typeof status === "string" ? status : "unknown";
+    throw new ProviderError({
+      provider: this.name,
+      status: 0,
+      retryable: false,
+      message: `Gemini Interactions ended with non-success status: ${normalizedStatus}`
+    });
+  }
+  // ---------------------------------------------------------------------------
   // Internal: request building
   // ---------------------------------------------------------------------------
   buildHeaders(apiKey) {
@@ -4036,14 +4825,15 @@ var GeminiProvider = class {
     }
     const result = [];
     for (const msg of messages) {
+      const text = typeof msg.content === "string" ? msg.content : "";
       if (msg.role === "assistant") {
         const rawParts = msg.providerMetadata?.geminiParts;
         if (rawParts && rawParts.length > 0) {
           result.push({ role: "model", parts: rawParts });
         } else {
           const parts = [];
-          if (msg.content) {
-            parts.push({ text: msg.content });
+          if (text) {
+            parts.push({ text });
           }
           if (msg.tool_calls && msg.tool_calls.length > 0) {
             for (const tc of msg.tool_calls) {
@@ -4069,7 +4859,7 @@ var GeminiProvider = class {
         const functionName = (msg.tool_call_id ? geminiNativeNames.get(msg.tool_call_id) : void 0) ?? toolCallIdToName.get(msg.tool_call_id) ?? "unknown";
         const functionResponse = {
           name: functionName,
-          response: parseGeminiFunctionResponse(msg.content)
+          response: parseGeminiFunctionResponse(text)
         };
         if (msg.tool_call_id && geminiNativeIds.has(msg.tool_call_id)) {
           functionResponse.id = msg.tool_call_id;
@@ -4079,7 +4869,7 @@ var GeminiProvider = class {
           parts: [{ functionResponse }]
         });
       } else if (msg.role === "user") {
-        result.push({ role: "user", parts: [{ text: msg.content }] });
+        result.push({ role: "user", parts: [{ text }] });
       }
     }
     return this.mergeConsecutiveRoles(result);
@@ -4267,6 +5057,56 @@ var GeminiProvider = class {
     }
   }
 };
+function isGeminiInteractionStep(value) {
+  return value !== null && typeof value === "object" && ["user_input", "model_output", "thought", "function_call", "function_result"].includes(
+    value.type
+  );
+}
+function interactionText(content) {
+  return content?.map((part) => part.type === "text" && typeof part.text === "string" ? part.text : "").join("") ?? "";
+}
+function interactionTextChunks(content) {
+  return content?.flatMap(
+    (part) => part.type === "text" && typeof part.text === "string" ? [part.text] : []
+  ) ?? [];
+}
+function cloneInteractionStep(step) {
+  return JSON.parse(JSON.stringify(step));
+}
+function appendInteractionContent(step, field, content) {
+  const existing = step[field] ?? [];
+  const last = existing.at(-1);
+  if (content.type === "text" && last?.type === "text" && typeof content.text === "string" && typeof last.text === "string") {
+    last.text += content.text;
+  } else {
+    existing.push(content);
+  }
+  step[field] = existing;
+}
+function safeJsonObject(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function normalizeInteractionUsage(usage) {
+  if (!usage || !isValidTokenCount2(usage.total_input_tokens) || !isValidTokenCount2(usage.total_output_tokens) || !isValidTokenCount2(usage.total_tokens)) {
+    return void 0;
+  }
+  const cached = usage.total_cached_tokens;
+  const thinking = usage.total_thought_tokens;
+  if (cached !== void 0 && (!isValidTokenCount2(cached) || cached > usage.total_input_tokens) || thinking !== void 0 && !isValidTokenCount2(thinking))
+    return void 0;
+  return {
+    prompt_tokens: usage.total_input_tokens,
+    completion_tokens: usage.total_output_tokens,
+    total_tokens: usage.total_tokens,
+    ...cached ? { cached_tokens: cached } : {},
+    ...thinking ? { reasoning_tokens: thinking } : {}
+  };
+}
 
 // src/providers/profiles/openrouter.ts
 var OPENROUTER_PROFILE = {
@@ -4698,68 +5538,1220 @@ var ProviderRegistry = class {
     if (cached) return cached;
     const factory = this.factories.get(name);
     if (factory) {
-      const instance = factory(config);
-      this.instances.set(name, instance);
-      return instance;
-    }
-    if (this.fallbackInstance) {
-      return this.fallbackInstance;
-    }
-    throw new Error(`Unknown provider "${name}". Registered providers: ${this.list().join(", ")}`);
+      const instance = factory(config);
+      this.instances.set(name, instance);
+      return instance;
+    }
+    if (this.fallbackInstance) {
+      return this.fallbackInstance;
+    }
+    throw new Error(`Unknown provider "${name}". Registered providers: ${this.list().join(", ")}`);
+  }
+  /**
+   * Resolve a "provider:model" URI string into a Provider instance and model name.
+   *
+   * Supported formats:
+   *   - "openai:gpt-4o"        -> provider=openai, model=gpt-4o
+   *   - "anthropic:claude-3"   -> provider=anthropic, model=claude-3
+   *   - "gpt-4o"               -> uses defaultProvider from config, model=gpt-4o
+   *   - undefined / empty      -> uses defaultProvider and defaultModel from config
+   *
+   * @param uri  Provider:model string, or just a model name
+   * @param config  Axl configuration for provider options and defaults
+   */
+  resolve(uri, config = {}) {
+    if (!uri) {
+      const providerName2 = config.defaultProvider ?? "openai";
+      const model2 = config.defaultModel ?? "gpt-4o";
+      return { provider: this.get(providerName2, config), model: model2 };
+    }
+    const colonIndex = uri.indexOf(":");
+    if (colonIndex === -1) {
+      const providerName2 = config.defaultProvider ?? "openai";
+      return { provider: this.get(providerName2, config), model: uri };
+    }
+    const providerName = uri.slice(0, colonIndex);
+    const model = uri.slice(colonIndex + 1);
+    if (!providerName || !model) {
+      throw new Error(
+        `Invalid provider URI "${uri}". Expected format: "provider:model" (e.g. "openai:gpt-4o")`
+      );
+    }
+    return { provider: this.get(providerName, config), model };
+  }
+  /**
+   * Clear all cached provider instances. Useful for testing or reconfiguration.
+   */
+  clearCache() {
+    this.instances.clear();
+  }
+  /**
+   * Clear all registered factories (including built-ins).
+   * Useful for test runtimes where only explicitly registered instances should be used.
+   */
+  clearFactories() {
+    this.factories.clear();
+  }
+};
+var defaultRegistry = new ProviderRegistry();
+
+// src/transcription.ts
+var MAX_INLINE_TRANSCRIPTION_BYTES = 25 * 1024 * 1024;
+var RESERVED_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "model",
+  "audio",
+  "signal",
+  "cleanup",
+  "cleanupStatus",
+  "usage",
+  "cost",
+  "pricingStatus",
+  "accounting"
+]);
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function cloneValue(value) {
+  try {
+    return structuredClone(value);
+  } catch {
+    throw new InvalidTranscriptionInputError("Transcription options must be structured-cloneable");
+  }
+}
+function normalizeTranscriptionRequest(request) {
+  if (!request || typeof request !== "object" || !nonEmptyString(request.model)) {
+    throw new InvalidTranscriptionInputError("A transcription model URI is required");
+  }
+  const audio = request.audio;
+  if (!audio || typeof audio !== "object") {
+    throw new InvalidTranscriptionInputError("A transcription audio source is required");
+  }
+  let normalizedAudio;
+  if (audio.type === "bytes") {
+    if (!(audio.data instanceof Uint8Array) || audio.data.byteLength === 0 || !nonEmptyString(audio.mediaType)) {
+      throw new InvalidTranscriptionInputError(
+        "Inline transcription bytes require nonempty data and mediaType"
+      );
+    }
+    if (audio.data.byteLength > MAX_INLINE_TRANSCRIPTION_BYTES) {
+      throw new InvalidTranscriptionInputError(
+        "Inline transcription audio must not exceed 25 MiB; chunk it or use a supported provider-file source"
+      );
+    }
+    normalizedAudio = {
+      type: "bytes",
+      data: new Uint8Array(audio.data),
+      mediaType: audio.mediaType
+    };
+  } else if (audio.type === "base64") {
+    if (!nonEmptyString(audio.data) || !nonEmptyString(audio.mediaType)) {
+      throw new InvalidTranscriptionInputError(
+        "Inline base64 transcription audio requires data and mediaType"
+      );
+    }
+    if (audio.data.length > 4 * Math.ceil(MAX_INLINE_TRANSCRIPTION_BYTES / 3)) {
+      throw new InvalidTranscriptionInputError(
+        "Inline transcription audio must not exceed 25 MiB; chunk it or use a supported provider-file source"
+      );
+    }
+    let decoded;
+    try {
+      decoded = Uint8Array.from(Buffer.from(audio.data, "base64"));
+    } catch {
+      throw new InvalidTranscriptionInputError(
+        "Transcription base64 must be canonical and decode to audio"
+      );
+    }
+    if (!decoded.byteLength || Buffer.from(decoded).toString("base64") !== audio.data) {
+      throw new InvalidTranscriptionInputError(
+        "Transcription base64 must be canonical and decode to nonempty audio"
+      );
+    }
+    if (decoded.byteLength > MAX_INLINE_TRANSCRIPTION_BYTES) {
+      throw new InvalidTranscriptionInputError(
+        "Inline transcription audio must not exceed 25 MiB; chunk it or use a supported provider-file source"
+      );
+    }
+    normalizedAudio = { type: "base64", data: audio.data, mediaType: audio.mediaType };
+  } else if (audio.type === "provider-file") {
+    if (!nonEmptyString(audio.provider) || !nonEmptyString(audio.reference)) {
+      throw new InvalidTranscriptionInputError(
+        "A provider-file transcription source requires provider and reference"
+      );
+    }
+    if (audio.mediaType !== void 0 && !nonEmptyString(audio.mediaType)) {
+      throw new InvalidTranscriptionInputError(
+        "Transcription provider-file mediaType must be nonempty when supplied"
+      );
+    }
+    normalizedAudio = {
+      type: "provider-file",
+      provider: audio.provider,
+      reference: audio.reference,
+      ...audio.mediaType !== void 0 ? { mediaType: audio.mediaType } : {}
+    };
+  } else {
+    throw new InvalidTranscriptionInputError(
+      "Transcription audio must be bytes, base64, or provider-file"
+    );
+  }
+  if (request.language !== void 0 && !nonEmptyString(request.language)) {
+    throw new InvalidTranscriptionInputError(
+      "Transcription language must be nonempty when supplied"
+    );
+  }
+  if (request.timestamps !== void 0 && request.timestamps !== "segment" && request.timestamps !== "word") {
+    throw new InvalidTranscriptionInputError("Transcription timestamps must be segment or word");
+  }
+  if (request.diarization !== void 0 && typeof request.diarization !== "boolean") {
+    throw new InvalidTranscriptionInputError("Transcription diarization must be boolean");
+  }
+  if (request.providerOptions !== void 0) {
+    if (!request.providerOptions || Array.isArray(request.providerOptions) || typeof request.providerOptions !== "object") {
+      throw new InvalidTranscriptionInputError("Transcription providerOptions must be an object");
+    }
+    for (const key of Object.keys(request.providerOptions)) {
+      if (RESERVED_PROVIDER_OPTION_KEYS.has(key)) {
+        throw new InvalidTranscriptionInputError(
+          "Transcription providerOptions cannot override reserved operation fields"
+        );
+      }
+    }
+  }
+  return {
+    model: request.model,
+    audio: normalizedAudio,
+    ...request.language !== void 0 ? { language: request.language } : {},
+    ...request.timestamps !== void 0 ? { timestamps: request.timestamps } : {},
+    ...request.diarization !== void 0 ? { diarization: request.diarization } : {},
+    ...request.providerOptions !== void 0 ? { providerOptions: cloneValue(request.providerOptions) } : {}
+  };
+}
+function cloneTranscript(transcript) {
+  if (!transcript || typeof transcript !== "object" || typeof transcript.text !== "string") {
+    throw new InvalidTranscriptionInputError(
+      "Transcription provider returned an invalid transcript"
+    );
+  }
+  const cloned = cloneValue(transcript);
+  const accounting = normalizeTranscriptionAccounting(cloned.usage, cloned.pricingStatus);
+  return {
+    text: cloned.text,
+    ...cloned.detectedLanguages ? { detectedLanguages: cloned.detectedLanguages } : {},
+    ...cloned.segments ? { segments: cloned.segments } : {},
+    ...cloned.words ? { words: cloned.words } : {},
+    ...accounting.usage ? { usage: accounting.usage } : {},
+    ...accounting.pricingStatus ? { pricingStatus: accounting.pricingStatus } : {},
+    ...cloned.providerMetadata ? { providerMetadata: cloned.providerMetadata } : {}
+  };
+}
+function normalizeTranscriptionAccounting(usageValue, pricingValue) {
+  const value = usageValue && typeof usageValue === "object" ? usageValue : void 0;
+  const number = (key) => {
+    const candidate = value?.[key];
+    return typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0 ? candidate : void 0;
+  };
+  const audioSeconds = number("audioSeconds");
+  const inputTokens = number("inputTokens");
+  const outputTokens = number("outputTokens");
+  const totalTokens = number("totalTokens");
+  const reportedCost = number("cost");
+  const usage = value && (audioSeconds !== void 0 || inputTokens !== void 0 || outputTokens !== void 0 || totalTokens !== void 0 || reportedCost !== void 0) ? {
+    ...audioSeconds !== void 0 ? { audioSeconds } : {},
+    ...inputTokens !== void 0 ? { inputTokens } : {},
+    ...outputTokens !== void 0 ? { outputTokens } : {},
+    ...totalTokens !== void 0 ? { totalTokens } : {},
+    ...reportedCost !== void 0 ? { cost: reportedCost } : {}
+  } : void 0;
+  const hasWork = (audioSeconds ?? 0) > 0 || (inputTokens ?? 0) > 0 || (outputTokens ?? 0) > 0 || (totalTokens ?? 0) > 0;
+  const requested = pricingValue === "priced" || pricingValue === "unpriced" || pricingValue === "zero" ? pricingValue : void 0;
+  const cost = requested === "zero" && (reportedCost === void 0 || reportedCost === 0) ? 0 : reportedCost;
+  const pricingStatus = requested === "zero" && (reportedCost === void 0 || reportedCost === 0) ? "zero" : requested === "priced" && cost !== void 0 ? "priced" : requested === "unpriced" && cost === void 0 ? "unpriced" : cost !== void 0 ? "priced" : hasWork || requested === "unpriced" || requested === "priced" ? "unpriced" : void 0;
+  const tokens = inputTokens !== void 0 || outputTokens !== void 0 ? {
+    ...inputTokens !== void 0 ? { input: inputTokens } : {},
+    ...outputTokens !== void 0 ? { output: outputTokens } : {}
+  } : void 0;
+  return {
+    ...usage ? { usage } : {},
+    ...pricingStatus ? { pricingStatus } : {},
+    ...cost !== void 0 ? { cost } : {},
+    ...tokens ? { tokens } : {},
+    hasWork
+  };
+}
+
+// src/providers/transcription-utils.ts
+var OPENAI_TRANSCRIPTION_MODEL = "gpt-transcribe";
+var GEMINI_TRANSCRIPTION_MODEL = "gemini-3.5-transcribe";
+var OPENROUTER_TRANSCRIPTION_MODEL = "openai/whisper-1";
+function requireExactTranscriptionModel(provider, model, expected) {
+  if (model !== expected) {
+    throw new UnsupportedTranscriptionInputError({
+      provider,
+      model,
+      feature: "this transcription model"
+    });
+  }
+}
+function inlineAudioBytes(audio) {
+  if (audio.type === "bytes") return new Uint8Array(audio.data);
+  if (audio.type === "base64") return Uint8Array.from(Buffer.from(audio.data, "base64"));
+  throw new UnsupportedTranscriptionInputError({
+    provider: audio.provider,
+    model: "",
+    feature: "provider-file transcription input"
+  });
+}
+function requireNoProviderFile(audio, provider, model) {
+  if (audio.type === "provider-file") {
+    throw new UnsupportedTranscriptionInputError({
+      provider,
+      model,
+      feature: "provider-file transcription input"
+    });
+  }
+}
+function assertOnlyProviderOptions(request, provider, model, allowed) {
+  const options = request.providerOptions ?? {};
+  for (const key of Object.keys(options)) {
+    if (!allowed.includes(key)) {
+      throw new InvalidTranscriptionInputError(
+        `Unsupported ${provider} transcription provider option for model '${model}'`
+      );
+    }
+  }
+  return options;
+}
+function transcriptUsage(value) {
+  const source = value && typeof value === "object" ? value : {};
+  const number = (...keys) => {
+    for (const key of keys) {
+      const candidate = source[key];
+      if (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0)
+        return candidate;
+    }
+    return void 0;
+  };
+  const inputTokens = number("total_input_tokens", "input_tokens", "prompt_tokens", "inputTokens");
+  const outputTokens = number(
+    "total_output_tokens",
+    "output_tokens",
+    "completion_tokens",
+    "outputTokens"
+  );
+  const totalTokens = number("total_tokens", "totalTokens");
+  const audioSeconds = number("seconds", "audio_seconds", "audioSeconds", "duration_seconds");
+  const cost = number("cost");
+  const usage = inputTokens !== void 0 || outputTokens !== void 0 || totalTokens !== void 0 || audioSeconds !== void 0 || cost !== void 0 ? {
+    ...audioSeconds !== void 0 ? { audioSeconds } : {},
+    ...inputTokens !== void 0 ? { inputTokens } : {},
+    ...outputTokens !== void 0 ? { outputTokens } : {},
+    ...totalTokens !== void 0 ? { totalTokens } : {},
+    ...cost !== void 0 ? { cost } : {}
+  } : void 0;
+  const hasWork = (audioSeconds ?? 0) > 0 || (inputTokens ?? 0) > 0 || (outputTokens ?? 0) > 0 || (totalTokens ?? 0) > 0;
+  return {
+    ...usage ? { usage } : {},
+    ...cost !== void 0 ? { pricingStatus: "priced" } : hasWork ? { pricingStatus: "unpriced" } : {}
+  };
+}
+function safeProviderMessage(provider, status, body) {
+  try {
+    const parsed = JSON.parse(body);
+    const message = parsed.error?.message ?? parsed.message;
+    if (typeof message === "string")
+      return `${provider} transcription API error (${status}): ${message}`;
+  } catch {
+  }
+  return `${provider} transcription API error (${status})`;
+}
+function attachTranscriptionFailureMetadata(error, metadata) {
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value !== void 0) Object.defineProperty(error, key, { enumerable: true, value });
+  }
+  return error;
+}
+
+// src/providers/openai-transcription.ts
+var OPENAI_FILE_EXTENSIONS = {
+  "audio/flac": "flac",
+  "audio/m4a": "m4a",
+  "audio/mp3": "mp3",
+  "audio/mp4": "mp4",
+  "audio/mpeg": "mp3",
+  "audio/mpga": "mpga",
+  "audio/ogg": "ogg",
+  "audio/wav": "wav",
+  "audio/webm": "webm"
+};
+var OpenAITranscriptionProvider = class {
+  name = "openai-transcription";
+  baseUrl;
+  apiKeySource;
+  governor;
+  constructor(options = {}) {
+    this.apiKeySource = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
+    this.baseUrl = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      "OpenAI transcription provider",
+      options.dangerouslyAllowInsecureHttp
+    );
+    this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
+  }
+  capabilities(model) {
+    return model === OPENAI_TRANSCRIPTION_MODEL ? { sources: ["bytes", "base64"] } : void 0;
+  }
+  async transcribe(request) {
+    requireExactTranscriptionModel(this.name, request.model, OPENAI_TRANSCRIPTION_MODEL);
+    requireNoProviderFile(request.audio, this.name, request.model);
+    if (request.audio.type === "provider-file")
+      throw new UnsupportedTranscriptionInputError({
+        provider: this.name,
+        model: request.model,
+        feature: "provider-file transcription input"
+      });
+    const options = assertOnlyProviderOptions(request, this.name, request.model, [
+      "temperature",
+      "prompt"
+    ]);
+    if (options.temperature !== void 0 && (typeof options.temperature !== "number" || !Number.isFinite(options.temperature) || options.temperature < 0 || options.temperature > 1))
+      throw new InvalidTranscriptionInputError(
+        "OpenAI transcription temperature must be a number between 0 and 1"
+      );
+    if (options.prompt !== void 0 && typeof options.prompt !== "string")
+      throw new InvalidTranscriptionInputError("OpenAI transcription prompt must be a string");
+    const mediaType2 = request.audio.mediaType;
+    const extension = OPENAI_FILE_EXTENSIONS[mediaType2];
+    if (!extension)
+      throw new UnsupportedTranscriptionInputError({
+        provider: this.name,
+        model: request.model,
+        feature: "this audio media type"
+      });
+    const bytes = inlineAudioBytes(request.audio);
+    if (bytes.byteLength > MAX_INLINE_TRANSCRIPTION_BYTES)
+      throw new InvalidTranscriptionInputError("OpenAI transcription audio must not exceed 25 MiB");
+    const form = new FormData();
+    form.set("file", new Blob([Buffer.from(bytes)], { type: mediaType2 }), `audio.${extension}`);
+    form.set("model", request.model);
+    form.set("response_format", "json");
+    if (request.language) form.set("language", request.language);
+    if (options.temperature !== void 0) form.set("temperature", String(options.temperature));
+    if (options.prompt !== void 0) form.set("prompt", options.prompt);
+    const key = await this.resolveKey();
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/audio/transcriptions`,
+      {
+        method: "POST",
+        headers: { Authorization: `Bearer ${key}` },
+        body: form,
+        signal: request.signal
+      },
+      { governor: this.governor, provider: this.name }
+    );
+    if (!res.ok) {
+      const body = await res.text();
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message: safeProviderMessage("OpenAI", res.status, body),
+        body
+      });
+    }
+    const json = await res.json();
+    if (typeof json.text !== "string")
+      throw new InvalidTranscriptionInputError(
+        "OpenAI transcription response did not contain text"
+      );
+    return {
+      transcript: { text: json.text, ...transcriptUsage(json.usage) },
+      cleanupStatus: "not_required"
+    };
+  }
+  async resolveKey() {
+    const key = await resolveApiKey(this.apiKeySource);
+    if (!key)
+      throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.");
+    return key;
+  }
+};
+
+// src/providers/gemini-transcription.ts
+var CLEANUP_TIMEOUT_MS = 3e3;
+var READY_TIMEOUT_MS = 3e4;
+var READY_POLL_MS = 250;
+var GEMINI_AUDIO_MEDIA_TYPES = /* @__PURE__ */ new Set([
+  "audio/wav",
+  "audio/mp3",
+  "audio/aiff",
+  "audio/aac",
+  "audio/ogg",
+  "audio/flac",
+  "audio/mpeg",
+  "audio/m4a",
+  "audio/l16",
+  "audio/opus",
+  "audio/alaw",
+  "audio/mulaw",
+  "audio/webm"
+]);
+function abortError2() {
+  return new DOMException("The transcription operation was aborted", "AbortError");
+}
+function audioMime(audio) {
+  if (!audio.mediaType)
+    throw new UnsupportedTranscriptionInputError({
+      provider: "gemini-transcription",
+      model: GEMINI_TRANSCRIPTION_MODEL,
+      feature: "provider-file audio mediaType"
+    });
+  return audio.mediaType;
+}
+function assertGeminiAudioMime(mediaType2) {
+  if (!mediaType2 || !GEMINI_AUDIO_MEDIA_TYPES.has(mediaType2)) {
+    throw new UnsupportedTranscriptionInputError({
+      provider: "gemini-transcription",
+      model: GEMINI_TRANSCRIPTION_MODEL,
+      feature: "this audio media type"
+    });
+  }
+  return mediaType2;
+}
+function secondsOffset(value) {
+  if (typeof value !== "string") return void 0;
+  const match = /^(\d+(?:\.\d+)?)s$/.exec(value);
+  if (!match) return void 0;
+  const seconds = Number(match[1]);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : void 0;
+}
+function sleep3(ms, signal) {
+  return new Promise((resolve2, reject) => {
+    if (signal?.aborted) {
+      reject(abortError2());
+      return;
+    }
+    const timer = setTimeout(done, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      done(abortError2());
+    };
+    function done(error) {
+      signal?.removeEventListener("abort", onAbort);
+      if (error) reject(error);
+      else resolve2();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var GeminiTranscriptionProvider = class {
+  name = "gemini-transcription";
+  baseUrl;
+  apiKeySource;
+  governor;
+  constructor(options = {}) {
+    this.apiKeySource = options.apiKey ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY ?? "";
+    this.baseUrl = (options.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta").replace(
+      /\/$/,
+      ""
+    );
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      "Gemini transcription provider",
+      options.dangerouslyAllowInsecureHttp
+    );
+    this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
+  }
+  capabilities(model) {
+    return model === GEMINI_TRANSCRIPTION_MODEL ? { sources: ["bytes", "base64", "provider-file"], timestamps: ["word"], diarization: true } : void 0;
+  }
+  async transcribe(request) {
+    requireExactTranscriptionModel(this.name, request.model, GEMINI_TRANSCRIPTION_MODEL);
+    const options = assertOnlyProviderOptions(request, this.name, request.model, [
+      "mode",
+      "customVocabulary"
+    ]);
+    const mode = options.mode ?? "verbatim";
+    if (mode !== "smart" && mode !== "verbatim")
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription mode must be smart or verbatim"
+      );
+    if (options.customVocabulary !== void 0 && (!Array.isArray(options.customVocabulary) || options.customVocabulary.length > 1e3 || options.customVocabulary.some(
+      (value) => typeof value !== "string" || !value.trim() || value.length > 256
+    )))
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription customVocabulary must contain at most 1000 nonempty strings up to 256 characters"
+      );
+    if (mode === "smart" && (request.timestamps || request.diarization))
+      throw new InvalidTranscriptionInputError(
+        "Gemini smart transcription does not support timestamps or diarization"
+      );
+    if (request.timestamps && options.customVocabulary !== void 0)
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription customVocabulary cannot be combined with timestamps"
+      );
+    if (request.timestamps && request.timestamps !== "word")
+      throw new UnsupportedTranscriptionInputError({
+        provider: this.name,
+        model: request.model,
+        feature: "segment timestamps"
+      });
+    if (request.diarization && request.timestamps !== "word")
+      throw new InvalidTranscriptionInputError("Gemini diarization requires word timestamps");
+    if (request.audio.type === "provider-file") {
+      if (request.audio.provider !== this.name || typeof request.audio.reference !== "string" || !request.audio.reference.trim()) {
+        throw new UnsupportedTranscriptionInputError({
+          provider: this.name,
+          model: request.model,
+          feature: "a matching nonempty provider-file reference"
+        });
+      }
+      assertGeminiAudioMime(request.audio.mediaType);
+    } else {
+      assertGeminiAudioMime(request.audio.mediaType);
+    }
+    const key = await this.resolveKey();
+    if (request.audio.type === "provider-file")
+      return this.transcribeReference(request, key, mode, options);
+    return this.transcribeUpload(request, key, mode, options);
+  }
+  async transcribeReference(request, key, mode, options) {
+    const audio = request.audio;
+    if (audio.type !== "provider-file" || audio.provider !== this.name)
+      throw new UnsupportedTranscriptionInputError({
+        provider: this.name,
+        model: request.model,
+        feature: "a provider-file owned by another provider"
+      });
+    const mimeType = audioMime(audio);
+    const transcript = await this.infer(request, key, audio.reference, mimeType, mode, options);
+    return { transcript, cleanupStatus: "not_required" };
+  }
+  async transcribeUpload(request, key, mode, options) {
+    let created = false;
+    let fileName;
+    let primaryError;
+    let transcript;
+    let cleanupStatus = "not_required";
+    try {
+      const uploaded = await this.upload(request, key);
+      created = true;
+      fileName = uploaded.name;
+      const ready = await this.waitForReady(
+        this.fileFromJson(uploaded.file, uploaded.mimeType),
+        key,
+        request.signal
+      );
+      transcript = await this.infer(request, key, ready.uri, ready.mimeType, mode, options);
+    } catch (error) {
+      primaryError = error;
+    } finally {
+      if (created && fileName) cleanupStatus = await this.cleanup(fileName, key);
+    }
+    if (primaryError) {
+      throw attachTranscriptionFailureMetadata(
+        primaryError instanceof Error ? primaryError : new Error("Gemini transcription failed"),
+        { cleanupStatus }
+      );
+    }
+    if (!transcript)
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription response did not contain text"
+      );
+    return { transcript, cleanupStatus };
+  }
+  /** A finalization response with a name creates a caller-owned cleanup obligation
+   * even when its URI/state is malformed. `transcribeUpload` stores the name before
+   * strictly parsing the rest of the file representation. */
+  async upload(request, key) {
+    if (request.audio.type === "provider-file")
+      throw new UnsupportedTranscriptionInputError({
+        provider: this.name,
+        model: request.model,
+        feature: "provider-file upload"
+      });
+    const mimeType = assertGeminiAudioMime(request.audio.mediaType);
+    const bytes = inlineAudioBytes(request.audio);
+    const start = await fetchWithRetry(
+      `${this.baseUrl.replace(/\/v1beta$/, "")}/upload/v1beta/files`,
+      {
+        method: "POST",
+        headers: {
+          "x-goog-api-key": key,
+          "X-Goog-Upload-Protocol": "resumable",
+          "X-Goog-Upload-Command": "start",
+          "X-Goog-Upload-Header-Content-Length": String(bytes.byteLength),
+          "X-Goog-Upload-Header-Content-Type": mimeType,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ file: { display_name: "axl-transcription" } }),
+        signal: request.signal
+      },
+      { governor: this.governor, provider: this.name, maxRetries: 0 }
+    );
+    if (!start.ok) {
+      const body = await start.text();
+      throw buildProviderError({
+        provider: this.name,
+        status: start.status,
+        headers: start.headers,
+        message: safeProviderMessage("Gemini", start.status, body),
+        body
+      });
+    }
+    const uploadUrl = start.headers.get("x-goog-upload-url");
+    if (!uploadUrl)
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription upload did not return an upload URL"
+      );
+    let parsedUploadUrl;
+    try {
+      parsedUploadUrl = new URL(uploadUrl);
+    } catch {
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription upload returned an invalid upload URL"
+      );
+    }
+    const baseOrigin = new URL(this.baseUrl).origin;
+    if (parsedUploadUrl.username || parsedUploadUrl.password || parsedUploadUrl.origin !== baseOrigin) {
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription upload returned an untrusted upload URL"
+      );
+    }
+    assertSafeProviderBaseUrl(
+      parsedUploadUrl.toString(),
+      "Gemini transcription upload endpoint",
+      new URL(this.baseUrl).protocol === "http:"
+    );
+    const finalize = await fetchWithRetry(
+      parsedUploadUrl.toString(),
+      {
+        method: "POST",
+        headers: {
+          "X-Goog-Upload-Command": "upload, finalize",
+          "X-Goog-Upload-Offset": "0",
+          "Content-Length": String(bytes.byteLength)
+        },
+        body: bytes,
+        signal: request.signal
+      },
+      { governor: this.governor, provider: this.name, maxRetries: 0 }
+    );
+    if (!finalize.ok) {
+      const body = await finalize.text();
+      throw buildProviderError({
+        provider: this.name,
+        status: finalize.status,
+        headers: finalize.headers,
+        message: safeProviderMessage("Gemini", finalize.status, body),
+        body
+      });
+    }
+    const payload = await finalize.json();
+    const file = payload.file;
+    if (!file || typeof file.name !== "string") {
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription upload did not return a file name"
+      );
+    }
+    return { name: file.name, file, mimeType };
+  }
+  async waitForReady(file, key, signal) {
+    let current = file;
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    if (!current.state) {
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription file readiness state is missing"
+      );
+    }
+    while (current.state && current.state !== "ACTIVE") {
+      if (current.state === "FAILED")
+        throw new InvalidTranscriptionInputError("Gemini transcription file processing failed");
+      if (Date.now() >= deadline)
+        throw new InvalidTranscriptionInputError("Gemini transcription file readiness timed out");
+      await sleep3(Math.min(READY_POLL_MS, deadline - Date.now()), signal);
+      const res = await fetchWithRetry(
+        `${this.baseUrl}/${current.name}`,
+        { method: "GET", headers: { "x-goog-api-key": key }, signal },
+        { governor: this.governor, provider: this.name, maxRetries: 0 }
+      );
+      if (!res.ok) {
+        const body = await res.text();
+        throw buildProviderError({
+          provider: this.name,
+          status: res.status,
+          headers: res.headers,
+          message: safeProviderMessage("Gemini", res.status, body),
+          body
+        });
+      }
+      current = this.fileFromJson(await res.json(), current.mimeType);
+    }
+    return current;
+  }
+  async infer(request, key, uri, mimeType, mode, options) {
+    const transcriptionConfig = {
+      mode: mode === "smart" ? "smart" : {
+        type: "verbatim",
+        ...request.timestamps ? { timestamp_granularities: ["word"] } : {},
+        ...request.diarization ? { diarization_mode: "speaker" } : {}
+      },
+      ...request.language ? { language_codes: [request.language] } : {},
+      ...options.customVocabulary ? { custom_vocabulary: options.customVocabulary } : {}
+    };
+    const body = {
+      model: request.model,
+      input: [{ type: "audio", uri, mime_type: mimeType }],
+      store: false,
+      generation_config: { transcription_config: transcriptionConfig }
+    };
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/interactions`,
+      {
+        method: "POST",
+        headers: { "x-goog-api-key": key, "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: request.signal
+      },
+      { governor: this.governor, provider: this.name }
+    );
+    if (!res.ok) {
+      const errorBody = await res.text();
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message: safeProviderMessage("Gemini", res.status, errorBody),
+        body: errorBody
+      });
+    }
+    const json = await res.json();
+    if (json.status !== "completed") {
+      throw new InvalidTranscriptionInputError("Gemini transcription interaction did not complete");
+    }
+    const words = [];
+    let text = "";
+    let hasModelOutputText = false;
+    if (Array.isArray(json.steps)) {
+      for (const step of json.steps) {
+        if (!step || typeof step !== "object") continue;
+        const modelOutput = step;
+        if (modelOutput.type !== "model_output" || !Array.isArray(modelOutput.content)) continue;
+        for (const block of modelOutput.content) {
+          if (!block || typeof block !== "object") continue;
+          const content = block;
+          if (content.type !== "text" || typeof content.text !== "string") continue;
+          hasModelOutputText = true;
+          text += content.text;
+          if (!Array.isArray(content.annotations)) continue;
+          for (const raw of content.annotations) {
+            if (!raw || typeof raw !== "object") continue;
+            const annotation = raw;
+            if (annotation.type !== "word_info") continue;
+            if (typeof annotation.text !== "string") continue;
+            const start = secondsOffset(annotation.start_offset);
+            const end = secondsOffset(annotation.end_offset);
+            if (start === void 0 || end === void 0 || end < start) continue;
+            words.push({
+              text: annotation.text,
+              start,
+              end,
+              ...typeof annotation.speaker === "string" ? { speaker: annotation.speaker } : {}
+            });
+          }
+        }
+      }
+    }
+    if (!hasModelOutputText)
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription response did not contain model output text"
+      );
+    return { text, ...words.length ? { words } : {}, ...transcriptUsage(json.usage) };
+  }
+  fileFromJson(value, fallbackMimeType) {
+    const file = "file" in value && value.file ? value.file : value;
+    if (typeof file.name !== "string" || typeof file.uri !== "string")
+      throw new InvalidTranscriptionInputError(
+        "Gemini transcription upload did not return a file reference"
+      );
+    return {
+      name: file.name,
+      uri: file.uri,
+      mimeType: typeof file.mimeType === "string" ? file.mimeType : typeof file.mime_type === "string" ? file.mime_type : fallbackMimeType,
+      ...typeof file.state === "string" ? { state: file.state } : {}
+    };
+  }
+  async cleanup(fileName, key) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), CLEANUP_TIMEOUT_MS);
+    try {
+      const res = await fetchWithRetry(
+        `${this.baseUrl}/${fileName}`,
+        { method: "DELETE", headers: { "x-goog-api-key": key }, signal: controller.signal },
+        { governor: this.governor, provider: this.name, maxRetries: 0 }
+      );
+      return res.ok ? "deleted" : "failed";
+    } catch {
+      return controller.signal.aborted ? "timed_out" : "failed";
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async resolveKey() {
+    const key = await resolveApiKey(this.apiKeySource);
+    if (!key)
+      throw new Error("Google API key is required. Set GOOGLE_API_KEY or pass apiKey in options.");
+    return key;
+  }
+};
+
+// src/providers/openrouter-transcription.ts
+var FORMAT_BY_MIME = {
+  "audio/aac": "aac",
+  "audio/flac": "flac",
+  "audio/m4a": "m4a",
+  "audio/mp3": "mp3",
+  "audio/mp4": "mp4",
+  "audio/mpeg": "mp3",
+  "audio/ogg": "ogg",
+  "audio/wav": "wav",
+  "audio/webm": "webm"
+};
+var OpenRouterTranscriptionProvider = class {
+  name = "openrouter-transcription";
+  baseUrl;
+  apiKeySource;
+  governor;
+  constructor(options = {}) {
+    this.apiKeySource = options.apiKey ?? process.env.OPENROUTER_API_KEY ?? "";
+    this.baseUrl = (options.baseUrl ?? process.env.OPENROUTER_BASE_URL ?? "https://openrouter.ai/api/v1").replace(/\/$/, "");
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      "OpenRouter transcription provider",
+      options.dangerouslyAllowInsecureHttp
+    );
+    this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
+  }
+  capabilities(model) {
+    return model === OPENROUTER_TRANSCRIPTION_MODEL ? { sources: ["bytes", "base64"] } : void 0;
+  }
+  async transcribe(request) {
+    requireExactTranscriptionModel(this.name, request.model, OPENROUTER_TRANSCRIPTION_MODEL);
+    requireNoProviderFile(request.audio, this.name, request.model);
+    if (request.audio.type === "provider-file")
+      throw new UnsupportedTranscriptionInputError({
+        provider: this.name,
+        model: request.model,
+        feature: "provider-file transcription input"
+      });
+    const options = assertOnlyProviderOptions(request, this.name, request.model, [
+      "temperature",
+      "provider"
+    ]);
+    if (options.temperature !== void 0 && (typeof options.temperature !== "number" || !Number.isFinite(options.temperature) || options.temperature < 0 || options.temperature > 1))
+      throw new InvalidTranscriptionInputError(
+        "OpenRouter transcription temperature must be a number between 0 and 1"
+      );
+    if (options.provider !== void 0 && (!options.provider || Array.isArray(options.provider) || typeof options.provider !== "object"))
+      throw new InvalidTranscriptionInputError(
+        "OpenRouter transcription provider routing must be an object"
+      );
+    const format = FORMAT_BY_MIME[request.audio.mediaType];
+    if (!format)
+      throw new UnsupportedTranscriptionInputError({
+        provider: this.name,
+        model: request.model,
+        feature: "this audio media type"
+      });
+    const bytes = inlineAudioBytes(request.audio);
+    const body = {
+      model: request.model,
+      input_audio: { data: Buffer.from(bytes).toString("base64"), format },
+      ...request.language ? { language: request.language } : {},
+      ...options.temperature !== void 0 ? { temperature: options.temperature } : {},
+      ...options.provider !== void 0 ? { provider: options.provider } : {}
+    };
+    const key = await this.resolveKey();
+    const res = await fetchWithRetry(
+      `${this.baseUrl}/audio/transcriptions`,
+      {
+        method: "POST",
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: request.signal
+      },
+      { governor: this.governor, provider: this.name }
+    );
+    if (!res.ok) {
+      const errorBody = await res.text();
+      throw buildProviderError({
+        provider: this.name,
+        status: res.status,
+        headers: res.headers,
+        message: safeProviderMessage("OpenRouter", res.status, errorBody),
+        body: errorBody
+      });
+    }
+    const json = await res.json();
+    if (typeof json.text !== "string")
+      throw new InvalidTranscriptionInputError(
+        "OpenRouter transcription response did not contain text"
+      );
+    return {
+      transcript: { text: json.text, ...transcriptUsage(json.usage) },
+      cleanupStatus: "not_required"
+    };
+  }
+  async resolveKey() {
+    const key = await resolveApiKey(this.apiKeySource);
+    if (!key)
+      throw new Error(
+        "OpenRouter API key is required. Set OPENROUTER_API_KEY or pass apiKey in options."
+      );
+    return key;
+  }
+};
+
+// src/providers/transcription-registry.ts
+var builtinFactories2 = {
+  "openai-transcription": (config) => {
+    const opts = config.providers?.openai ?? {};
+    return new OpenAITranscriptionProvider({
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
+      rateLimit: opts.rateLimit
+    });
+  },
+  "gemini-transcription": (config) => {
+    const opts = config.providers?.google ?? {};
+    return new GeminiTranscriptionProvider({
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
+      rateLimit: opts.rateLimit
+    });
+  },
+  "openrouter-transcription": (config) => {
+    const opts = config.providers?.openrouter ?? {};
+    return new OpenRouterTranscriptionProvider({
+      apiKey: opts.apiKey,
+      baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
+      rateLimit: opts.rateLimit
+    });
+  }
+};
+var TranscriptionProviderRegistry = class {
+  instances = /* @__PURE__ */ new Map();
+  factories = /* @__PURE__ */ new Map();
+  constructor() {
+    for (const [name, factory] of Object.entries(builtinFactories2))
+      this.factories.set(name, factory);
+  }
+  register(name, factory) {
+    this.factories.set(name, factory);
+    this.instances.delete(name);
+  }
+  registerInstance(name, provider) {
+    this.instances.set(name, provider);
+  }
+  has(name) {
+    return this.instances.has(name) || this.factories.has(name);
+  }
+  get(name, config = {}) {
+    const instance = this.instances.get(name);
+    if (instance) return instance;
+    const factory = this.factories.get(name);
+    if (factory) {
+      const created = factory(config);
+      this.instances.set(name, created);
+      return created;
+    }
+    throw new UnsupportedTranscriptionInputError({
+      provider: name,
+      model: "",
+      feature: "transcription"
+    });
   }
-  /**
-   * Resolve a "provider:model" URI string into a Provider instance and model name.
-   *
-   * Supported formats:
-   *   - "openai:gpt-4o"        -> provider=openai, model=gpt-4o
-   *   - "anthropic:claude-3"   -> provider=anthropic, model=claude-3
-   *   - "gpt-4o"               -> uses defaultProvider from config, model=gpt-4o
-   *   - undefined / empty      -> uses defaultProvider and defaultModel from config
-   *
-   * @param uri  Provider:model string, or just a model name
-   * @param config  Axl configuration for provider options and defaults
-   */
   resolve(uri, config = {}) {
-    if (!uri) {
-      const providerName2 = config.defaultProvider ?? "openai";
-      const model2 = config.defaultModel ?? "gpt-4o";
-      return { provider: this.get(providerName2, config), model: model2 };
-    }
-    const colonIndex = uri.indexOf(":");
-    if (colonIndex === -1) {
-      const providerName2 = config.defaultProvider ?? "openai";
-      return { provider: this.get(providerName2, config), model: uri };
-    }
-    const providerName = uri.slice(0, colonIndex);
-    const model = uri.slice(colonIndex + 1);
-    if (!providerName || !model) {
-      throw new Error(
-        `Invalid provider URI "${uri}". Expected format: "provider:model" (e.g. "openai:gpt-4o")`
-      );
+    const colon = typeof uri === "string" ? uri.indexOf(":") : -1;
+    if (colon <= 0 || colon === uri.length - 1 || uri.indexOf(":", colon + 1) !== -1) {
+      throw new UnsupportedTranscriptionInputError({
+        provider: "unknown",
+        model: "",
+        feature: "an explicit transcription provider:model URI"
+      });
     }
-    return { provider: this.get(providerName, config), model };
-  }
-  /**
-   * Clear all cached provider instances. Useful for testing or reconfiguration.
-   */
-  clearCache() {
-    this.instances.clear();
-  }
-  /**
-   * Clear all registered factories (including built-ins).
-   * Useful for test runtimes where only explicitly registered instances should be used.
-   */
-  clearFactories() {
-    this.factories.clear();
+    const providerName = uri.slice(0, colon);
+    const model = uri.slice(colon + 1);
+    return { provider: this.get(providerName, config), model, providerName };
   }
 };
-var defaultRegistry = new ProviderRegistry();
 
 // src/context.ts
 var import_node_async_hooks = require("async_hooks");
 var import_node_crypto = require("crypto");
 var import_zod2 = require("zod");
 
+// src/input.ts
+var MAX_INLINE_MODEL_INPUT_BYTES = 25 * 1024 * 1024;
+function invalid(message) {
+  throw new InvalidModelInputError(message);
+}
+function nonEmptyString2(value, field) {
+  if (typeof value !== "string" || value.length === 0)
+    invalid(`${field} must be a non-empty string`);
+  return value;
+}
+function mediaType(value, field) {
+  return nonEmptyString2(value, field);
+}
+function validBase64(value) {
+  return value.length > 0 && value.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(value);
+}
+function decodedBase64Bytes(value) {
+  return Math.floor(value.length * 3 / 4) - (value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0);
+}
+function normalizeModelInput(input) {
+  if (typeof input === "string") return input;
+  if (!Array.isArray(input) || input.length === 0)
+    invalid("ModelInput parts must be a non-empty array");
+  let inlineBytes = 0;
+  const reserveInlineBytes = (bytes) => {
+    if (bytes > MAX_INLINE_MODEL_INPUT_BYTES - inlineBytes) {
+      invalid(
+        "Inline image data must not exceed 25 MiB total; use a URL or provider-file source where supported"
+      );
+    }
+    inlineBytes += bytes;
+  };
+  return input.map((part, index) => {
+    if (!part || typeof part !== "object") invalid(`ModelInput part ${index} must be an object`);
+    if (part.type === "text")
+      return { type: "text", text: nonEmptyString2(part.text, `part ${index}.text`) };
+    if (part.type !== "image") invalid(`part ${index}.type must be 'text' or 'image'`);
+    const source = part.source;
+    if (!source || typeof source !== "object") invalid(`part ${index}.source must be an object`);
+    let clone;
+    switch (source.type) {
+      case "url": {
+        const url = nonEmptyString2(source.url, `part ${index}.source.url`);
+        let parsed;
+        try {
+          parsed = new URL(url);
+        } catch {
+          invalid(`part ${index}.source.url must be an http(s) URL`);
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+          invalid(`part ${index}.source.url must be an http(s) URL`);
+        clone = {
+          type: "url",
+          url,
+          ...source.mediaType === void 0 ? {} : { mediaType: mediaType(source.mediaType, `part ${index}.source.mediaType`) }
+        };
+        break;
+      }
+      case "bytes":
+        if (!(source.data instanceof Uint8Array) || source.data.byteLength === 0)
+          invalid(`part ${index}.source.data must be a non-empty Uint8Array`);
+        reserveInlineBytes(source.data.byteLength);
+        clone = {
+          type: "bytes",
+          data: source.data.slice(),
+          mediaType: mediaType(source.mediaType, `part ${index}.source.mediaType`)
+        };
+        break;
+      case "base64": {
+        const data = nonEmptyString2(source.data, `part ${index}.source.data`);
+        if (data.length > 4 * Math.ceil(MAX_INLINE_MODEL_INPUT_BYTES / 3)) {
+          invalid(
+            "Inline image data must not exceed 25 MiB total; use a URL or provider-file source where supported"
+          );
+        }
+        if (!validBase64(data)) invalid(`part ${index}.source.data must be valid base64`);
+        reserveInlineBytes(decodedBase64Bytes(data));
+        clone = {
+          type: "base64",
+          data,
+          mediaType: mediaType(source.mediaType, `part ${index}.source.mediaType`)
+        };
+        break;
+      }
+      case "provider-file":
+        clone = {
+          type: "provider-file",
+          provider: nonEmptyString2(source.provider, `part ${index}.source.provider`),
+          reference: nonEmptyString2(source.reference, `part ${index}.source.reference`),
+          ...source.mediaType === void 0 ? {} : { mediaType: mediaType(source.mediaType, `part ${index}.source.mediaType`) }
+        };
+        break;
+      default:
+        invalid(`part ${index}.source.type is unsupported`);
+    }
+    return {
+      type: "image",
+      source: clone,
+      ...part.label === void 0 ? {} : { label: nonEmptyString2(part.label, `part ${index}.label`) }
+    };
+  });
+}
+function inputText(input) {
+  return typeof input === "string" ? input : input.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+}
+function cloneModelInput(input) {
+  return typeof input === "string" ? input : normalizeModelInput(input);
+}
+function describeModelInput(input) {
+  if (typeof input === "string") return void 0;
+  return {
+    parts: input.map((part) => {
+      if (part.type === "text") return { type: "text", characters: part.text.length };
+      const { source } = part;
+      return {
+        type: "image",
+        source: source.type,
+        ...source.mediaType ? { mediaType: source.mediaType } : {},
+        ...source.type === "bytes" ? { bytes: source.data.byteLength } : {},
+        ...source.type === "base64" ? {
+          bytes: decodedBase64Bytes(source.data)
+        } : {},
+        ...(source.type === "url" ? source.url : source.type === "provider-file" ? source.reference : void 0) ? {
+          locator: source.type === "url" ? source.url : source.type === "provider-file" ? source.reference : void 0
+        } : {},
+        ...part.label ? { label: part.label } : {}
+      };
+    })
+  };
+}
+function summarizeModelInput(input) {
+  if (typeof input === "string") return input;
+  return input.map(
+    (part) => part.type === "text" ? part.text : `[image ${part.source.mediaType ?? "media"}]`
+  ).join("\n");
+}
+function sanitizeModelInputForTrace(input) {
+  return inputText(input);
+}
+function normalizePersistedSessionHistory(history) {
+  return history.map((message, index) => {
+    if (typeof message.content === "string") return { ...message };
+    if (message.role !== "user") {
+      throw new InvalidModelInputError(
+        `History message ${index} has non-text content on a non-user role`
+      );
+    }
+    const content = normalizeModelInput(message.content);
+    if (typeof content !== "string" && content.some((part) => part.type === "image" && part.source.type === "bytes")) {
+      throw new InvalidModelInputError(
+        "Uint8Array image input cannot be persisted in session history"
+      );
+    }
+    return { ...message, content };
+  });
+}
+
 // src/partial-json.ts
 var MAX_DEPTH = 256;
 function parsePartialJson(input) {
@@ -5331,7 +7323,8 @@ var COST_BEARING_LEAF_TYPES = [
   "agent_call_end",
   "tool_call_end",
   "memory_remember",
-  "memory_recall"
+  "memory_recall",
+  "transcription_end"
 ];
 var COST_LEAF_SET = new Set(COST_BEARING_LEAF_TYPES);
 function hasPositiveTokens(event) {
@@ -5339,6 +7332,12 @@ function hasPositiveTokens(event) {
   if (!t) return false;
   return (t.input ?? 0) + (t.output ?? 0) + (t.reasoning ?? 0) + (t.cached ?? 0) + (t.cacheWrite ?? 0) > 0;
 }
+function hasPositiveBillableWork(event) {
+  if (hasPositiveTokens(event)) return true;
+  const seconds = event.data?.usage?.audioSeconds;
+  const totalTokens = event.data?.usage?.totalTokens;
+  return typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0 || typeof totalTokens === "number" && Number.isFinite(totalTokens) && totalTokens > 0;
+}
 function isUsableCost(cost) {
   return typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
 }
@@ -5351,7 +7350,7 @@ function isCostBearingLeaf(event) {
   return COST_LEAF_SET.has(event.type);
 }
 function isUnpricedLeaf(event) {
-  return event.type !== void 0 && COST_LEAF_SET.has(event.type) && !isUsableCost(event.cost) && hasPositiveTokens(event);
+  return event.type !== void 0 && COST_LEAF_SET.has(event.type) && !isUsableCost(event.cost) && hasPositiveBillableWork(event);
 }
 function isRootLevel(event) {
   const d = event.depth;
@@ -5366,6 +7365,9 @@ var AXL_EVENT_TYPES = [
   // Workflow lifecycle
   "workflow_start",
   "workflow_end",
+  // Transcription operation lifecycle (separate from chat/agent turns)
+  "transcription_start",
+  "transcription_end",
   // Ask boundary
   "ask_start",
   "ask_end",
@@ -5456,6 +7458,8 @@ var LIFECYCLE_TYPES = /* @__PURE__ */ new Set([
   "schema_diagnostic",
   "workflow_start",
   "workflow_end",
+  "transcription_start",
+  "transcription_end",
   "checkpoint_save",
   "checkpoint_replay",
   "await_human",
@@ -6271,6 +8275,21 @@ function redactGate(event) {
     }
   };
 }
+function redactInputDescriptor(input) {
+  return {
+    ...input,
+    parts: input.parts.map((part) => {
+      if (!part || typeof part !== "object" || !("type" in part) || part.type === "text")
+        return part;
+      const value = part;
+      return {
+        ...part,
+        ...value.locator !== void 0 ? { locator: REDACTED } : {},
+        ...value.label !== void 0 ? { label: REDACTED } : {}
+      };
+    })
+  };
+}
 function redactMemory(event) {
   const d = event.data;
   if (!d || typeof d !== "object") return event;
@@ -6294,7 +8313,11 @@ var LEGACY_REDACTION_RULES = {
       }
     };
   },
-  ask_start: (e) => ({ ...e, prompt: REDACTED }),
+  ask_start: (e) => ({
+    ...e,
+    prompt: REDACTED,
+    ...e.input ? { input: redactInputDescriptor(e.input) } : {}
+  }),
   ask_end: (e) => ({
     ...e,
     outcome: e.outcome.ok ? { ok: true, result: REDACTED } : { ok: false, error: REDACTED }
@@ -6302,6 +8325,14 @@ var LEGACY_REDACTION_RULES = {
   agent_call_start: (e) => {
     const d = e.data;
     const out = { ...d, prompt: REDACTED };
+    if (d.input) {
+      out.input = redactInputDescriptor(d.input);
+    }
+    if (d.messageInputs)
+      out.messageInputs = d.messageInputs.map((entry) => ({
+        ...entry,
+        input: redactInputDescriptor(entry.input)
+      }));
     if (d.system !== void 0) out.system = REDACTED;
     if (Array.isArray(d.messages)) {
       out.messages = [{ role: "system", content: `[${d.messages.length} messages redacted]` }];
@@ -6457,6 +8488,18 @@ function reuseLegacyRule(type) {
 var COMMON_V2_REDACTION_RULES = {
   workflow_start: reuseLegacyRule("workflow_start"),
   workflow_end: reuseLegacyRule("workflow_end"),
+  transcription_start: (e) => e,
+  transcription_end: (e) => {
+    const d = e.data;
+    return {
+      ...e,
+      data: {
+        ...d,
+        ...d.text !== void 0 ? { text: REDACTED } : {},
+        ...d.error !== void 0 ? { error: REDACTED } : {}
+      }
+    };
+  },
   ask_start: reuseLegacyRule("ask_start"),
   ask_end: reuseLegacyRule("ask_end"),
   agent_call_start: reuseLegacyRule("agent_call_start"),
@@ -6651,7 +8694,7 @@ function resolveConfig(config) {
 
 // src/tool-model-output.ts
 var import_node_util = require("util");
-function invalid(path, reason) {
+function invalid2(path, reason) {
   return new Error(`Invalid tool model output at ${path}: ${reason}`);
 }
 function propertyPath(parent, key) {
@@ -6669,14 +8712,14 @@ function propertyPath(parent, key) {
 function normalize(value, path, stack) {
   if (value === null || typeof value === "string" || typeof value === "boolean") return value;
   if (typeof value === "number") {
-    if (!Number.isFinite(value)) throw invalid(path, "number must be finite");
+    if (!Number.isFinite(value)) throw invalid2(path, "number must be finite");
     return value;
   }
-  if (value === void 0) throw invalid(path, "undefined is only allowed on object properties");
+  if (value === void 0) throw invalid2(path, "undefined is only allowed on object properties");
   if (typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") {
-    throw invalid(path, `unsupported ${typeof value}`);
+    throw invalid2(path, `unsupported ${typeof value}`);
   }
-  if (typeof value !== "object") throw invalid(path, `unsupported ${typeof value}`);
+  if (typeof value !== "object") throw invalid2(path, `unsupported ${typeof value}`);
   let prototype;
   let descriptors;
   try {
@@ -6684,38 +8727,38 @@ function normalize(value, path, stack) {
     descriptors = Object.getOwnPropertyDescriptors(value);
     Object.setPrototypeOf(descriptors, null);
   } catch (cause) {
-    throw invalid(
+    throw invalid2(
       path,
       `object inspection failed (${cause instanceof Error ? cause.name : "error"})`
     );
   }
-  if (stack.has(value)) throw invalid(path, "cyclic reference");
+  if (stack.has(value)) throw invalid2(path, "cyclic reference");
   for (const key of Reflect.ownKeys(descriptors)) {
     const descriptor = descriptors[key];
     if (descriptor && !("value" in descriptor)) {
-      throw invalid(
+      throw invalid2(
         typeof key === "string" ? propertyPath(path, key) : `${path}[symbol]`,
         "accessor properties are not supported"
       );
     }
     if (typeof key === "symbol") {
-      throw invalid(`${path}[symbol]`, "symbol keys are not supported");
+      throw invalid2(`${path}[symbol]`, "symbol keys are not supported");
     }
   }
   if (typeof descriptors.toJSON?.value === "function") {
-    throw invalid(propertyPath(path, "toJSON"), "custom toJSON is not supported");
+    throw invalid2(propertyPath(path, "toJSON"), "custom toJSON is not supported");
   }
   const array = Array.isArray(value);
   if (array && prototype !== Array.prototype && prototype !== null) {
-    throw invalid(path, "array subclasses are not supported");
+    throw invalid2(path, "array subclasses are not supported");
   }
   const inheritedToJSON = prototype === Array.prototype || prototype === Object.prototype ? Object.getOwnPropertyDescriptor(prototype, "toJSON") : void 0;
   if (typeof inheritedToJSON?.value === "function") {
-    throw invalid(propertyPath(path, "toJSON"), "inherited custom toJSON is not supported");
+    throw invalid2(propertyPath(path, "toJSON"), "inherited custom toJSON is not supported");
   }
   const inheritedThen = prototype === Array.prototype || prototype === Object.prototype ? Object.getOwnPropertyDescriptor(prototype, "then") : void 0;
   if (typeof descriptors.then?.value === "function" || inheritedThen !== void 0 && (!("value" in inheritedThen) || typeof inheritedThen.value === "function")) {
-    throw invalid(path, "thenable output is not supported");
+    throw invalid2(path, "thenable output is not supported");
   }
   stack.add(value);
   try {
@@ -6723,15 +8766,15 @@ function normalize(value, path, stack) {
       const normalized2 = [];
       const length = descriptors.length?.value;
       if (!Number.isSafeInteger(length) || length < 0) {
-        throw invalid(propertyPath(path, "length"), "array length is invalid");
+        throw invalid2(propertyPath(path, "length"), "array length is invalid");
       }
       for (let index = 0; index < length; index++) {
         const descriptor = descriptors[String(index)];
         if (!descriptor || !("value" in descriptor)) {
-          throw invalid(`${path}[${index}]`, "arrays must be dense data properties");
+          throw invalid2(`${path}[${index}]`, "arrays must be dense data properties");
         }
         if (descriptor.value === void 0) {
-          throw invalid(`${path}[${index}]`, "array values cannot be undefined");
+          throw invalid2(`${path}[${index}]`, "array values cannot be undefined");
         }
         normalized2.push(normalize(descriptor.value, `${path}[${index}]`, stack));
       }
@@ -6740,21 +8783,21 @@ function normalize(value, path, stack) {
         if (!descriptor?.enumerable) continue;
         const index = Number(key);
         if (!Number.isInteger(index) || index < 0 || index >= length || String(index) !== key) {
-          throw invalid(propertyPath(path, key), "non-index array properties are not supported");
+          throw invalid2(propertyPath(path, key), "non-index array properties are not supported");
         }
       }
       Object.setPrototypeOf(normalized2, null);
       return normalized2;
     }
     if (prototype !== Object.prototype && prototype !== null) {
-      throw invalid(path, "only plain objects and null-prototype records are supported");
+      throw invalid2(path, "only plain objects and null-prototype records are supported");
     }
     const normalized = /* @__PURE__ */ Object.create(null);
     for (const key of Object.keys(descriptors)) {
       const descriptor = descriptors[key];
       if (!descriptor?.enumerable) continue;
       if (!("value" in descriptor)) {
-        throw invalid(propertyPath(path, key), "accessor properties are not supported");
+        throw invalid2(propertyPath(path, key), "accessor properties are not supported");
       }
       if (descriptor.value === void 0) continue;
       normalized[key] = normalize(descriptor.value, propertyPath(path, key), stack);
@@ -7262,44 +9305,44 @@ function resolveBranchDrainTimeoutMs(value) {
   return resolved;
 }
 function parseHumanDecision(value) {
-  const invalid2 = () => {
+  const invalid3 = () => {
     throw new AxlError(
       "INVALID_HUMAN_DECISION",
       "Human decision must be a plain object with a boolean approved field and only branch-appropriate string data"
     );
   };
-  if (typeof value !== "object" || value === null || Array.isArray(value)) invalid2();
+  if (typeof value !== "object" || value === null || Array.isArray(value)) invalid3();
   let prototype;
   try {
     prototype = Object.getPrototypeOf(value);
   } catch {
-    return invalid2();
+    return invalid3();
   }
-  if (prototype !== Object.prototype && prototype !== null) invalid2();
+  if (prototype !== Object.prototype && prototype !== null) invalid3();
   let ownKeys;
   try {
     ownKeys = Reflect.ownKeys(value);
   } catch {
-    return invalid2();
+    return invalid3();
   }
   if (ownKeys.some(
     (key) => typeof key !== "string" || key !== "approved" && key !== "data" && key !== "reason"
   )) {
-    invalid2();
+    invalid3();
   }
   const readDataProperty = (key) => {
     let descriptor;
     try {
       descriptor = Object.getOwnPropertyDescriptor(value, key);
     } catch {
-      return invalid2();
+      return invalid3();
     }
     if (!descriptor) {
-      if (ownKeys.includes(key)) invalid2();
+      if (ownKeys.includes(key)) invalid3();
       return { present: false, value: void 0 };
     }
-    if (!ownKeys.includes(key)) return invalid2();
-    if (!("value" in descriptor)) return invalid2();
+    if (!ownKeys.includes(key)) return invalid3();
+    if (!("value" in descriptor)) return invalid3();
     return { present: true, value: descriptor.value };
   };
   const approved = readDataProperty("approved");
@@ -7318,7 +9361,7 @@ function parseHumanDecision(value) {
       };
     }
   }
-  return invalid2();
+  return invalid3();
 }
 var askStorage = new import_node_async_hooks.AsyncLocalStorage();
 var inlineSchemaCache = /* @__PURE__ */ new WeakMap();
@@ -7426,8 +9469,12 @@ function appendRetryMessages(messages, content, feedbackMessage, providerMetadat
 }
 function estimateMessagesTokens(messages) {
   let total = 0;
+  let unmeasured = false;
   for (const msg of messages) {
-    total += estimateTokens(msg.content);
+    total += estimateTokens(inputText(msg.content));
+    if (typeof msg.content !== "string") {
+      unmeasured ||= msg.content.some((part) => part.type === "image");
+    }
     if (msg.tool_calls) {
       for (const tc of msg.tool_calls) {
         total += estimateTokens(tc.function.name + tc.function.arguments);
@@ -7435,7 +9482,73 @@ function estimateMessagesTokens(messages) {
     }
     total += 4;
   }
-  return total;
+  return { tokens: total, unmeasured };
+}
+function cloneMessagesForProvider(messages) {
+  return messages.map((message) => ({
+    ...message,
+    content: cloneModelInput(message.content),
+    ...message.tool_calls ? {
+      tool_calls: message.tool_calls.map((call) => ({
+        ...call,
+        function: { ...call.function }
+      }))
+    } : {}
+  }));
+}
+function assertRichMessagesAreUserOnly(messages) {
+  for (const message of messages) {
+    if (typeof message.content !== "string" && message.role !== "user") {
+      throw new InvalidModelInputError(
+        "Non-text model input parts are only supported on user messages"
+      );
+    }
+  }
+}
+function normalizeSessionHistory(messages) {
+  return messages.map((message) => {
+    if (typeof message.content === "string") return { ...message };
+    if (message.role !== "user") {
+      throw new InvalidModelInputError(
+        "Non-text model input parts are only supported on user messages"
+      );
+    }
+    return { ...message, content: normalizeModelInput(message.content) };
+  });
+}
+function hasRichMessage(messages) {
+  return messages.some((message) => typeof message.content !== "string");
+}
+function firstImageSource(input, history) {
+  const find = (value) => typeof value === "string" ? void 0 : value.find((part) => part.type === "image")?.source.type;
+  return find(input) ?? history.map((message) => find(message.content)).find(Boolean);
+}
+function appendHandoffInstruction(input, originalText, instruction) {
+  if (typeof input === "string" || instruction.length === 0 || instruction === originalText)
+    return input;
+  return [...input, { type: "text", text: instruction }];
+}
+var RICH_MODEL_INPUT_ERROR_MESSAGE = "Provider request failed while processing rich model input";
+var RICH_MODEL_INPUT_ERROR_NAME = "RichModelInputError";
+var MAX_RICH_FAILURE_ASSOCIATIONS = 32;
+var MAX_RICH_FAILURE_CAUSE_DEPTH = 4;
+function legacyErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function providerErrorEventMetadata(error, richRequest) {
+  if (!(error instanceof ProviderError)) {
+    return error instanceof AxlError && richRequest ? { code: error.code } : {};
+  }
+  return {
+    status: error.status,
+    retryable: error.retryable,
+    ...richRequest ? {
+      code: error.code,
+      provider: error.provider,
+      ...error.requestId ? { requestId: error.requestId } : {},
+      ...error.retryAfterMs !== void 0 ? { retryAfterMs: error.retryAfterMs } : {}
+    } : {}
+  };
 }
 var WorkflowContext = class _WorkflowContext {
   input;
@@ -7451,6 +9564,7 @@ var WorkflowContext = class _WorkflowContext {
   }
   config;
   providerRegistry;
+  transcriptionProviderRegistry;
   sessionHistory;
   onTrace;
   pendingDecisions;
@@ -7476,6 +9590,10 @@ var WorkflowContext = class _WorkflowContext {
    */
   autoCheckpointCounters;
   branchDrainState;
+  /** Bounded exact-identity failure association for this execution tree.
+   * Unlike a process-global marker, this cannot affect another context that
+   * happens to reuse the same Error object. */
+  richFailureState;
   /** Root-shared idempotency guards for workflow lifecycle emission.
    *  Both `runtime.execute()` and `runtime.stream()` have paths where a
    *  post-emit side-effect (checkpoint deletion, state-store persistence)
@@ -7559,7 +9677,8 @@ var WorkflowContext = class _WorkflowContext {
   get events() {
     if (!this._busRef.current) {
       this._busRef.current = new AxlEventBus(this._eventStreamOptions);
-      if (this.signal?.aborted) {
+      const signal = this.currentSignal;
+      if (signal?.aborted) {
         this._busRef.current._finish();
       }
     }
@@ -7597,6 +9716,7 @@ var WorkflowContext = class _WorkflowContext {
     this.metadata = init.metadata ?? {};
     this.config = init.config;
     this.providerRegistry = init.providerRegistry;
+    this.transcriptionProviderRegistry = init.transcriptionProviderRegistry;
     this.sessionHistory = init.sessionHistory ?? [];
     this.onTrace = init.onTrace;
     this.pendingDecisions = init.pendingDecisions;
@@ -7630,6 +9750,11 @@ var WorkflowContext = class _WorkflowContext {
       byAgent: /* @__PURE__ */ new Map(),
       root: 0
     };
+    this.richFailureState = init.richFailureState ?? {
+      associations: [],
+      overflowed: false,
+      indeterminate: false
+    };
     const branchDrainTimeoutMs = resolveBranchDrainTimeoutMs(init.branchDrainTimeoutMs);
     this.branchDrainState = init.branchDrainState ?? {
       pending: /* @__PURE__ */ new Set(),
@@ -7662,6 +9787,7 @@ var WorkflowContext = class _WorkflowContext {
       executionId: this.executionId,
       config: this.config,
       providerRegistry: this.providerRegistry,
+      transcriptionProviderRegistry: this.transcriptionProviderRegistry,
       metadata: { ...this.metadata },
       // Shared infrastructure
       budgetContext: this.budgetContext,
@@ -7684,6 +9810,7 @@ var WorkflowContext = class _WorkflowContext {
       autoCheckpointCounters: this.autoCheckpointCounters,
       branchDrainState: this.branchDrainState,
       workflowLifecycleState: this.workflowLifecycleState,
+      richFailureState: this.richFailureState,
       // Share the parent's bus slot (mutable ref). Late allocation in
       // either parent or child propagates because both read the same
       // slot. Nested-ask events (agent-as-tool pattern) bubble up to
@@ -7695,6 +9822,52 @@ var WorkflowContext = class _WorkflowContext {
       // Isolated: sessionHistory (empty)
     });
   }
+  /** Associate an exact thrown value with rich input in this execution only. */
+  recordRichFailure(error) {
+    const state = this.richFailureState;
+    if (state.associations.some((known) => Object.is(known, error))) return;
+    if (state.associations.length >= MAX_RICH_FAILURE_ASSOCIATIONS) {
+      state.associations.shift();
+      state.overflowed = true;
+      state.indeterminate = true;
+    }
+    state.associations.push(error);
+  }
+  /** @internal Safe observer projection for a failure associated with rich input. */
+  _observerErrorProjection(error) {
+    const state = this.richFailureState;
+    const safe = () => ({
+      message: RICH_MODEL_INPUT_ERROR_MESSAGE,
+      name: RICH_MODEL_INPUT_ERROR_NAME
+    });
+    const indeterminate = () => {
+      if (state.associations.length === 0) return void 0;
+      state.indeterminate = true;
+      return safe();
+    };
+    let current = error;
+    const seen = /* @__PURE__ */ new WeakSet();
+    for (let depth = 0; depth < MAX_RICH_FAILURE_CAUSE_DEPTH; depth++) {
+      if (state.associations.some((known) => Object.is(known, current))) {
+        return safe();
+      }
+      if ((typeof current !== "object" || current === null) && typeof current !== "function") {
+        return state.overflowed || state.indeterminate ? safe() : void 0;
+      }
+      if (seen.has(current)) return indeterminate();
+      seen.add(current);
+      let descriptor;
+      try {
+        descriptor = Object.getOwnPropertyDescriptor(current, "cause");
+      } catch {
+        return indeterminate();
+      }
+      if (!descriptor) return state.overflowed || state.indeterminate ? safe() : void 0;
+      if (!("value" in descriptor)) return indeterminate();
+      current = descriptor.value;
+    }
+    return indeterminate();
+  }
   /**
    * Resolve the current abort signal.
    * Branch-scoped signals (from race/spawn/map/budget) in AsyncLocalStorage
@@ -7896,6 +10069,17 @@ var WorkflowContext = class _WorkflowContext {
   }
   // ── ctx.ask() ─────────────────────────────────────────────────────────
   async ask(agent2, prompt, options) {
+    const normalizedInput = normalizeModelInput(prompt);
+    const normalizedHistory = normalizeSessionHistory(this.sessionHistory);
+    const delegateInputHolder = agent2;
+    if (delegateInputHolder._delegateOriginalInput !== void 0) {
+      delegateInputHolder._delegateOriginalInput = normalizeModelInput(
+        delegateInputHolder._delegateOriginalInput
+      );
+    }
+    const richAsk = typeof normalizedInput !== "string" || hasRichMessage(normalizedHistory) || delegateInputHolder._delegateOriginalInput !== void 0 && typeof delegateInputHolder._delegateOriginalInput !== "string";
+    const promptText = inputText(normalizedInput);
+    const inputDescriptor = describeModelInput(normalizedInput);
     const agentName = agent2._name;
     return this._checkpoint(
       this._autoCheckpointName("ask", agentName),
@@ -7915,7 +10099,11 @@ var WorkflowContext = class _WorkflowContext {
         };
         return askStorage.run(frame, async () => {
           const askStart = Date.now();
-          this.emitEvent({ type: "ask_start", prompt });
+          this.emitEvent({
+            type: "ask_start",
+            prompt: promptText,
+            ...inputDescriptor ? { input: inputDescriptor } : {}
+          });
           const costBefore = this.budgetContext?.totalCost ?? 0;
           const unpricedCountBefore = this.budgetContext?.unpricedCount ?? 0;
           const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
@@ -7923,10 +10111,11 @@ var WorkflowContext = class _WorkflowContext {
           const doCall = async () => {
             const result2 = await this.executeAgentCall(
               agent2,
-              prompt,
+              normalizedInput,
               options,
               void 0,
-              usageCapture
+              usageCapture,
+              normalizedHistory
             );
             return result2;
           };
@@ -7943,6 +10132,9 @@ var WorkflowContext = class _WorkflowContext {
               },
               async (span) => {
                 const r = await doCall();
+                if (usageCapture.modelUri) {
+                  span.setAttribute("axl.agent.model", usageCapture.modelUri);
+                }
                 const costAfter2 = this.budgetContext?.totalCost ?? 0;
                 span.setAttribute("axl.agent.cost", costAfter2 - costBefore);
                 span.setAttribute("axl.agent.duration", Date.now() - askStart);
@@ -7976,9 +10168,10 @@ var WorkflowContext = class _WorkflowContext {
               try {
                 this.onAgentCallComplete({
                   agent: agent2._name,
-                  prompt,
+                  prompt: promptText,
+                  ...inputDescriptor ? { input: inputDescriptor } : {},
                   response: typeof result === "string" ? result : JSON.stringify(result),
-                  model: agent2.resolveModel(resolveCtx),
+                  model: usageCapture.modelUri ?? agent2.resolveModel(resolveCtx),
                   cost: costAfter - costBefore,
                   unpriced: frame.askUnpriced || unpricedCountAfter > unpricedCountBefore,
                   duration: Date.now() - askStart,
@@ -8002,9 +10195,10 @@ var WorkflowContext = class _WorkflowContext {
           } catch (err) {
             askFailed = true;
             askFailure = err;
+            if (richAsk) this.recordRichFailure(err);
             outcome = {
               ok: false,
-              error: err instanceof Error ? err.message : String(err)
+              error: this._observerErrorProjection(err)?.message ?? legacyErrorMessage(err)
             };
           }
           let terminalFailure;
@@ -8032,7 +10226,7 @@ var WorkflowContext = class _WorkflowContext {
       { agent: agentName }
     );
   }
-  async executeAgentCall(agent2, prompt, options, handoffMessages, usageCapture) {
+  async executeAgentCall(agent2, input, options, handoffMessages, usageCapture, sessionHistory = normalizeSessionHistory(this.sessionHistory)) {
     if (this.budgetContext?.exceeded) {
       const { limit, totalCost: spent, policy } = this.budgetContext;
       if (policy === "warn") {
@@ -8049,7 +10243,82 @@ var WorkflowContext = class _WorkflowContext {
     const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
     const modelUri = agent2.resolveModel(resolveCtx);
     const systemPrompt = agent2.resolveSystem(resolveCtx);
-    const { provider, model } = this.providerRegistry.resolve(modelUri, this.config);
+    const { provider, model: resolvedModel } = this.providerRegistry.resolve(modelUri, this.config);
+    let model = resolvedModel;
+    const prompt = inputText(input);
+    const providerOptions = options?.providerOptions ?? agent2._config.providerOptions;
+    const richRequest = typeof input !== "string" || hasRichMessage(sessionHistory);
+    if (richRequest) {
+      if (providerOptions && ("messages" in providerOptions || "input" in providerOptions)) {
+        throw new UnsupportedModelInputError({
+          provider: provider.name ?? modelUri.split(":", 1)[0],
+          model,
+          modality: "image",
+          feature: "raw input-container providerOptions"
+        });
+      }
+      const source = firstImageSource(input, sessionHistory);
+      if (!provider.validateInput) {
+        throw new UnsupportedModelInputError({
+          provider: provider.name ?? modelUri.split(":", 1)[0],
+          model,
+          modality: "image",
+          ...source ? { source } : {}
+        });
+      }
+      const validation = provider.validateInput({
+        model,
+        input: cloneModelInput(input),
+        history: cloneMessagesForProvider(sessionHistory),
+        stream: this._streamingEnabled,
+        hasTools: Boolean(
+          agent2._config.tools?.length || agent2._config.mcp?.length || agent2._config.mcpTools?.length || agent2._config.handoffs
+        ),
+        responseMode: options?.schema ? "structured" : "text",
+        providerOptions
+      });
+      if (!validation || typeof validation.effectiveModel !== "string" || validation.effectiveModel.length === 0) {
+        throw new UnsupportedModelInputError({
+          provider: provider.name ?? modelUri.split(":", 1)[0],
+          model,
+          modality: "image",
+          ...source ? { source } : {}
+        });
+      }
+      model = validation.effectiveModel;
+    }
+    const effectiveModelUri = !richRequest ? modelUri : `${modelUri.slice(0, modelUri.indexOf(":") + 1)}${model}`;
+    if (usageCapture) usageCapture.modelUri ??= effectiveModelUri;
+    if (richRequest) {
+      const descriptors = [
+        describeModelInput(input),
+        ...sessionHistory.map((message) => describeModelInput(message.content))
+      ].filter(
+        (descriptor) => descriptor !== void 0
+      );
+      const parts = descriptors.flatMap((descriptor) => descriptor.parts);
+      this.spanManager?.addEventToActiveSpan("axl.model_input", {
+        "axl.input.parts": parts.length,
+        "axl.input.images": parts.filter((part) => part.type === "image").length,
+        "axl.input.source.bytes": parts.filter(
+          (part) => part.type === "image" && part.source === "bytes"
+        ).length,
+        "axl.input.source.base64": parts.filter(
+          (part) => part.type === "image" && part.source === "base64"
+        ).length,
+        "axl.input.source.url": parts.filter(
+          (part) => part.type === "image" && part.source === "url"
+        ).length,
+        "axl.input.source.provider_file": parts.filter(
+          (part) => part.type === "image" && part.source === "provider-file"
+        ).length,
+        "axl.input.inline_bytes": parts.reduce(
+          (sum, part) => sum + (part.type === "image" ? part.bytes ?? 0 : 0),
+          0
+        )
+      });
+    }
+    assertRichMessagesAreUserOnly(sessionHistory);
     let resolvedHandoffs;
     if (typeof agent2._config.handoffs === "function") {
       try {
@@ -8070,50 +10339,60 @@ var WorkflowContext = class _WorkflowContext {
       messages.push({ role: "system", content: systemPrompt });
     }
     const maxContext = agent2._config.maxContext;
-    if (maxContext && this.sessionHistory.length > 0) {
+    if (maxContext && sessionHistory.length > 0) {
       const reserveTokens = this.config.contextManagement?.reserveTokens ?? 2e3;
       const systemTokens = systemPrompt ? estimateTokens(systemPrompt) : 0;
       const toolTokens = toolDefs.length > 0 ? estimateTokens(JSON.stringify(toolDefs)) : 0;
       const overhead = systemTokens + toolTokens + reserveTokens;
       const availableForHistory = maxContext - overhead;
-      const historyTokens = estimateMessagesTokens(this.sessionHistory);
-      if (historyTokens > availableForHistory) {
+      const historyEstimate = estimateMessagesTokens(sessionHistory);
+      if (historyEstimate.unmeasured) {
+        this.emitEvent({
+          type: "log",
+          data: {
+            warning: "Context media contribution is unmeasured; provider will enforce its context limit"
+          }
+        });
+      }
+      if (historyEstimate.tokens > availableForHistory) {
         const summarizedMessages = await this.summarizeHistory(
           provider,
           model,
-          this.sessionHistory,
+          sessionHistory,
           availableForHistory
         );
         for (const msg of summarizedMessages) {
           messages.push(msg);
         }
       } else {
-        for (const msg of this.sessionHistory) {
+        for (const msg of sessionHistory) {
           messages.push(msg);
         }
       }
     } else {
-      for (const msg of this.sessionHistory) {
+      for (const msg of sessionHistory) {
         messages.push(msg);
       }
     }
     const schemaPromptMode = options?.schemaPrompt ?? agent2._config.schemaPrompt ?? "json-schema";
-    let userContent = prompt;
+    let userContent = input;
     let appendedSchemaText;
     if (options?.schema) {
       const schema = options.schema;
       if (schemaPromptMode === "none") {
       } else if (schemaPromptMode === "json-schema") {
         appendedSchemaText = renderSchemaForPrompt(schema);
-        userContent += `
+        const guidance = `
 
 Respond with valid JSON matching this schema:
 ${appendedSchemaText}`;
+        userContent = typeof input === "string" ? input + guidance : [...input, { type: "text", text: guidance }];
       } else {
         appendedSchemaText = typeof schemaPromptMode.render === "function" ? schemaPromptMode.render(schema) : schemaPromptMode.render;
-        userContent += `
+        const guidance = `
 
 ${appendedSchemaText}`;
+        userContent = typeof input === "string" ? input + guidance : [...input, { type: "text", text: guidance }];
       }
     }
     messages.push({ role: "user", content: userContent });
@@ -8141,7 +10420,10 @@ ${appendedSchemaText}`;
     }
     const guardrails = agent2._config.guardrails;
     if (guardrails?.input) {
-      const inputResult = await guardrails.input(prompt, { metadata: this.metadata });
+      const inputResult = await guardrails.input(prompt, {
+        metadata: this.metadata,
+        input: cloneModelInput(input)
+      });
       this.emitEvent({
         type: "guardrail",
         agent: agent2._name,
@@ -8232,7 +10514,7 @@ ${appendedSchemaText}`;
         includeThoughts: options?.includeThoughts ?? agent2._config.includeThoughts,
         toolChoice: options?.toolChoice ?? agent2._config.toolChoice,
         stop: options?.stop ?? agent2._config.stop,
-        providerOptions: options?.providerOptions ?? agent2._config.providerOptions,
+        providerOptions,
         signal: this.currentSignal
       };
       if (options?.schema && toolDefs.length === 0) {
@@ -8258,15 +10540,26 @@ ${appendedSchemaText}`;
         ...chatOptions.stop !== void 0 ? { stop: chatOptions.stop } : {}
       };
       let messagesSnapshot;
+      let messageInputs;
       if (verboseTrace) {
         try {
-          messagesSnapshot = structuredClone(currentMessages);
+          messageInputs = currentMessages.flatMap((message, index) => {
+            const descriptor = describeModelInput(message.content);
+            return descriptor ? [{ index, input: descriptor }] : [];
+          });
+          messagesSnapshot = currentMessages.map((message) => ({
+            ...message,
+            content: sanitizeModelInputForTrace(message.content)
+          }));
         } catch (err) {
           console.warn(
             "[axl] verbose trace messages snapshot failed to clone; emitting shallow copy:",
             err instanceof Error ? err.message : String(err)
           );
-          messagesSnapshot = [...currentMessages];
+          messagesSnapshot = currentMessages.map((message) => ({
+            ...message,
+            content: sanitizeModelInputForTrace(message.content)
+          }));
         }
       }
       const retryReason = pendingRetryReason;
@@ -8274,16 +10567,18 @@ ${appendedSchemaText}`;
       this.emitEvent({
         type: "agent_call_start",
         agent: agent2._name,
-        model: modelUri,
+        model: effectiveModelUri,
         turn: turns,
         data: {
           prompt,
+          ...typeof input === "string" ? {} : { input: describeModelInput(input) },
           ...systemPrompt ? { system: systemPrompt } : {},
           params: callParams,
           turn: turns,
           ...retryReason ? { retryReason } : {},
           ...toolDefs.length > 0 ? { toolNames: toolDefs.map((t) => t.function.name) } : {},
-          ...messagesSnapshot ? { messages: messagesSnapshot } : {}
+          ...messagesSnapshot ? { messages: messagesSnapshot } : {},
+          ...messageInputs && messageInputs.length > 0 ? { messageInputs } : {}
         }
       });
       let response;
@@ -8307,7 +10602,10 @@ ${appendedSchemaText}`;
               });
             }
           }) : void 0;
-          for await (const chunk of provider.stream(currentMessages, chatOptions)) {
+          for await (const chunk of provider.stream(
+            cloneMessagesForProvider(currentMessages),
+            chatOptions
+          )) {
             if (chunk.type === "text_delta") {
               content2 += chunk.content;
               this.emitEvent({ type: "token", data: chunk.content });
@@ -8373,24 +10671,25 @@ ${appendedSchemaText}`;
             response.thinking_content = thinkingContent;
           }
         } else {
-          response = await provider.chat(currentMessages, chatOptions);
+          response = await provider.chat(cloneMessagesForProvider(currentMessages), chatOptions);
         }
       } catch (err) {
+        if (richRequest) this.recordRichFailure(err);
         this.emitEvent({
           type: "agent_call_end",
           agent: agent2._name,
-          model: modelUri,
+          model: effectiveModelUri,
           promptVersion: agent2._config.version,
           duration: Date.now() - turnStart,
           data: {
             response: "",
             turn: turns,
             ...retryReason ? { retryReason } : {},
-            error: err instanceof Error ? err.message : String(err),
+            error: this._observerErrorProjection(err)?.message ?? legacyErrorMessage(err),
             // Enrich with typed-error metadata when available. `body` is
             // deliberately NOT emitted — it's redaction-eligible (see
             // docs/security.md). `data.error` already carries the message.
-            ...err instanceof ProviderError ? { status: err.status, retryable: err.retryable } : {}
+            ...providerErrorEventMetadata(err, richRequest)
           }
         });
         throw err;
@@ -8404,7 +10703,7 @@ ${appendedSchemaText}`;
       this.emitEvent({
         type: "agent_call_end",
         agent: agent2._name,
-        model: modelUri,
+        model: effectiveModelUri,
         promptVersion: agent2._config.version,
         cost: response.cost,
         tokens: response.usage ? {
@@ -8438,12 +10737,12 @@ ${appendedSchemaText}`;
             if (descriptor) {
               const mode = descriptor.mode ?? "oneway";
               let handoffPrompt = prompt;
-              if (mode === "roundtrip") {
-                try {
-                  const args = JSON.parse(toolCall.function.arguments);
-                  if (args.message) handoffPrompt = args.message;
-                } catch {
+              try {
+                const args = JSON.parse(toolCall.function.arguments);
+                if (typeof args.message === "string" && args.message.length > 0) {
+                  handoffPrompt = args.message;
                 }
+              } catch {
               }
               const handoffStart = Date.now();
               const sourceFrame = askStorage.getStore();
@@ -8470,15 +10769,27 @@ ${appendedSchemaText}`;
                 validateRetries: options.validateRetries
               } : void 0;
               const handoffFn = () => askStorage.run(targetFrame, async () => {
-                this.emitEvent({ type: "ask_start", prompt: handoffPrompt });
+                const delegateOriginal = agent2._delegateOriginalInput;
+                const handoffInput = delegateOriginal ?? (typeof input === "string" ? handoffPrompt : input);
+                const enrichedHandoffInput = appendHandoffInstruction(
+                  handoffInput,
+                  inputText(input),
+                  handoffPrompt
+                );
+                this.emitEvent({
+                  type: "ask_start",
+                  prompt: inputText(enrichedHandoffInput),
+                  ...typeof enrichedHandoffInput === "string" ? {} : { input: describeModelInput(enrichedHandoffInput) }
+                });
                 const targetAskStart = Date.now();
                 try {
                   const result = await this.executeAgentCall(
                     descriptor.agent,
-                    handoffPrompt,
+                    enrichedHandoffInput,
                     handoffOptions,
                     currentMessages,
-                    usageCapture
+                    usageCapture,
+                    sessionHistory
                   );
                   this.emitEvent({
                     type: "ask_end",
@@ -8489,11 +10800,13 @@ ${appendedSchemaText}`;
                   });
                   return result;
                 } catch (err) {
+                  const richHandoff = typeof enrichedHandoffInput !== "string" || hasRichMessage(sessionHistory);
+                  if (richHandoff) this.recordRichFailure(err);
                   this.emitEvent({
                     type: "ask_end",
                     outcome: {
                       ok: false,
-                      error: err instanceof Error ? err.message : String(err)
+                      error: this._observerErrorProjection(err)?.message ?? legacyErrorMessage(err)
                     },
                     cost: targetFrame.askCost.value,
                     ...targetFrame.askUnpriced ? { unpriced: true } : {},
@@ -9002,12 +11315,12 @@ ${appendedSchemaText}`;
         content: `Summary of earlier conversation:
 ${this.summaryCache}`
       };
-      const summaryTokens = estimateTokens(summaryMsg2.content) + 4;
+      const summaryTokens = estimateTokens(summarizeModelInput(summaryMsg2.content)) + 4;
       const remaining = availableTokens - summaryTokens;
       let recentTokens2 = 0;
       let splitIdx2 = history.length;
       for (let i = history.length - 1; i >= 0; i--) {
-        const msgTokens = estimateTokens(history[i].content) + 4;
+        const msgTokens = estimateTokens(summarizeModelInput(history[i].content)) + 4;
         if (recentTokens2 + msgTokens > remaining) break;
         recentTokens2 += msgTokens;
         splitIdx2 = i;
@@ -9020,7 +11333,7 @@ ${this.summaryCache}`
     let splitIdx = history.length;
     const targetRecent = Math.floor(availableTokens * 0.6);
     for (let i = history.length - 1; i >= 0; i--) {
-      const msgTokens = estimateTokens(history[i].content) + 4;
+      const msgTokens = estimateTokens(summarizeModelInput(history[i].content)) + 4;
       if (recentTokens + msgTokens > targetRecent) break;
       recentTokens += msgTokens;
       splitIdx = i;
@@ -9038,7 +11351,7 @@ ${this.summaryCache}`
       summaryProvider = provider;
       summaryModel = model;
     }
-    const oldContent = oldMessages.map((m) => `${m.role}: ${m.content}`).join("\n");
+    const oldContent = oldMessages.map((m) => `${m.role}: ${summarizeModelInput(m.content)}`).join("\n");
     const summaryResponse = await summaryProvider.chat(
       [
         {
@@ -10272,7 +12585,9 @@ ${summaryResponse.content}`
         reason: "routed"
       }
     });
-    return this.ask(routerAgent, prompt, {
+    const routerInput = options?.routerInput === "text" ? inputText(prompt) : prompt;
+    routerAgent._delegateOriginalInput = prompt;
+    return this.ask(routerAgent, routerInput, {
       schema: options?.schema,
       schemaPrompt: options?.schemaPrompt,
       nativeStructuredOutput: options?.nativeStructuredOutput,
@@ -10282,6 +12597,278 @@ ${summaryResponse.content}`
       validateRetries: options?.validateRetries
     });
   }
+  /** Transcribe recorded audio through the dedicated transcription registry.
+   * This operation never enters the chat history or chat-provider path. */
+  async transcribe(request) {
+    const startedAt = Date.now();
+    const transcriptionId = (0, import_node_crypto.randomUUID)();
+    const signal = this.currentSignal;
+    const rawAudio = request && typeof request === "object" && "audio" in request ? request.audio : void 0;
+    const source = rawAudio?.type;
+    const requestedUri = typeof request?.model === "string" ? request.model : void 0;
+    const colon = requestedUri?.indexOf(":") ?? -1;
+    const requestedProvider = colon > 0 ? requestedUri.slice(0, colon) : void 0;
+    const requestedModel = colon > 0 && colon < requestedUri.length - 1 ? requestedUri.slice(colon + 1) : void 0;
+    const startAudio = {
+      source: typeof source === "string" ? source : "unknown",
+      ...rawAudio?.data instanceof Uint8Array ? { bytes: rawAudio.data.byteLength } : {},
+      ...typeof rawAudio?.mediaType === "string" ? { mediaType: rawAudio.mediaType } : {}
+    };
+    this.emitEvent({
+      type: "transcription_start",
+      transcriptionId,
+      model: requestedModel,
+      data: {
+        ...requestedProvider ? { provider: requestedProvider } : {},
+        ...requestedModel ? { model: requestedModel } : {},
+        audio: startAudio
+      }
+    });
+    let terminalEmitted = false;
+    const emitTerminal = (partial) => {
+      if (terminalEmitted) return;
+      terminalEmitted = true;
+      this.emitEvent({
+        type: "transcription_end",
+        transcriptionId,
+        model: partial.model,
+        duration: Date.now() - startedAt,
+        ...partial.cost !== void 0 ? { cost: partial.cost } : {},
+        ...partial.tokens ? { tokens: partial.tokens } : {},
+        data: partial.data
+      });
+    };
+    const abortError3 = () => new DOMException("The transcription operation was aborted", "AbortError");
+    const cleanupStatus = (value) => value === "not_required" || value === "deleted" || value === "failed" || value === "timed_out" ? value : void 0;
+    const safeProviderFailure = (error, provider, model) => {
+      const details = error && typeof error === "object" ? error : void 0;
+      const accounting = normalizeTranscriptionAccounting(details?.usage, details?.pricingStatus);
+      const cleanup = cleanupStatus(details?.cleanupStatus);
+      const providerError = error instanceof ProviderError ? error : void 0;
+      const diagnostics = providerError ? {
+        status: providerError.status,
+        retryable: providerError.retryable,
+        ...providerError.retryAfterMs !== void 0 ? { retryAfterMs: providerError.retryAfterMs } : {},
+        ...providerError.requestId ? { requestId: providerError.requestId } : {}
+      } : void 0;
+      return {
+        accounting,
+        cleanup,
+        diagnostics,
+        error: new TranscriptionOperationError({
+          provider,
+          model,
+          ...accounting.usage ? { usage: accounting.usage } : {},
+          ...accounting.pricingStatus ? { pricingStatus: accounting.pricingStatus } : {},
+          ...cleanup ? { cleanupStatus: cleanup } : {},
+          ...diagnostics ?? {},
+          cause: error
+        })
+      };
+    };
+    const terminalData = (status, provider, model, audio, accounting, extras = {}) => ({
+      status,
+      ...provider ? { provider } : {},
+      ...model ? { model } : {},
+      ...audio ? { audio } : {},
+      ...accounting.usage ? { usage: accounting.usage } : {},
+      ...accounting.pricingStatus ? { pricingStatus: accounting.pricingStatus } : {},
+      ...extras
+    });
+    try {
+      const normalized = normalizeTranscriptionRequest(request);
+      const descriptor = {
+        source: normalized.audio.type,
+        ...normalized.audio.type === "bytes" ? { bytes: normalized.audio.data.byteLength } : {},
+        ...normalized.audio.mediaType !== void 0 ? { mediaType: normalized.audio.mediaType } : {}
+      };
+      if (this.currentSignal?.aborted || signal?.aborted) {
+        emitTerminal({
+          model: requestedModel,
+          data: terminalData("aborted", requestedProvider, requestedModel, descriptor, {
+            hasWork: false
+          })
+        });
+        throw abortError3();
+      }
+      if (this.budgetContext?.exceeded) {
+        const { limit, totalCost: spent, policy } = this.budgetContext;
+        if (policy === "warn") {
+          this.emitEvent({
+            type: "log",
+            data: { warning: "Budget exceeded", limit, spent, policy }
+          });
+        } else {
+          throw new BudgetExceededError(limit, spent, policy);
+        }
+      }
+      if (!this.transcriptionProviderRegistry) {
+        throw new InvalidTranscriptionInputError(
+          "No transcription provider registry is configured"
+        );
+      }
+      const resolved = this.transcriptionProviderRegistry.resolve(normalized.model, this.config);
+      if (normalized.audio.type === "provider-file" && normalized.audio.provider !== resolved.providerName) {
+        throw new InvalidTranscriptionInputError(
+          "Transcription provider-file source does not match the requested provider"
+        );
+      }
+      const capabilities = resolved.provider.capabilities(resolved.model);
+      if (!capabilities || !capabilities.sources.includes(normalized.audio.type)) {
+        throw new InvalidTranscriptionInputError(
+          "The requested transcription model does not support this audio source"
+        );
+      }
+      if (normalized.timestamps && !capabilities.timestamps?.includes(normalized.timestamps)) {
+        throw new InvalidTranscriptionInputError(
+          "The requested transcription model does not support requested timestamps"
+        );
+      }
+      if (normalized.diarization && !capabilities.diarization) {
+        throw new InvalidTranscriptionInputError(
+          "The requested transcription model does not support diarization"
+        );
+      }
+      const providerRequest = {
+        ...normalized,
+        model: resolved.model,
+        ...signal ? { signal } : {}
+      };
+      let result;
+      try {
+        result = await resolved.provider.transcribe(providerRequest);
+      } catch (error) {
+        const failure = safeProviderFailure(error, resolved.providerName, resolved.model);
+        if (this.currentSignal?.aborted || signal?.aborted) {
+          if (failure.accounting.cost !== void 0)
+            this._accumulateBudgetCost(failure.accounting.cost);
+          emitTerminal({
+            model: resolved.model,
+            ...failure.accounting.cost !== void 0 ? { cost: failure.accounting.cost } : {},
+            ...failure.accounting.tokens ? { tokens: failure.accounting.tokens } : {},
+            data: terminalData(
+              "aborted",
+              resolved.providerName,
+              resolved.model,
+              descriptor,
+              failure.accounting,
+              ...failure.cleanup ? [{ cleanupStatus: failure.cleanup }] : []
+            )
+          });
+          throw abortError3();
+        }
+        if (failure.accounting.cost !== void 0)
+          this._accumulateBudgetCost(failure.accounting.cost);
+        emitTerminal({
+          model: resolved.model,
+          ...failure.accounting.cost !== void 0 ? { cost: failure.accounting.cost } : {},
+          ...failure.accounting.tokens ? { tokens: failure.accounting.tokens } : {},
+          data: terminalData(
+            "failed",
+            resolved.providerName,
+            resolved.model,
+            descriptor,
+            failure.accounting,
+            {
+              error: "Transcription operation failed",
+              errorCode: failure.error.code,
+              ...failure.diagnostics ? { providerError: failure.diagnostics } : {},
+              ...failure.cleanup ? { cleanupStatus: failure.cleanup } : {}
+            }
+          )
+        });
+        throw failure.error;
+      }
+      const accounting = normalizeTranscriptionAccounting(
+        result.transcript?.usage,
+        result.transcript?.pricingStatus
+      );
+      if (accounting.cost !== void 0) this._accumulateBudgetCost(accounting.cost);
+      if (this.currentSignal?.aborted || signal?.aborted) {
+        emitTerminal({
+          model: resolved.model,
+          ...accounting.cost !== void 0 ? { cost: accounting.cost } : {},
+          ...accounting.tokens ? { tokens: accounting.tokens } : {},
+          data: terminalData(
+            "aborted",
+            resolved.providerName,
+            resolved.model,
+            descriptor,
+            accounting,
+            ...cleanupStatus(result.cleanupStatus) ? [{ cleanupStatus: cleanupStatus(result.cleanupStatus) }] : []
+          )
+        });
+        throw abortError3();
+      }
+      let transcript;
+      try {
+        transcript = cloneTranscript(result.transcript);
+      } catch (error) {
+        const cleanup = cleanupStatus(result.cleanupStatus);
+        const failure = new TranscriptionOperationError({
+          provider: resolved.providerName,
+          model: resolved.model,
+          ...accounting.usage ? { usage: accounting.usage } : {},
+          ...accounting.pricingStatus ? { pricingStatus: accounting.pricingStatus } : {},
+          ...cleanup ? { cleanupStatus: cleanup } : {},
+          cause: error
+        });
+        emitTerminal({
+          model: resolved.model,
+          ...accounting.cost !== void 0 ? { cost: accounting.cost } : {},
+          ...accounting.tokens ? { tokens: accounting.tokens } : {},
+          data: terminalData(
+            "failed",
+            resolved.providerName,
+            resolved.model,
+            descriptor,
+            accounting,
+            {
+              error: "Transcription operation failed",
+              errorCode: "TRANSCRIPTION_PROVIDER_ERROR",
+              ...cleanup ? { cleanupStatus: cleanup } : {}
+            }
+          )
+        });
+        throw failure;
+      }
+      emitTerminal({
+        model: resolved.model,
+        ...accounting.cost !== void 0 ? { cost: accounting.cost } : {},
+        ...accounting.tokens ? { tokens: accounting.tokens } : {},
+        data: terminalData(
+          "completed",
+          resolved.providerName,
+          resolved.model,
+          descriptor,
+          accounting,
+          {
+            text: transcript.text,
+            ...cleanupStatus(result.cleanupStatus) ? { cleanupStatus: cleanupStatus(result.cleanupStatus) } : {}
+          }
+        )
+      });
+      return transcript;
+    } catch (error) {
+      if (!terminalEmitted) {
+        const aborted = signal?.aborted || error instanceof Error && error.name === "AbortError";
+        emitTerminal({
+          model: requestedModel,
+          data: terminalData(
+            aborted ? "aborted" : "failed",
+            requestedProvider,
+            requestedModel,
+            void 0,
+            { hasWork: false },
+            {
+              error: aborted ? "Transcription operation aborted" : "Transcription operation failed"
+            }
+          )
+        });
+      }
+      throw error;
+    }
+  }
   // ── Private ───────────────────────────────────────────────────────────
   /**
    * Internal emitter input — intentionally loose so call sites don't need to
@@ -10297,7 +12884,7 @@ ${summaryResponse.content}`
     const cost = partial.cost;
     if (COST_BEARING_LEAF_TYPES.includes(partial.type)) {
       const usable = isUsableCost(cost);
-      const unpriced = !usable && hasPositiveTokens(
+      const unpriced = !usable && hasPositiveBillableWork(
         partial
       );
       if (frame) {
@@ -10402,11 +12989,13 @@ function agent(config) {
     _name: defaultName,
     async ask(prompt, options) {
       const registry = new ProviderRegistry();
+      const transcriptionRegistry = new TranscriptionProviderRegistry();
       const ctx = new WorkflowContext({
         input: prompt,
         executionId: (0, import_node_crypto2.randomUUID)(),
         config: {},
-        providerRegistry: registry
+        providerRegistry: registry,
+        transcriptionProviderRegistry: transcriptionRegistry
       });
       return ctx.ask(agentInstance, prompt, options);
     },
@@ -10466,7 +13055,7 @@ var MemoryStore = class {
     return data !== void 0 ? structuredClone(data) : null;
   }
   async saveSession(sessionId, history) {
-    this.sessions.set(sessionId, structuredClone(history));
+    this.sessions.set(sessionId, structuredClone(normalizePersistedSessionHistory(history)));
   }
   async getSession(sessionId) {
     const history = this.sessions.get(sessionId);
@@ -10890,7 +13479,7 @@ var SQLiteStore = class {
     const stmt = this.db.prepare(
       "INSERT OR REPLACE INTO sessions (session_id, history) VALUES (?, ?)"
     );
-    stmt.run(sessionId, JSON.stringify(history));
+    stmt.run(sessionId, JSON.stringify(normalizePersistedSessionHistory(history)));
   }
   async getSession(sessionId) {
     const stmt = this.db.prepare("SELECT history FROM sessions WHERE session_id = ?");
@@ -11458,7 +14047,7 @@ var AxlStream = class extends import_node_stream.Readable {
   /** Signal an error. `executionId` is required for the same reason as
    *  `_done`: terminal events must carry a real id even when the
    *  failure happens before any real trace event fires (review S4). */
-  _error(error, executionId) {
+  _error(error, executionId, observerMessage = error.message, observerName = error.name) {
     if (this.events.isFinished) return;
     const errorEvent = {
       schemaVersion: 2,
@@ -11466,7 +14055,7 @@ var AxlStream = class extends import_node_stream.Readable {
       executionId,
       step: Number.MAX_SAFE_INTEGER,
       timestamp: Date.now(),
-      data: { message: error.message, name: error.name }
+      data: { message: observerMessage, name: observerName }
     };
     this.events._push(errorEvent);
     this.push(errorEvent);
@@ -12193,6 +14782,10 @@ var StreamingFlusher = class {
 function isAbortError4(err) {
   return typeof err === "object" && err !== null && err.name === "AbortError";
 }
+function executionErrorProjection(ctx, error) {
+  const safe = ctx?._observerErrorProjection(error);
+  return safe ?? { message: error instanceof Error ? error.message : String(error) };
+}
 function pushEventBounded(execInfo, event, cap) {
   if (STREAMING_EXCLUDED_TYPES.has(event.type)) return;
   if (cap === Infinity || execInfo.events.length < cap) {
@@ -12287,6 +14880,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   tools = /* @__PURE__ */ new Map();
   agents = /* @__PURE__ */ new Map();
   providerRegistry;
+  transcriptionProviderRegistry;
   stateStore;
   executions = /* @__PURE__ */ new Map();
   pendingDecisionResolvers = /* @__PURE__ */ new Map();
@@ -12342,6 +14936,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
     super();
     this.config = resolveConfig(config ?? {});
     this.providerRegistry = new ProviderRegistry();
+    this.transcriptionProviderRegistry = new TranscriptionProviderRegistry();
     this.stateStore = this.createStateStore();
     const requested = this.config.state?.maxEventsPerExecution;
     if (requested === void 0) {
@@ -12490,7 +15085,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       execInfo.status = "failed";
       execInfo.completedAt = Date.now();
       execInfo.duration = execInfo.completedAt - execInfo.startedAt;
-      execInfo.error = terminalError instanceof Error ? terminalError.message : String(terminalError);
+      execInfo.error = executionErrorProjection(ctx, terminalError).message;
       execInfo.observation = observation;
       ctx._emitWorkflowEnd({
         status: "failed",
@@ -12745,6 +15340,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       metadata: options?.metadata,
       config: this.config,
       providerRegistry: this.providerRegistry,
+      transcriptionProviderRegistry: this.transcriptionProviderRegistry,
       stateStore: this.stateStore,
       mcpManager: this.mcpManager,
       spanManager: this.spanManager,
@@ -12773,6 +15369,10 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   registerProvider(name, provider) {
     this.providerRegistry.registerInstance(name, provider);
   }
+  /** Register a dedicated transcription adapter. It is never used for chat. */
+  registerTranscriptionProvider(name, provider) {
+    this.transcriptionProviderRegistry.registerInstance(name, provider);
+  }
   /** Resolve a provider:model URI to a Provider instance and model name. */
   resolveProvider(uri) {
     return this.providerRegistry.resolve(uri, this.config);
@@ -12816,6 +15416,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
       metadata: options?.metadata,
       config: this.config,
       providerRegistry: this.providerRegistry,
+      transcriptionProviderRegistry: this.transcriptionProviderRegistry,
       sessionHistory,
       signal: controller.signal,
       eventStreamOptions: options?.events,
@@ -12903,6 +15504,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
     const executionId = (0, import_node_crypto3.randomUUID)();
     this.abortControllers.set(executionId, controller);
     let execInfo;
+    let wfCtx;
     const run = async () => {
       const workflow2 = this.workflows.get(name);
       if (!workflow2) throw new Error(`Workflow "${name}" not registered`);
@@ -12926,12 +15528,13 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         metadata: liftPersistedMetadata(options?.metadata)
       };
       this.executions.set(executionId, execInfo);
-      const wfCtx = new WorkflowContext({
+      const context = new WorkflowContext({
         input: validated,
         executionId,
         metadata: options?.metadata,
         config: this.config,
         providerRegistry: this.providerRegistry,
+        transcriptionProviderRegistry: this.transcriptionProviderRegistry,
         sessionHistory,
         signal: controller.signal,
         eventStreamOptions: options?.events,
@@ -12996,6 +15599,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
           unpricedWarned: false
         }
       });
+      wfCtx = context;
       return this.spanManager.withSpanAsync(
         "axl.workflow.execute",
         {
@@ -13005,7 +15609,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         },
         (span) => this.runWorkflowBody({
           workflow: workflow2,
-          ctx: wfCtx,
+          ctx: context,
           execInfo,
           validated,
           span,
@@ -13018,12 +15622,14 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         execInfo.status = "failed";
         execInfo.completedAt = Date.now();
         execInfo.duration = execInfo.completedAt - execInfo.startedAt;
-        execInfo.error = err instanceof Error ? err.message : String(err);
+        execInfo.error = executionErrorProjection(wfCtx, err).message;
         this.persistExecution(execInfo);
       }
       this.abortControllers.delete(executionId);
       cleanupAbortForwarder();
-      axlStream._error(err instanceof Error ? err : new Error(String(err)), executionId);
+      const originalError = err instanceof Error ? err : new Error(String(err));
+      const projection = executionErrorProjection(wfCtx, err);
+      axlStream._error(originalError, executionId, projection.message, projection.name);
     });
     return axlStream;
   }
@@ -13434,7 +16040,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
         },
         {
           role: "user",
-          content: messages.map((m) => `${m.role}: ${m.content}`).join("\n")
+          content: messages.map((m) => `${m.role}: ${summarizeModelInput(m.content)}`).join("\n")
         }
       ],
       { model, maxTokens: 1024 }
@@ -13881,7 +16487,7 @@ async function registerConditions(conditions) {
     ].join("\n");
     nodeModule.register(`data:text/javascript,${encodeURIComponent(hookCode)}`);
   } catch {
-    console.warn("Warning: --conditions requires Node.js 20.6+");
+    console.warn("Warning: this Node.js runtime does not support --conditions");
   }
 }
 
@@ -14190,7 +16796,11 @@ var RedisStore = class _RedisStore {
   async saveSession(sessionId, history) {
     const ttl = this.ttlFor("session");
     const setOptions = ttl !== void 0 ? { EX: ttl } : void 0;
-    await this.client.multi().set(this.sessionKey(sessionId), JSON.stringify(history), setOptions).sAdd(this.sessionIdsKey(), sessionId).exec();
+    await this.client.multi().set(
+      this.sessionKey(sessionId),
+      JSON.stringify(normalizePersistedSessionHistory(history)),
+      setOptions
+    ).sAdd(this.sessionIdsKey(), sessionId).exec();
   }
   async getSession(sessionId) {
     const raw = await this.client.get(this.sessionKey(sessionId));
@@ -14679,10 +17289,15 @@ function cosineSimilarity2(a, b) {
   EventStreamOverflowError,
   GROQ_PROFILE,
   GeminiProvider,
+  GeminiTranscriptionProvider,
   GuardrailError,
   InMemoryVectorStore,
+  InvalidModelInputError,
+  InvalidTranscriptionInputError,
   LLAMACPP_PROFILE,
   LMSTUDIO_PROFILE,
+  MAX_INLINE_MODEL_INPUT_BYTES,
+  MAX_INLINE_TRANSCRIPTION_BYTES,
   MISTRAL_PROFILE,
   MaxTurnsError,
   McpManager,
@@ -14698,6 +17313,8 @@ function cosineSimilarity2(a, b) {
   OpenAIEmbedder,
   OpenAIProvider,
   OpenAIResponsesProvider,
+  OpenAITranscriptionProvider,
+  OpenRouterTranscriptionProvider,
   ProviderError,
   ProviderRegistry,
   QuorumNotMet,
@@ -14713,7 +17330,11 @@ function cosineSimilarity2(a, b) {
   TimeoutError,
   ToolFailure,
   ToolModelOutputError,
+  TranscriptionOperationError,
+  TranscriptionProviderRegistry,
   UnsupportedEventSchemaVersionError,
+  UnsupportedModelInputError,
+  UnsupportedTranscriptionInputError,
   VLLM_PROFILE,
   ValidationError,
   VerifyError,
@@ -14730,8 +17351,10 @@ function cosineSimilarity2(a, b) {
   findConfig,
   getEventSchemaVersion,
   getExecutionEventSchemaVersion,
+  hasPositiveBillableWork,
   hasPositiveTokens,
   importModule,
+  inputText,
   isCostBearingLeaf,
   isRetryableStatus,
   isRootLevel,