@effect/ai-openrouter 4.0.0-beta.1 → 4.0.0-beta.100

package/src/OpenRouterLanguageModel.ts

@@ -1,18 +1,26 @@
 /**
- * @since 1.0.0
+ * The `OpenRouterLanguageModel` module provides the OpenRouter implementation
+ * of Effect AI's `LanguageModel` service. It translates provider-neutral
+ * prompts, tools, files, structured output requests, reasoning metadata,
+ * cache-control hints, and provider options into OpenRouter chat completion
+ * requests, records GenAI telemetry around those calls, and converts normal or
+ * streaming results back into Effect AI response content and metadata.
+ *
+ * @since 4.0.0
  */
 /** @effect-diagnostics preferSchemaOverJson:skip-file */
 import * as Arr from "effect/Array"
+import * as Context from "effect/Context"
 import * as DateTime from "effect/DateTime"
 import * as Effect from "effect/Effect"
-import * as Base64 from "effect/encoding/Base64"
+import * as Encoding from "effect/Encoding"
 import { dual } from "effect/Function"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
 import * as Redactable from "effect/Redactable"
 import type * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import type { Span } from "effect/Tracer"
 import type { DeepMutable, Mutable, Simplify } from "effect/Types"
@@ -37,12 +45,19 @@ import { type ChatStreamingResponseChunkData, OpenRouterClient } from "./OpenRou
 // =============================================================================
 
 /**
- * Service definition for OpenRouter language model configuration.
+ * Context service for OpenRouter language model configuration.
+ *
+ * **When to use**
+ *
+ * Use to provide scoped OpenRouter chat completion defaults or per-operation
+ * overrides for an OpenRouter language model service.
+ *
+ * @see {@link withConfigOverride} for scoping language model request overrides
  *
- * @since 1.0.0
  * @category services
+ * @since 4.0.0
  */
-export class Config extends ServiceMap.Service<
+export class Config extends Context.Service<
   Config,
   Simplify<
     & Partial<
@@ -68,14 +83,20 @@ export class Config extends ServiceMap.Service<
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * OpenRouter assistant reasoning detail blocks preserved for multi-turn
+ * conversations.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ReasoningDetails = Exclude<typeof Generated.AssistantMessage.Encoded["reasoning_details"], undefined>
 
 /**
- * @since 1.0.0
+ * File annotations emitted on OpenRouter assistant messages and exposed in
+ * finish metadata.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type FileAnnotation = Extract<
   NonNullable<typeof Generated.AssistantMessage.fields.annotations.Type>[number],
@@ -83,7 +104,21 @@ export type FileAnnotation = Extract<
 >
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * OpenRouter-specific options for system messages.
+   *
+   * **Details**
+   *
+   * These options are used when translating system instructions into
+   * OpenRouter chat messages.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface SystemMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the system message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -92,7 +127,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for user messages.
+   *
+   * **Details**
+   *
+   * These options are used when translating user content into OpenRouter chat
+   * messages.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface UserMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the user message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -101,7 +150,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for assistant messages.
+   *
+   * **Details**
+   *
+   * Preserves reasoning metadata when assistant messages are replayed in later
+   * OpenRouter requests.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface AssistantMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the assistant message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -114,7 +177,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for tool messages.
+   *
+   * **Details**
+   *
+   * These options are used when converting tool results into OpenRouter chat
+   * messages.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the tool message.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -123,7 +200,20 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for text prompt parts.
+   *
+   * **When to use**
+   *
+   * Use when you use these options to control how text content is sent to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface TextPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the text part.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -132,7 +222,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for reasoning prompt parts.
+   *
+   * **Details**
+   *
+   * Preserves provider reasoning blocks so reasoning-aware conversations can
+   * continue across OpenRouter requests.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ReasoningPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the reasoning part.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -145,7 +249,20 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for file prompt parts.
+   *
+   * **Details**
+   *
+   * Controls file naming and prompt caching for files sent to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface FilePartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the file part.
+     */
     readonly openrouter?: {
       /**
        * The name to give to the file. Will be prioritized over the file name
@@ -159,7 +276,21 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for tool call prompt parts.
+   *
+   * **Details**
+   *
+   * Preserves reasoning details associated with tool calls when a conversation
+   * is sent back to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolCallPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the tool call part.
+     */
     readonly openrouter?: {
       /**
        * Reasoning details associated with the tool call part.
@@ -168,7 +299,20 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenRouter-specific options for tool result prompt parts.
+   *
+   * **Details**
+   *
+   * Controls prompt caching for tool results sent to OpenRouter.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolResultPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific options sent to OpenRouter for the tool result part.
+     */
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
@@ -179,43 +323,157 @@ declare module "effect/unstable/ai/Prompt" {
 }
 
 declare module "effect/unstable/ai/Response" {
+  /**
+   * OpenRouter metadata attached to completed reasoning response parts.
+   *
+   * **Details**
+   *
+   * Preserves provider reasoning details that can be sent back in later turns.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the reasoning part.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details emitted by the underlying provider for this part.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata emitted when a streamed reasoning part starts.
+   *
+   * **Details**
+   *
+   * Carries the first reasoning detail chunk when OpenRouter exposes one.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning start.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details emitted by the underlying provider for this part.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata emitted for streamed reasoning deltas.
+   *
+   * **Details**
+   *
+   * Carries provider reasoning detail chunks as they arrive from OpenRouter.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning delta.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details emitted by the underlying provider for this delta.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata attached to tool-call response parts.
+   *
+   * **Details**
+   *
+   * Associates tool calls with provider reasoning details when the model emits
+   * reasoning and tool calls together.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolCallPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the tool call.
+     */
     readonly openrouter?: {
+      /**
+       * Reasoning details associated with this tool call.
+       */
       readonly reasoningDetails?: ReasoningDetails | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata attached to URL source citations.
+   *
+   * **Details**
+   *
+   * Includes citation text and offsets returned by providers that support URL
+   * annotations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific citation metadata returned for the URL source.
+     */
     readonly openrouter?: {
+      /**
+       * The cited source content returned by the provider.
+       */
       readonly content?: string | null
+      /**
+       * The zero-based start index of the citation in the generated text.
+       */
       readonly startIndex?: number | null
+      /**
+       * The zero-based end index of the citation in the generated text.
+       */
       readonly endIndex?: number | null
     } | null
   }
 
+  /**
+   * OpenRouter metadata attached to finish response parts.
+   *
+   * **Details**
+   *
+   * Exposes provider response details that are not represented by the common
+   * Effect AI finish part fields.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface FinishPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned when the OpenRouter response finishes.
+     */
     readonly openrouter?: {
+      /**
+       * Provider fingerprint for the backend configuration that served the request.
+       */
       readonly systemFingerprint?: string | null
+      /**
+       * Raw token usage reported by OpenRouter.
+       */
       readonly usage?: typeof Generated.ChatGenerationTokenUsage.Encoded | null
+      /**
+       * File annotations returned by the provider.
+       */
       readonly annotations?: ReadonlyArray<FileAnnotation> | null
+      /**
+       * The OpenRouter provider that served the request, when reported.
+       */
       readonly provider?: string | null
     } | null
   }
@@ -226,20 +484,59 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * Creates an OpenRouter model descriptor that can be provided with
+ * `Effect.provide`.
+ *
+ * **When to use**
+ *
+ * Use when you want an OpenRouter language model value that carries provider
+ * and model metadata and can be supplied directly to an Effect program.
+ *
+ * **Details**
+ *
+ * The returned model requires `OpenRouterClient` and provides
+ * `LanguageModel.LanguageModel`.
+ *
+ * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link withConfigOverride} for scoping OpenRouter request overrides
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: string,
   config?: Omit<typeof Config.Service, "model">
 ): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenRouterClient> =>
-  AiModel.make("openai", layer({ model, config }))
+  AiModel.make("openai", model, layer({ model, config }))
 
 /**
- * Creates an OpenRouter language model service.
+ * Creates an OpenRouter `LanguageModel` service from a model identifier and
+ * optional request defaults.
+ *
+ * **When to use**
+ *
+ * Use when you need to construct a `LanguageModel.Service` value backed by
+ * `OpenRouterClient` inside an Effect.
+ *
+ * **Details**
+ *
+ * The returned effect requires `OpenRouterClient`. Request defaults from the
+ * `config` option are merged with any `Config` service in the context, with
+ * context values taking precedence. The service supports both `generateText`
+ * and `streamText`.
+ *
+ * **Gotchas**
+ *
+ * Provider-defined tools are not supported by this provider integration;
+ * requests that include them fail with an `InvalidUserInputError`.
+ *
+ * @see {@link layer} for providing the service as a `Layer`
+ * @see {@link model} for creating a model descriptor for `Effect.provide`
+ * @see {@link withConfigOverride} for scoping request defaults around operations
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: string
@@ -249,7 +546,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   const codecTransformer = getCodecTransformer(model)
 
   const makeConfig = Effect.gen(function*() {
-    const services = yield* Effect.services<never>()
+    const services = yield* Effect.context<never>()
     return { model, ...providerConfig, ...services.mapUnsafe.get(Config.key) }
   })
 
@@ -273,6 +570,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   )
 
   return yield* LanguageModel.make({
+    codecTransformer: toCodecOpenAI,
     generateText: Effect.fnUntraced(
       function*(options) {
         const config = yield* makeConfig
@@ -300,17 +598,23 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
           })
         )
     )
-  }).pipe(Effect.provideService(
-    LanguageModel.CurrentCodecTransformer,
-    codecTransformer
-  ))
+  })
 })
 
 /**
  * Creates a layer for the OpenRouter language model.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use when composing application layers and you want OpenRouter to satisfy
+ * `LanguageModel.LanguageModel` while supplying `OpenRouterClient` from another
+ * layer.
+ *
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link model} for creating a model descriptor for `Effect.provide`
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: string
@@ -321,37 +625,107 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenRouter language model operations.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use to apply OpenRouter request configuration to one effect without changing
+ * the model's default configuration.
+ *
+ * **Details**
+ *
+ * The overrides are merged with any existing `Config` service for the duration
+ * of the supplied effect. Fields in `overrides` take precedence over existing
+ * config, and the helper supports both pipe form and
+ * `withConfigOverride(effect, overrides)`.
+ *
+ * @see {@link Config} for available OpenRouter request configuration fields
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
 } = dual<
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
   /**
    * Provides config overrides for OpenRouter language model operations.
    *
-   * @since 1.0.0
+   * **When to use**
+   *
+   * Use to apply OpenRouter request configuration to one effect without changing
+   * the model's default configuration.
+   *
+   * **Details**
+   *
+   * The overrides are merged with any existing `Config` service for the duration
+   * of the supplied effect. Fields in `overrides` take precedence over existing
+   * config, and the helper supports both pipe form and
+   * `withConfigOverride(effect, overrides)`.
+   *
+   * @see {@link Config} for available OpenRouter request configuration fields
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
 >(2, (self, overrides) =>
@@ -451,7 +825,7 @@ const prepareMessages = Effect.fnUntraced(
                       url: part.data instanceof URL
                         ? part.data.toString()
                         : part.data instanceof Uint8Array
-                        ? `data:${mediaType};base64,${Base64.encode(part.data)}`
+                        ? `data:${mediaType};base64,${Encoding.encodeBase64(part.data)}`
                         : part.data
                     },
                     ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
@@ -460,6 +834,45 @@ const prepareMessages = Effect.fnUntraced(
                   break
                 }
 
+                if (part.mediaType.startsWith("audio/")) {
+                  const format = audioFormats[part.mediaType.toLowerCase()]
+
+                  if (Predicate.isUndefined(format)) {
+                    return yield* AiError.make({
+                      module: "OpenRouterLanguageModel",
+                      method: "prepareMessages",
+                      reason: new AiError.InvalidUserInputError({
+                        description: `Detected unsupported media type for audio file: '${part.mediaType}' ` +
+                          `- OpenRouter supports ${supportedAudioFormats} audio`
+                      })
+                    })
+                  }
+
+                  if (part.data instanceof URL) {
+                    return yield* AiError.make({
+                      module: "OpenRouterLanguageModel",
+                      method: "prepareMessages",
+                      reason: new AiError.InvalidUserInputError({
+                        description: "Detected URL data for audio file - OpenRouter requires " +
+                          "audio to be provided as base64-encoded data"
+                      })
+                    })
+                  }
+
+                  content.push({
+                    type: "input_audio",
+                    input_audio: {
+                      data: part.data instanceof Uint8Array
+                        ? Encoding.encodeBase64(part.data)
+                        : getBase64FromDataUrl(part.data),
+                      format
+                    },
+                    ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
+                  })
+
+                  break
+                }
+
                 const options = part.options.openrouter
                 const fileName = options?.fileName ?? part.fileName ?? ""
 
@@ -470,7 +883,7 @@ const prepareMessages = Effect.fnUntraced(
                     file_data: part.data instanceof URL
                       ? part.data.toString()
                       : part.data instanceof Uint8Array
-                      ? `data:${part.mediaType};base64,${Base64.encode(part.data)}`
+                      ? `data:${part.mediaType};base64,${Encoding.encodeBase64(part.data)}`
                       : part.data
                   },
                   ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
@@ -588,7 +1001,7 @@ const buildHttpRequestDetails = (
   method: request.method,
   url: request.url,
   urlParams: Array.from(request.urlParams),
-  hash: request.hash,
+  hash: Option.getOrUndefined(request.hash),
   headers: Redactable.redact(request.headers) as Record<string, string>
 })
 
@@ -830,12 +1243,12 @@ const makeStreamResponse = Effect.fnUntraced(
     let activeTextId: string | undefined = undefined
 
     let totalToolCalls = 0
-    const activeToolCalls: Array<{
+    const activeToolCalls: Record<number, {
       readonly id: string
       readonly type: "function"
       readonly name: string
       params: string
-    }> = []
+    }> = {}
 
     // Track reasoning details to preserve for multi-turn conversations
     const accumulatedReasoningDetails: DeepMutable<ReasoningDetails> = []
@@ -885,283 +1298,275 @@ const makeStreamResponse = Effect.fnUntraced(
         }
 
         const choice = event.choices[0]
-        if (Predicate.isUndefined(choice)) {
-          return yield* AiError.make({
-            module: "OpenRouterLanguageModel",
-            method: "makeStreamResponse",
-            reason: new AiError.InvalidOutputError({
-              description: "Received response with empty choices"
-            })
-          })
-        }
-
-        if (Predicate.isNotNull(choice.finish_reason)) {
-          finishReason = resolveFinishReason(choice.finish_reason)
-        }
+        if (Predicate.isNotUndefined(choice)) {
+          if (Predicate.isNotNullish(choice.finish_reason)) {
+            finishReason = resolveFinishReason(choice.finish_reason)
+          }
 
-        const delta = choice.delta
-        if (Predicate.isNullish(delta)) {
-          return parts
-        }
+          const delta = choice.delta
+          if (Predicate.isNullish(delta)) {
+            return parts
+          }
 
-        const emitReasoning = Effect.fnUntraced(
-          function*(delta: string, metadata?: Response.ReasoningDeltaPart["metadata"] | undefined) {
-            if (!reasoningStarted) {
-              activeReasoningId = openRouterResponseId ?? (yield* idGenerator.generateId())
+          const emitReasoning = Effect.fnUntraced(
+            function*(delta: string, metadata?: Response.ReasoningDeltaPart["metadata"] | undefined) {
+              if (!reasoningStarted) {
+                activeReasoningId = openRouterResponseId ?? (yield* idGenerator.generateId())
+                parts.push({
+                  type: "reasoning-start",
+                  id: activeReasoningId,
+                  metadata
+                })
+                reasoningStarted = true
+              }
               parts.push({
-                type: "reasoning-start",
-                id: activeReasoningId,
+                type: "reasoning-delta",
+                id: activeReasoningId!,
+                delta,
                 metadata
               })
-              reasoningStarted = true
             }
-            parts.push({
-              type: "reasoning-delta",
-              id: activeReasoningId!,
-              delta,
-              metadata
-            })
-          }
-        )
+          )
 
-        const reasoningDetails = delta.reasoning_details
-        if (Predicate.isNotUndefined(reasoningDetails) && reasoningDetails.length > 0) {
-          // Accumulate reasoning_details to preserve for multi-turn conversations
-          // Merge consecutive reasoning.text items into a single entry
-          for (const detail of reasoningDetails) {
-            if (detail.type === "reasoning.text") {
-              const lastDetail = accumulatedReasoningDetails[accumulatedReasoningDetails.length - 1]
-              if (Predicate.isNotUndefined(lastDetail) && lastDetail.type === "reasoning.text") {
-                // Merge with the previous text detail
-                lastDetail.text = (lastDetail.text ?? "") + (detail.text ?? "")
-                lastDetail.signature = lastDetail.signature ?? detail.signature ?? null
-                lastDetail.format = lastDetail.format ?? detail.format ?? null
+          const reasoningDetails = delta.reasoning_details
+          if (Predicate.isNotUndefined(reasoningDetails) && reasoningDetails.length > 0) {
+            // Accumulate reasoning_details to preserve for multi-turn conversations
+            // Merge consecutive reasoning.text items into a single entry
+            for (const detail of reasoningDetails) {
+              if (detail.type === "reasoning.text") {
+                const lastDetail = accumulatedReasoningDetails[accumulatedReasoningDetails.length - 1]
+                if (Predicate.isNotUndefined(lastDetail) && lastDetail.type === "reasoning.text") {
+                  // Merge with the previous text detail
+                  lastDetail.text = (lastDetail.text ?? "") + (detail.text ?? "")
+                  lastDetail.signature = lastDetail.signature ?? detail.signature ?? null
+                  lastDetail.format = lastDetail.format ?? detail.format ?? null
+                } else {
+                  // Start a new text detail
+                  accumulatedReasoningDetails.push({ ...detail })
+                }
               } else {
-                // Start a new text detail
-                accumulatedReasoningDetails.push({ ...detail })
+                // Non-text details (encrypted, summary) are pushed as-is
+                accumulatedReasoningDetails.push(detail)
               }
-            } else {
-              // Non-text details (encrypted, summary) are pushed as-is
-              accumulatedReasoningDetails.push(detail)
             }
-          }
 
-          // Emit reasoning_details in providerMetadata for each delta chunk
-          // so users can accumulate them on their end before sending back
-          const metadata: Response.ReasoningDeltaPart["metadata"] = {
-            openrouter: {
-              reasoningDetails
+            // Emit reasoning_details in providerMetadata for each delta chunk
+            // so users can accumulate them on their end before sending back
+            const metadata: Response.ReasoningDeltaPart["metadata"] = {
+              openrouter: {
+                reasoningDetails
+              }
             }
-          }
-          for (const detail of reasoningDetails) {
-            switch (detail.type) {
-              case "reasoning.text": {
-                if (Predicate.isNotNullish(detail.text)) {
-                  yield* emitReasoning(detail.text, metadata)
+            for (const detail of reasoningDetails) {
+              switch (detail.type) {
+                case "reasoning.text": {
+                  if (Predicate.isNotNullish(detail.text)) {
+                    yield* emitReasoning(detail.text, metadata)
+                  }
+                  break
                 }
-                break
-              }
 
-              case "reasoning.summary": {
-                if (Predicate.isNotNullish(detail.summary)) {
-                  yield* emitReasoning(detail.summary, metadata)
+                case "reasoning.summary": {
+                  if (Predicate.isNotNullish(detail.summary)) {
+                    yield* emitReasoning(detail.summary, metadata)
+                  }
+                  break
                 }
-                break
-              }
 
-              case "reasoning.encrypted": {
-                if (Predicate.isNotNullish(detail.data)) {
-                  yield* emitReasoning("[REDACTED]", metadata)
+                case "reasoning.encrypted": {
+                  if (Predicate.isNotNullish(detail.data)) {
+                    yield* emitReasoning("[REDACTED]", metadata)
+                  }
+                  break
                 }
-                break
               }
             }
+          } else if (Predicate.isNotNullish(delta.reasoning)) {
+            yield* emitReasoning(delta.reasoning)
           }
-        } else if (Predicate.isNotNullish(delta.reasoning)) {
-          yield* emitReasoning(delta.reasoning)
-        }
 
-        const content = delta.content
-        if (Predicate.isNotNullish(content)) {
-          // If reasoning was previously active and now we're starting text content,
-          // we should end the reasoning first to maintain proper order
-          if (reasoningStarted && !textStarted) {
-            parts.push({
-              type: "reasoning-end",
-              id: activeReasoningId!,
-              // Include accumulated reasoning_details so the we can update the
-              // reasoning part's provider metadata with the correct signature.
-              // The signature typically arrives in the last reasoning delta,
-              // but reasoning-start only carries the first delta's metadata.
-              metadata: accumulatedReasoningDetails.length > 0
-                ? { openRouter: { reasoningDetails: accumulatedReasoningDetails } }
-                : undefined
-            })
-            reasoningStarted = false
-          }
+          const content = delta.content
+          if (Predicate.isNotNullish(content)) {
+            // If reasoning was previously active and now we're starting text content,
+            // we should end the reasoning first to maintain proper order
+            if (reasoningStarted && !textStarted) {
+              parts.push({
+                type: "reasoning-end",
+                id: activeReasoningId!,
+                // Include accumulated reasoning_details so the we can update the
+                // reasoning part's provider metadata with the correct signature.
+                // The signature typically arrives in the last reasoning delta,
+                // but reasoning-start only carries the first delta's metadata.
+                metadata: accumulatedReasoningDetails.length > 0
+                  ? { openRouter: { reasoningDetails: accumulatedReasoningDetails } }
+                  : undefined
+              })
+              reasoningStarted = false
+            }
+
+            if (!textStarted) {
+              activeTextId = openRouterResponseId ?? (yield* idGenerator.generateId())
+              parts.push({
+                type: "text-start",
+                id: activeTextId
+              })
+              textStarted = true
+            }
 
-          if (!textStarted) {
-            activeTextId = openRouterResponseId ?? (yield* idGenerator.generateId())
             parts.push({
-              type: "text-start",
-              id: activeTextId
+              type: "text-delta",
+              id: activeTextId!,
+              delta: content
             })
-            textStarted = true
           }
 
-          parts.push({
-            type: "text-delta",
-            id: activeTextId!,
-            delta: content
-          })
-        }
-
-        const annotations = delta.annotations
-        if (Predicate.isNotNullish(annotations)) {
-          for (const annotation of annotations) {
-            if (annotation.type === "url_citation") {
-              parts.push({
-                type: "source",
-                sourceType: "url",
-                id: annotation.url_citation.url,
-                url: annotation.url_citation.url,
-                title: annotation.url_citation.title ?? "",
-                metadata: {
-                  openrouter: {
-                    ...(Predicate.isNotUndefined(annotation.url_citation.content)
-                      ? { content: annotation.url_citation.content }
-                      : undefined),
-                    ...(Predicate.isNotUndefined(annotation.url_citation.start_index)
-                      ? { startIndex: annotation.url_citation.start_index }
-                      : undefined),
-                    ...(Predicate.isNotUndefined(annotation.url_citation.end_index)
-                      ? { startIndex: annotation.url_citation.end_index }
-                      : undefined)
+          const annotations = delta.annotations
+          if (Predicate.isNotNullish(annotations)) {
+            for (const annotation of annotations) {
+              if (annotation.type === "url_citation") {
+                parts.push({
+                  type: "source",
+                  sourceType: "url",
+                  id: annotation.url_citation.url,
+                  url: annotation.url_citation.url,
+                  title: annotation.url_citation.title ?? "",
+                  metadata: {
+                    openrouter: {
+                      ...(Predicate.isNotUndefined(annotation.url_citation.content)
+                        ? { content: annotation.url_citation.content }
+                        : undefined),
+                      ...(Predicate.isNotUndefined(annotation.url_citation.start_index)
+                        ? { startIndex: annotation.url_citation.start_index }
+                        : undefined),
+                      ...(Predicate.isNotUndefined(annotation.url_citation.end_index)
+                        ? { startIndex: annotation.url_citation.end_index }
+                        : undefined)
+                    }
                   }
-                }
-              })
-            } else if (annotation.type === "file") {
-              accumulatedFileAnnotations.push(annotation)
+                })
+              } else if (annotation.type === "file") {
+                accumulatedFileAnnotations.push(annotation)
+              }
             }
           }
-        }
 
-        const toolCalls = delta.tool_calls
-        if (Predicate.isNotNullish(toolCalls)) {
-          for (const toolCall of toolCalls) {
-            const index = toolCall.index ?? toolCalls.length - 1
-            let activeToolCall = activeToolCalls[index]
-
-            // Tool call start - OpenRouter returns all information except the
-            // tool call parameters in the first chunk
-            if (Predicate.isUndefined(activeToolCall)) {
-              if (toolCall.type !== "function") {
-                return yield* AiError.make({
-                  module: "OpenRouterLanguageModel",
-                  method: "makeStreamResponse",
-                  reason: new AiError.InvalidOutputError({
-                    description: "Received tool call delta that was not of type: 'function'"
+          const toolCalls = delta.tool_calls
+          if (Predicate.isNotNullish(toolCalls)) {
+            for (const toolCall of toolCalls) {
+              const index = toolCall.index ?? toolCalls.length - 1
+              let activeToolCall = activeToolCalls[index]
+
+              // Tool call start - OpenRouter returns all information except the
+              // tool call parameters in the first chunk
+              if (Predicate.isUndefined(activeToolCall)) {
+                if (toolCall.type !== "function") {
+                  return yield* AiError.make({
+                    module: "OpenRouterLanguageModel",
+                    method: "makeStreamResponse",
+                    reason: new AiError.InvalidOutputError({
+                      description: "Received tool call delta that was not of type: 'function'"
+                    })
                   })
-                })
-              }
+                }
 
-              if (Predicate.isUndefined(toolCall.id)) {
-                return yield* AiError.make({
-                  module: "OpenRouterLanguageModel",
-                  method: "makeStreamResponse",
-                  reason: new AiError.InvalidOutputError({
-                    description: "Received tool call delta without a tool call identifier"
+                if (Predicate.isNullish(toolCall.id)) {
+                  return yield* AiError.make({
+                    module: "OpenRouterLanguageModel",
+                    method: "makeStreamResponse",
+                    reason: new AiError.InvalidOutputError({
+                      description: "Received tool call delta without a tool call identifier"
+                    })
                   })
-                })
-              }
+                }
 
-              if (Predicate.isUndefined(toolCall.function?.name)) {
-                return yield* AiError.make({
-                  module: "OpenRouterLanguageModel",
-                  method: "makeStreamResponse",
-                  reason: new AiError.InvalidOutputError({
-                    description: "Received tool call delta without a tool call name"
+                if (Predicate.isNullish(toolCall.function?.name)) {
+                  return yield* AiError.make({
+                    module: "OpenRouterLanguageModel",
+                    method: "makeStreamResponse",
+                    reason: new AiError.InvalidOutputError({
+                      description: "Received tool call delta without a tool call name"
+                    })
                   })
-                })
-              }
+                }
 
-              activeToolCall = {
-                id: toolCall.id,
-                type: "function",
-                name: toolCall.function.name,
-                params: toolCall.function.arguments ?? ""
-              }
+                activeToolCall = {
+                  id: toolCall.id,
+                  type: "function",
+                  name: toolCall.function.name,
+                  params: toolCall.function.arguments ?? ""
+                }
 
-              activeToolCalls[index] = activeToolCall
+                activeToolCalls[index] = activeToolCall
 
-              parts.push({
-                type: "tool-params-start",
-                id: activeToolCall.id,
-                name: activeToolCall.name
-              })
+                parts.push({
+                  type: "tool-params-start",
+                  id: activeToolCall.id,
+                  name: activeToolCall.name
+                })
 
-              // Emit a tool call delta part if parameters were also sent
-              if (activeToolCall.params.length > 0) {
+                // Emit a tool call delta part if parameters were also sent
+                if (activeToolCall.params.length > 0) {
+                  parts.push({
+                    type: "tool-params-delta",
+                    id: activeToolCall.id,
+                    delta: activeToolCall.params
+                  })
+                }
+              } else {
+                // If an active tool call was found, update and emit the delta for
+                // the tool call's parameters
+                activeToolCall.params += toolCall.function?.arguments ?? ""
                 parts.push({
                   type: "tool-params-delta",
                   id: activeToolCall.id,
                   delta: activeToolCall.params
                 })
               }
-            } else {
-              // If an active tool call was found, update and emit the delta for
-              // the tool call's parameters
-              activeToolCall.params += toolCall.function?.arguments ?? ""
-              parts.push({
-                type: "tool-params-delta",
-                id: activeToolCall.id,
-                delta: activeToolCall.params
-              })
-            }
 
-            // Check if the tool call is complete
-            // @effect-diagnostics-next-line tryCatchInEffectGen:off
-            try {
-              const params = Tool.unsafeSecureJsonParse(activeToolCall.params)
+              // Check if the tool call is complete
+              // @effect-diagnostics-next-line tryCatchInEffectGen:off
+              try {
+                const params = Tool.unsafeSecureJsonParse(activeToolCall.params)
 
-              parts.push({
-                type: "tool-params-end",
-                id: activeToolCall.id
-              })
+                parts.push({
+                  type: "tool-params-end",
+                  id: activeToolCall.id
+                })
 
-              parts.push({
-                type: "tool-call",
-                id: activeToolCall.id,
-                name: activeToolCall.name,
-                params,
-                // Only attach reasoning_details to the first tool call to avoid
-                // duplicating thinking blocks for parallel tool calls (Claude)
-                metadata: reasoningDetailsAttachedToToolCall ? undefined : {
-                  openrouter: { reasoningDetails: accumulatedReasoningDetails }
-                }
-              })
+                parts.push({
+                  type: "tool-call",
+                  id: activeToolCall.id,
+                  name: activeToolCall.name,
+                  params,
+                  // Only attach reasoning_details to the first tool call to avoid
+                  // duplicating thinking blocks for parallel tool calls (Claude)
+                  metadata: reasoningDetailsAttachedToToolCall ? undefined : {
+                    openrouter: { reasoningDetails: accumulatedReasoningDetails }
+                  }
+                })
 
-              reasoningDetailsAttachedToToolCall = true
+                reasoningDetailsAttachedToToolCall = true
 
-              // Increment the total tool calls emitted by the stream and
-              // remove the active tool call
-              totalToolCalls += 1
-              delete activeToolCalls[toolCall.index]
-            } catch {
-              // Tool call incomplete, continue parsing
-              continue
+                // Increment the total tool calls emitted by the stream and
+                // remove the active tool call
+                totalToolCalls += 1
+                delete activeToolCalls[toolCall.index]
+              } catch {
+                // Tool call incomplete, continue parsing
+                continue
+              }
             }
           }
-        }
 
-        const images = delta.images
-        if (Predicate.isNotNullish(images)) {
-          for (const image of images) {
-            parts.push({
-              type: "file",
-              mediaType: getMediaType(image.image_url.url, "image/jpeg"),
-              data: getBase64FromDataUrl(image.image_url.url)
-            })
+          const images = delta.images
+          if (Predicate.isNotNullish(images)) {
+            for (const image of images) {
+              parts.push({
+                type: "file",
+                mediaType: getMediaType(image.image_url.url, "image/jpeg"),
+                data: getBase64FromDataUrl(image.image_url.url)
+              })
+            }
           }
         }
 
@@ -1180,7 +1585,7 @@ const makeStreamResponse = Effect.fnUntraced(
 
           // Forward any unsent tool calls if finish reason is 'tool-calls'
           if (finishReason === "tool-calls") {
-            for (const toolCall of activeToolCalls) {
+            for (const toolCall of Object.values(activeToolCalls)) {
               // Coerce invalid tool call parameters to an empty object
               let params: unknown
               // @effect-diagnostics-next-line tryCatchInEffectGen:off
@@ -1439,7 +1844,7 @@ const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError
     })
   })
 
-const tryJsonSchema = <S extends Schema.Top>(
+const tryJsonSchema = <S extends Schema.Constraint>(
   schema: S,
   method: string,
   transformer: LanguageModel.CodecTransformer
@@ -1470,6 +1875,32 @@ const getResponseFormat = Effect.fnUntraced(function*({ config, options, transfo
   return undefined
 })
 
+/**
+ * Maps audio media types to the formats supported by OpenRouter.
+ *
+ * @see https://openrouter.ai/docs/guides/overview/multimodal/audio
+ */
+const audioFormats: Record<string, string> = {
+  "audio/aac": "aac",
+  "audio/aiff": "aiff",
+  "audio/x-aiff": "aiff",
+  "audio/flac": "flac",
+  "audio/x-flac": "flac",
+  "audio/l16": "pcm16",
+  "audio/l24": "pcm24",
+  "audio/m4a": "m4a",
+  "audio/x-m4a": "m4a",
+  "audio/mp4": "m4a",
+  "audio/mp3": "mp3",
+  "audio/mpeg": "mp3",
+  "audio/ogg": "ogg",
+  "audio/wav": "wav",
+  "audio/wave": "wav",
+  "audio/x-wav": "wav"
+}
+
+const supportedAudioFormats = Array.from(new Set(Object.values(audioFormats))).join(", ")
+
 const getMediaType = (dataUrl: string, defaultMediaType: string): string => {
   const match = dataUrl.match(/^data:([^;]+)/)
   return match ? (match[1] ?? defaultMediaType) : defaultMediaType