@effect/ai-openrouter 0.8.3 → 4.0.0-beta.0

package/src/OpenRouterLanguageModel.ts

@@ -1,98 +1,95 @@
 /**
  * @since 1.0.0
  */
-import * as AiError from "@effect/ai/AiError"
-import * as LanguageModel from "@effect/ai/LanguageModel"
-import * as AiModel from "@effect/ai/Model"
-import type * as Prompt from "@effect/ai/Prompt"
-import type * as Response from "@effect/ai/Response"
-import { addGenAIAnnotations } from "@effect/ai/Telemetry"
-import * as Tool from "@effect/ai/Tool"
+/** @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 Encoding from "effect/Encoding"
+import * as Base64 from "effect/encoding/Base64"
 import { dual } from "effect/Function"
 import * as Layer from "effect/Layer"
 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 { Simplify } from "effect/Types"
-import type * as Generated from "./Generated.js"
-import * as InternalUtilities from "./internal/utilities.js"
-import type { ChatStreamingResponseChunk } from "./OpenRouterClient.js"
-import { OpenRouterClient } from "./OpenRouterClient.js"
+import type { DeepMutable, Mutable, Simplify } from "effect/Types"
+import * as AiError from "effect/unstable/ai/AiError"
+import { toCodecAnthropic } from "effect/unstable/ai/AnthropicStructuredOutput"
+import * as IdGenerator from "effect/unstable/ai/IdGenerator"
+import * as LanguageModel from "effect/unstable/ai/LanguageModel"
+import * as AiModel from "effect/unstable/ai/Model"
+import { toCodecOpenAI } from "effect/unstable/ai/OpenAiStructuredOutput"
+import type * as Prompt from "effect/unstable/ai/Prompt"
+import type * as Response from "effect/unstable/ai/Response"
+import { addGenAIAnnotations } from "effect/unstable/ai/Telemetry"
+import * as Tool from "effect/unstable/ai/Tool"
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import type * as Generated from "./Generated.ts"
+import { ReasoningDetailsDuplicateTracker, resolveFinishReason } from "./internal/utilities.ts"
+import { type ChatStreamingResponseChunkData, OpenRouterClient } from "./OpenRouterClient.ts"
 
 // =============================================================================
 // Configuration
 // =============================================================================
 
 /**
+ * Service definition for OpenRouter language model configuration.
+ *
  * @since 1.0.0
- * @category Context
+ * @category services
  */
-export class Config extends Context.Tag(
-  "@effect/ai-openrouter/OpenRouterLanguageModel/Config"
-)<Config, Config.Service>() {
-  /**
-   * @since 1.0.0
-   */
-  static readonly getOrUndefined: Effect.Effect<typeof Config.Service | undefined> = Effect.map(
-    Effect.context<never>(),
-    (context) => context.unsafeMap.get(Config.key)
-  )
-}
-
-/**
- * @since 1.0.0
- */
-export declare namespace Config {
-  /**
-   * @since 1.0.0
-   * @category Configuration
-   */
-  export interface Service extends
-    Simplify<
-      Partial<
-        Omit<
-          typeof Generated.ChatGenerationParams.Encoded,
-          "messages" | "response_format" | "tools" | "tool_choice" | "stream"
-        >
+export class Config extends ServiceMap.Service<
+  Config,
+  Simplify<
+    & Partial<
+      Omit<
+        typeof Generated.ChatGenerationParams.Encoded,
+        "messages" | "response_format" | "tools" | "tool_choice" | "stream" | "stream_options"
       >
     >
-  {}
-}
+    & {
+      /**
+       * Whether to use strict JSON schema validation for structured outputs.
+       *
+       * Only applies to models that support structured outputs. Defaults to
+       * `true` when structured outputs are supported.
+       */
+      readonly strictJsonSchema?: boolean | undefined
+    }
+  >
+>()("@effect/ai-openrouter/OpenRouterLanguageModel/Config") {}
 
 // =============================================================================
-// OpenRouter Provider Options / Metadata
+// Provider Options / Metadata
 // =============================================================================
 
 /**
  * @since 1.0.0
- * @category Provider Metadata
+ * @category models
  */
-export type OpenRouterReasoningInfo = {
-  readonly type: "reasoning"
-  readonly signature: string | undefined
-} | {
-  readonly type: "encrypted_reasoning"
-  readonly format: typeof Generated.ReasoningDetailSummary.Type["format"]
-  readonly redactedData: string
-}
+export type ReasoningDetails = Exclude<typeof Generated.AssistantMessage.Encoded["reasoning_details"], undefined>
 
 /**
  * @since 1.0.0
- * @category Provider Options
+ * @category models
  */
-declare module "@effect/ai/Prompt" {
+export type FileAnnotation = Extract<
+  NonNullable<typeof Generated.AssistantMessage.fields.annotations.Type>[number],
+  { type: "file" }
+>
+
+declare module "effect/unstable/ai/Prompt" {
   export interface SystemMessageOptions extends ProviderOptions {
     readonly openrouter?: {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+    } | null
   }
 
   export interface UserMessageOptions extends ProviderOptions {
@@ -100,8 +97,8 @@ declare module "@effect/ai/Prompt" {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+    } | null
   }
 
   export interface AssistantMessageOptions extends ProviderOptions {
@@ -109,8 +106,12 @@ declare module "@effect/ai/Prompt" {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+      /**
+       * Reasoning details associated with the assistant message.
+       */
+      readonly reasoningDetails?: ReasoningDetails | null
+    } | null
   }
 
   export interface ToolMessageOptions extends ProviderOptions {
@@ -118,8 +119,8 @@ declare module "@effect/ai/Prompt" {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+    } | null
   }
 
   export interface TextPartOptions extends ProviderOptions {
@@ -127,8 +128,8 @@ declare module "@effect/ai/Prompt" {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+    } | null
   }
 
   export interface ReasoningPartOptions extends ProviderOptions {
@@ -136,8 +137,12 @@ declare module "@effect/ai/Prompt" {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+      /**
+       * Reasoning details associated with the reasoning part.
+       */
+      readonly reasoningDetails?: ReasoningDetails | null
+    } | null
   }
 
   export interface FilePartOptions extends ProviderOptions {
@@ -146,12 +151,21 @@ declare module "@effect/ai/Prompt" {
        * The name to give to the file. Will be prioritized over the file name
        * associated with the file part, if present.
        */
-      readonly fileName?: string | undefined
+      readonly fileName?: string | null
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+    } | null
+  }
+
+  export interface ToolCallPartOptions extends ProviderOptions {
+    readonly openrouter?: {
+      /**
+       * Reasoning details associated with the tool call part.
+       */
+      readonly reasoningDetails?: ReasoningDetails | null
+    } | null
   }
 
   export interface ToolResultPartOptions extends ProviderOptions {
@@ -159,120 +173,100 @@ declare module "@effect/ai/Prompt" {
       /**
        * A breakpoint which marks the end of reusable content eligible for caching.
        */
-      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | undefined
-    } | undefined
+      readonly cacheControl?: typeof Generated.ChatMessageContentItemCacheControl.Encoded | null
+    } | null
   }
 }
 
-/**
- * @since 1.0.0
- * @category Provider Metadata
- */
-declare module "@effect/ai/Response" {
+declare module "effect/unstable/ai/Response" {
   export interface ReasoningPartMetadata extends ProviderMetadata {
-    readonly openrouter?: OpenRouterReasoningInfo | undefined
+    readonly openrouter?: {
+      readonly reasoningDetails?: ReasoningDetails | null
+    } | null
   }
 
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
-    readonly openrouter?: OpenRouterReasoningInfo | undefined
+    readonly openrouter?: {
+      readonly reasoningDetails?: ReasoningDetails | null
+    } | null
   }
 
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
-    readonly openrouter?: OpenRouterReasoningInfo | undefined
+    readonly openrouter?: {
+      readonly reasoningDetails?: ReasoningDetails | null
+    } | null
+  }
+
+  export interface ToolCallPartMetadata extends ProviderMetadata {
+    readonly openrouter?: {
+      readonly reasoningDetails?: ReasoningDetails | null
+    } | null
   }
 
   export interface UrlSourcePartMetadata extends ProviderMetadata {
     readonly openrouter?: {
-      readonly content?: string | undefined
-    } | undefined
+      readonly content?: string | null
+      readonly startIndex?: number | null
+      readonly endIndex?: number | null
+    } | null
   }
 
   export interface FinishPartMetadata extends ProviderMetadata {
     readonly openrouter?: {
-      /**
-       * The provider used to generate the response.
-       */
-      readonly provider?: string | undefined
-      /**
-       * Additional usage information.
-       */
-      readonly usage?: {
-        /**
-         * The total cost of generating the response.
-         */
-        readonly cost?: number | undefined
-        /**
-         * Additional details about cost.
-         */
-        readonly costDetails?: {
-          readonly upstream_inference_cost?: number | undefined
-        } | undefined
-        /**
-         * Additional details about prompt token usage.
-         */
-        readonly promptTokensDetails?: {
-          readonly audio_tokens?: number | undefined
-          readonly cached_tokens?: number | undefined
-        }
-        /**
-         * Additional details about completion token usage.
-         */
-        readonly completionTokensDetails?: {
-          readonly reasoning_tokens?: number | undefined
-          readonly audio_tokens?: number | undefined
-          readonly accepted_prediction_tokens?: number | undefined
-          readonly rejected_prediction_tokens?: number | undefined
-        } | undefined
-      } | undefined
-    } | undefined
+      readonly systemFingerprint?: string | null
+      readonly usage?: typeof Generated.ChatGenerationTokenUsage.Encoded | null
+      readonly annotations?: ReadonlyArray<FileAnnotation> | null
+      readonly provider?: string | null
+    } | null
   }
 }
 
 // =============================================================================
-// OpenRouter Language Model
+// Language Model
 // =============================================================================
 
 /**
  * @since 1.0.0
- * @category Ai Models
+ * @category constructors
  */
 export const model = (
   model: string,
-  config?: Omit<Config.Service, "model">
-): AiModel.Model<"openrouter", LanguageModel.LanguageModel, OpenRouterClient> =>
-  AiModel.make("openrouter", layer({ model, config }))
+  config?: Omit<typeof Config.Service, "model">
+): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenRouterClient> =>
+  AiModel.make("openai", layer({ model, config }))
 
 /**
+ * Creates an OpenRouter language model service.
+ *
  * @since 1.0.0
- * @category Constructors
+ * @category constructors
  */
-export const make = Effect.fnUntraced(function*(options: {
+export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: string
-  readonly config?: Omit<Config.Service, "model">
-}) {
+  readonly config?: Omit<typeof Config.Service, "model"> | undefined
+}): Effect.fn.Return<LanguageModel.Service, never, OpenRouterClient> {
   const client = yield* OpenRouterClient
+  const codecTransformer = getCodecTransformer(model)
+
+  const makeConfig = Effect.gen(function*() {
+    const services = yield* Effect.services<never>()
+    return { model, ...providerConfig, ...services.mapUnsafe.get(Config.key) }
+  })
 
   const makeRequest = Effect.fnUntraced(
-    function*(providerOptions: LanguageModel.ProviderOptions) {
-      const context = yield* Effect.context<never>()
-      const config = { model: options.model, ...options.config, ...context.unsafeMap.get(Config.key) }
-      const messages = yield* prepareMessages(providerOptions)
-      const { toolChoice, tools } = yield* prepareTools(providerOptions)
-      const responseFormat = providerOptions.responseFormat
+    function*({ config, options }: {
+      readonly config: typeof Config.Service
+      readonly options: LanguageModel.ProviderOptions
+    }): Effect.fn.Return<typeof Generated.ChatGenerationParams.Encoded, AiError.AiError> {
+      const messages = yield* prepareMessages({ options })
+      const { tools, toolChoice } = yield* prepareTools({ options, transformer: codecTransformer })
+      const responseFormat = yield* getResponseFormat({ config, options, transformer: codecTransformer })
       const request: typeof Generated.ChatGenerationParams.Encoded = {
         ...config,
         messages,
-        tools,
-        tool_choice: toolChoice,
-        response_format: responseFormat.type === "text" ? undefined : {
-          type: "json_schema",
-          json_schema: {
-            name: responseFormat.objectName,
-            description: Tool.getDescriptionFromSchemaAst(responseFormat.schema.ast) ?? "Respond with a JSON object",
-            schema: Tool.getJsonSchemaFromSchemaAst(responseFormat.schema.ast),
-            strict: true
-          }
-        }
+        ...(Predicate.isNotUndefined(responseFormat) ? { response_format: responseFormat } : undefined),
+        ...(Predicate.isNotUndefined(tools) ? { tools } : undefined),
+        ...(Predicate.isNotUndefined(toolChoice) ? { tool_choice: toolChoice } : undefined)
       }
       return request
     }
@@ -281,22 +275,24 @@ export const make = Effect.fnUntraced(function*(options: {
   return yield* LanguageModel.make({
     generateText: Effect.fnUntraced(
       function*(options) {
-        const request = yield* makeRequest(options)
+        const config = yield* makeConfig
+        const request = yield* makeRequest({ config, options })
         annotateRequest(options.span, request)
-        const rawResponse = yield* client.createChatCompletion(request)
+        const [rawResponse, response] = yield* client.createChatCompletion(request)
         annotateResponse(options.span, rawResponse)
-        return yield* makeResponse(rawResponse)
+        return yield* makeResponse({ rawResponse, response })
       }
     ),
     streamText: Effect.fnUntraced(
       function*(options) {
-        const request = yield* makeRequest(options)
+        const config = yield* makeConfig
+        const request = yield* makeRequest({ config, options })
         annotateRequest(options.span, request)
-        return client.createChatCompletionStream(request)
+        const [response, stream] = yield* client.createChatCompletionStream(request)
+        return yield* makeStreamResponse({ response, stream })
       },
       (effect, options) =>
         effect.pipe(
-          Effect.flatMap((stream) => makeStreamResponse(stream)),
           Stream.unwrap,
           Stream.map((response) => {
             annotateStreamResponse(options.span, response)
@@ -304,384 +300,473 @@ export const make = Effect.fnUntraced(function*(options: {
           })
         )
     )
-  })
+  }).pipe(Effect.provideService(
+    LanguageModel.CurrentCodecTransformer,
+    codecTransformer
+  ))
 })
 
 /**
+ * Creates a layer for the OpenRouter language model.
+ *
  * @since 1.0.0
- * @category Layers
+ * @category layers
  */
 export const layer = (options: {
   readonly model: string
-  readonly config?: Omit<Config.Service, "model">
+  readonly config?: Omit<typeof Config.Service, "model"> | undefined
 }): Layer.Layer<LanguageModel.LanguageModel, never, OpenRouterClient> =>
-  Layer.effect(LanguageModel.LanguageModel, make({ model: options.model, config: options.config }))
+  Layer.effect(LanguageModel.LanguageModel, make(options))
 
 /**
+ * Provides config overrides for OpenRouter language model operations.
+ *
  * @since 1.0.0
- * @category Configuration
+ * @category configuration
  */
 export const withConfigOverride: {
   /**
+   * Provides config overrides for OpenRouter language model operations.
+   *
    * @since 1.0.0
-   * @category Configuration
+   * @category configuration
    */
-  (config: Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  (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
-   * @category Configuration
+   * @category configuration
    */
-  <A, E, R>(self: Effect.Effect<A, E, R>, config: Config.Service): Effect.Effect<A, E, R>
+  <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
-   * @category Configuration
+   * @category configuration
    */
-  (config: Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>,
+  (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
-   * @category Configuration
+   * @category configuration
    */
-  <A, E, R>(self: Effect.Effect<A, E, R>, config: Config.Service) => Effect.Effect<A, E, R>
+  <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
 >(2, (self, overrides) =>
   Effect.flatMap(
-    Config.getOrUndefined,
-    (config) => Effect.provideService(self, Config, { ...config, ...overrides })
+    Effect.serviceOption(Config),
+    (config) =>
+      Effect.provideService(self, Config, {
+        ...(config._tag === "Some" ? config.value : {}),
+        ...overrides
+      })
   ))
 
 // =============================================================================
 // Prompt Conversion
 // =============================================================================
 
-const prepareMessages: (options: LanguageModel.ProviderOptions) => Effect.Effect<
-  ReadonlyArray<typeof Generated.Message.Encoded>,
-  AiError.AiError
-> = Effect.fnUntraced(function*(options) {
-  const messages: Array<typeof Generated.Message.Encoded> = []
-
-  for (const message of options.prompt.content) {
-    switch (message.role) {
-      case "system": {
-        messages.push({
-          role: "system",
-          content: message.content,
-          cache_control: getCacheControl(message)
-        })
-        break
-      }
+const prepareMessages = Effect.fnUntraced(
+  function*({ options }: {
+    readonly options: LanguageModel.ProviderOptions
+  }): Effect.fn.Return<ReadonlyArray<typeof Generated.Message.Encoded>, AiError.AiError> {
+    const messages: Array<typeof Generated.Message.Encoded> = []
+
+    const reasoningDetailsTracker = new ReasoningDetailsDuplicateTracker()
+
+    for (const message of options.prompt.content) {
+      switch (message.role) {
+        case "system": {
+          const cache_control = getCacheControl(message)
 
-      case "user": {
-        if (message.content.length === 1 && message.content[0].type === "text") {
-          const part = message.content[0]
-          const cacheControl = getCacheControl(message) ?? getCacheControl(part)
           messages.push({
-            role: "user",
-            content: Predicate.isNotUndefined(cacheControl)
-              ? [{ type: "text", text: part.text, cache_control: cacheControl }]
-              : part.text
+            role: "system",
+            content: [{
+              type: "text",
+              text: message.content,
+              ...(Predicate.isNotNull(cache_control) ? { cache_control } : undefined)
+            }]
           })
-        } else {
+
+          break
+        }
+
+        case "user": {
           const content: Array<typeof Generated.ChatMessageContentItem.Encoded> = []
+
+          // Get the message-level cache control
           const messageCacheControl = getCacheControl(message)
-          for (const part of message.content) {
+
+          if (message.content.length === 1 && message.content[0].type === "text") {
+            messages.push({
+              role: "user",
+              content: Predicate.isNotNull(messageCacheControl)
+                ? [{ type: "text", text: message.content[0].text, cache_control: messageCacheControl }]
+                : message.content[0].text
+            })
+
+            break
+          }
+
+          // Find the index of the last text part in the message content
+          let lastTextPartIndex = -1
+          for (let i = message.content.length - 1; i >= 0; i--) {
+            if (message.content[i].type === "text") {
+              lastTextPartIndex = i
+              break
+            }
+          }
+
+          for (let index = 0; index < message.content.length; index++) {
+            const part = message.content[index]
+            const isLastTextPart = part.type === "text" && index === lastTextPartIndex
             const partCacheControl = getCacheControl(part)
-            const cacheControl = partCacheControl ?? messageCacheControl
+
             switch (part.type) {
               case "text": {
+                const cache_control = Predicate.isNotNull(partCacheControl)
+                  ? partCacheControl
+                  : isLastTextPart
+                  ? messageCacheControl
+                  : null
+
                 content.push({
                   type: "text",
                   text: part.text,
-                  cache_control: cacheControl
+                  ...(Predicate.isNotNull(cache_control) ? { cache_control } : undefined)
                 })
+
                 break
               }
+
               case "file": {
                 if (part.mediaType.startsWith("image/")) {
                   const mediaType = part.mediaType === "image/*" ? "image/jpeg" : part.mediaType
+
                   content.push({
                     type: "image_url",
                     image_url: {
                       url: part.data instanceof URL
                         ? part.data.toString()
                         : part.data instanceof Uint8Array
-                        ? `data:${mediaType};base64,${Encoding.encodeBase64(part.data)}`
-                        : part.data
-                    },
-                    cache_control: cacheControl
-                  })
-                } else {
-                  const options = part.options.openrouter
-                  const fileName = options?.fileName ?? part.fileName ?? ""
-                  content.push({
-                    type: "file",
-                    file: {
-                      filename: fileName,
-                      file_data: part.data instanceof URL
-                        ? part.data.toString()
-                        : part.data instanceof Uint8Array
-                        ? `data:${part.mediaType};base64,${Encoding.encodeBase64(part.data)}`
+                        ? `data:${mediaType};base64,${Base64.encode(part.data)}`
                         : part.data
                     },
-                    cache_control: part.data instanceof URL ? cacheControl : undefined
+                    ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
                   })
+
+                  break
                 }
+
+                const options = part.options.openrouter
+                const fileName = options?.fileName ?? part.fileName ?? ""
+
+                content.push({
+                  type: "file",
+                  file: {
+                    filename: fileName,
+                    file_data: part.data instanceof URL
+                      ? part.data.toString()
+                      : part.data instanceof Uint8Array
+                      ? `data:${part.mediaType};base64,${Base64.encode(part.data)}`
+                      : part.data
+                  },
+                  ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
+                } as any)
+
                 break
               }
             }
           }
-          messages.push({
-            role: "user",
-            content
-          })
+
+          messages.push({ role: "user", content })
+
+          break
         }
-        break
-      }
 
-      case "assistant": {
-        let text = ""
-        let reasoning = ""
-        const reasoningDetails: Array<typeof Generated.ReasoningDetail.Encoded> = []
-        const toolCalls: Array<typeof Generated.ChatMessageToolCall.Encoded> = []
-        const cacheControl = getCacheControl(message)
-        for (const part of message.content) {
-          switch (part.type) {
-            case "text": {
-              text += part.text
-              break
+        case "assistant": {
+          let text = ""
+          let reasoning = ""
+          const toolCalls: Array<typeof Generated.ChatMessageToolCall.Encoded> = []
+
+          for (const part of message.content) {
+            switch (part.type) {
+              case "text": {
+                text += part.text
+                break
+              }
+
+              case "reasoning": {
+                reasoning += part.text
+                break
+              }
+
+              case "tool-call": {
+                toolCalls.push({
+                  type: "function",
+                  id: part.id,
+                  function: { name: part.name, arguments: JSON.stringify(part.params) }
+                })
+                break
+              }
+
+              default: {
+                break
+              }
             }
-            case "reasoning": {
-              reasoning += part.text
-              reasoningDetails.push({
-                type: "reasoning.text",
-                text: part.text
-              })
-              break
+          }
+
+          const messageReasoningDetails = message.options.openrouter?.reasoningDetails
+
+          // Use message-level reasoning details if available, otherwise find from parts
+          // Priority: message-level > first tool call > first reasoning part
+          // This prevents duplicate thinking blocks when Claude makes parallel tool calls
+          const candidateReasoningDetails: ReasoningDetails | null = Predicate.isNotNullish(messageReasoningDetails)
+              && Array.isArray(messageReasoningDetails)
+              && messageReasoningDetails.length > 0
+            ? messageReasoningDetails
+            : findFirstReasoningDetails(message.content)
+
+          // Deduplicate reasoning details across all messages to prevent "Duplicate
+          // item found with id" errors in multi-turn conversations.
+          let reasoningDetails: ReasoningDetails | null = null
+          if (Predicate.isNotNull(candidateReasoningDetails) && candidateReasoningDetails.length > 0) {
+            const uniqueReasoningDetails: Mutable<ReasoningDetails> = []
+            for (const detail of candidateReasoningDetails) {
+              if (reasoningDetailsTracker.upsert(detail)) {
+                uniqueReasoningDetails.push(detail)
+              }
             }
-            case "tool-call": {
-              toolCalls.push({
-                id: part.id,
-                type: "function",
-                function: {
-                  name: part.name,
-                  arguments: JSON.stringify(part.params)
-                }
-              })
-              break
+            if (uniqueReasoningDetails.length > 0) {
+              reasoningDetails = uniqueReasoningDetails
             }
           }
-        }
-        messages.push({
-          role: "assistant",
-          content: text,
-          tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
-          reasoning: reasoning.length > 0 ? reasoning : undefined,
-          reasoning_details: reasoningDetails.length > 0 ? reasoningDetails : undefined,
-          cache_control: cacheControl
-        })
-        break
-      }
 
-      case "tool": {
-        const cacheControl = getCacheControl(message)
-        for (const part of message.content) {
           messages.push({
-            role: "tool",
-            tool_call_id: part.id,
-            content: JSON.stringify(part.result),
-            cache_control: cacheControl
+            role: "assistant",
+            content: text,
+            reasoning: reasoning.length > 0 ? reasoning : null,
+            ...(Predicate.isNotNull(reasoningDetails) ? { reasoning_details: reasoningDetails } : undefined),
+            ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : undefined)
           })
-        }
-        break
-      }
-    }
-  }
-
-  return messages
-})
 
-// =============================================================================
-// Tool Conversion
-// =============================================================================
-
-const prepareTools: (options: LanguageModel.ProviderOptions) => Effect.Effect<{
-  readonly tools: ReadonlyArray<typeof Generated.ToolDefinitionJson.Encoded> | undefined
-  readonly toolChoice: typeof Generated.ToolChoiceOption.Encoded | undefined
-}, AiError.AiError> = Effect.fnUntraced(
-  function*(options: LanguageModel.ProviderOptions) {
-    if (options.tools.length === 0) {
-      return { tools: undefined, toolChoice: undefined }
-    }
+          break
+        }
 
-    const hasProviderDefinedTools = options.tools.some((tool) => Tool.isProviderDefined(tool))
-    if (hasProviderDefinedTools) {
-      return yield* new AiError.MalformedInput({
-        module: "OpenRouterLanguageModel",
-        method: "prepareTools",
-        description: "Provider-defined tools are unsupported by the OpenRouter " +
-          "provider integration at this time"
-      })
-    }
+        case "tool": {
+          for (const part of message.content) {
+            // Skip tool approval parts
+            if (part.type === "tool-approval-response") {
+              continue
+            }
 
-    let tools: Array<typeof Generated.ToolDefinitionJson.Encoded> = []
-    let toolChoice: typeof Generated.ToolChoiceOption.Encoded | undefined = undefined
+            messages.push({
+              role: "tool",
+              tool_call_id: part.id,
+              content: JSON.stringify(part.result)
+            })
+          }
 
-    for (const tool of options.tools) {
-      tools.push({
-        type: "function",
-        function: {
-          name: tool.name,
-          description: Tool.getDescription(tool as any),
-          parameters: Tool.getJsonSchema(tool as any) as any,
-          strict: true
+          break
         }
-      })
-    }
-
-    if (options.toolChoice === "none") {
-      toolChoice = "none"
-    } else if (options.toolChoice === "auto") {
-      toolChoice = "auto"
-    } else if (options.toolChoice === "required") {
-      toolChoice = "required"
-    } else if ("tool" in options.toolChoice) {
-      toolChoice = { type: "function", function: { name: options.toolChoice.tool } }
-    } else {
-      const allowedTools = new Set(options.toolChoice.oneOf)
-      tools = tools.filter((tool) => allowedTools.has(tool.function.name))
-      toolChoice = options.toolChoice.mode === "auto" ? "auto" : "required"
+      }
     }
 
-    return { tools, toolChoice }
+    return messages
   }
 )
 
 // =============================================================================
-// Response Conversion
+// HTTP Details
 // =============================================================================
 
-const makeResponse: (response: Generated.ChatResponse) => Effect.Effect<
-  Array<Response.PartEncoded>,
-  AiError.AiError
-> = Effect.fnUntraced(
-  function*(response) {
-    const choice = response.choices[0]
+const buildHttpRequestDetails = (
+  request: HttpClientRequest.HttpClientRequest
+): typeof Response.HttpRequestDetails.Type => ({
+  method: request.method,
+  url: request.url,
+  urlParams: Array.from(request.urlParams),
+  hash: request.hash,
+  headers: Redactable.redact(request.headers) as Record<string, string>
+})
 
-    if (Predicate.isUndefined(choice)) {
-      return yield* new AiError.MalformedOutput({
-        module: "OpenRouterLanguageModel",
-        method: "makeResponse",
-        description: "Received response with no valid choices"
-      })
-    }
+const buildHttpResponseDetails = (
+  response: HttpClientResponse.HttpClientResponse
+): typeof Response.HttpResponseDetails.Type => ({
+  status: response.status,
+  headers: Redactable.redact(response.headers) as Record<string, string>
+})
+
+// =============================================================================
+// Response Conversion
+// =============================================================================
+
+const makeResponse = Effect.fnUntraced(
+  function*({ rawResponse, response }: {
+    readonly rawResponse: Generated.SendChatCompletionRequest200
+    readonly response: HttpClientResponse.HttpClientResponse
+  }): Effect.fn.Return<Array<Response.PartEncoded>, AiError.AiError, IdGenerator.IdGenerator> {
+    const idGenerator = yield* IdGenerator.IdGenerator
 
     const parts: Array<Response.PartEncoded> = []
-    const message = choice.message
+    let hasToolCalls = false
+    let hasEncryptedReasoning = false
 
-    const createdAt = new Date(response.created * 1000)
+    const createdAt = new Date(rawResponse.created * 1000)
     parts.push({
       type: "response-metadata",
-      id: response.id,
-      modelId: response.model,
-      timestamp: DateTime.formatIso(DateTime.unsafeFromDate(createdAt))
+      id: rawResponse.id,
+      modelId: rawResponse.model,
+      timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(createdAt)),
+      request: buildHttpRequestDetails(response.request)
     })
 
-    if (Predicate.isNotNullable(message.reasoning) && message.reasoning.length > 0) {
-      parts.push({
-        type: "reasoning",
-        text: message.reasoning
+    const choice = rawResponse.choices[0]
+    if (Predicate.isUndefined(choice)) {
+      return yield* AiError.make({
+        module: "OpenRouterLanguageModel",
+        method: "makeResponse",
+        reason: new AiError.InvalidOutputError({
+          description: "Received response with empty choices"
+        })
       })
     }
 
-    if (Predicate.isNotNullable(message.reasoning_details) && message.reasoning_details.length > 0) {
-      for (const detail of message.reasoning_details) {
+    const message = choice.message
+    let finishReason = choice.finish_reason
+
+    const reasoningDetails = message.reasoning_details
+    if (Predicate.isNotNullish(reasoningDetails) && reasoningDetails.length > 0) {
+      for (const detail of reasoningDetails) {
         switch (detail.type) {
-          case "reasoning.summary": {
-            if (Predicate.isNotUndefined(detail.summary) && detail.summary.length > 0) {
+          case "reasoning.text": {
+            if (Predicate.isNotNullish(detail.text) && detail.text.length > 0) {
               parts.push({
                 type: "reasoning",
-                text: detail.summary
+                text: detail.text,
+                metadata: { openrouter: { reasoningDetails: [detail] } }
               })
             }
             break
           }
-          case "reasoning.encrypted": {
-            if (Predicate.isNotUndefined(detail.data) && detail.data.length > 0) {
+          case "reasoning.summary": {
+            if (detail.summary.length > 0) {
               parts.push({
                 type: "reasoning",
-                text: "",
-                metadata: {
-                  openrouter: {
-                    type: "encrypted_reasoning",
-                    format: detail.format,
-                    redactedData: detail.data
-                  }
-                }
+                text: detail.summary,
+                metadata: { openrouter: { reasoningDetails: [detail] } }
               })
             }
             break
           }
-          case "reasoning.text": {
-            if (Predicate.isNotUndefined(detail.text) && detail.text.length > 0) {
+          case "reasoning.encrypted": {
+            if (detail.data.length > 0) {
+              hasEncryptedReasoning = true
               parts.push({
                 type: "reasoning",
-                text: detail.text,
-                metadata: {
-                  openrouter: {
-                    type: "reasoning",
-                    signature: detail.signature
-                  }
-                }
+                text: "[REDACTED]",
+                metadata: { openrouter: { reasoningDetails: [detail] } }
               })
             }
             break
           }
         }
       }
-    }
-
-    if (Predicate.isNotNullable(message.content) && message.content.length > 0) {
+    } else if (Predicate.isNotNullish(message.reasoning) && message.reasoning.length > 0) {
+      // message.reasoning fallback only when reasoning_details absent/empty
       parts.push({
-        type: "text",
-        text: message.content as string
+        type: "reasoning",
+        text: message.reasoning
       })
     }
 
-    if (Predicate.isNotNullable(message.tool_calls)) {
-      for (const toolCall of message.tool_calls) {
+    const content = message.content
+    if (Predicate.isNotNullish(content)) {
+      if (typeof content === "string") {
+        if (content.length > 0) {
+          parts.push({ type: "text", text: content })
+        }
+      } else {
+        for (const item of content) {
+          if (item.type === "text") {
+            parts.push({ type: "text", text: item.text })
+          }
+        }
+      }
+    }
+
+    const toolCalls = message.tool_calls
+    if (Predicate.isNotNullish(toolCalls) && toolCalls.length > 0) {
+      hasToolCalls = true
+      for (let index = 0; index < toolCalls.length; index++) {
+        const toolCall = toolCalls[index]
         const toolName = toolCall.function.name
-        const toolParams = toolCall.function.arguments
+        const toolParams = toolCall.function.arguments ?? "{}"
         const params = yield* Effect.try({
           try: () => Tool.unsafeSecureJsonParse(toolParams),
           catch: (cause) =>
-            new AiError.MalformedOutput({
+            AiError.make({
               module: "OpenRouterLanguageModel",
               method: "makeResponse",
-              description: "Failed to securely parse tool call parameters " +
-                `for tool '${toolName}':\nParameters: ${toolParams}`,
-              cause
+              reason: new AiError.ToolParameterValidationError({
+                toolName,
+                toolParams: {},
+                description: `Failed to securely JSON parse tool parameters: ${cause}`
+              })
             })
         })
         parts.push({
           type: "tool-call",
           id: toolCall.id,
           name: toolName,
-          params
+          params,
+          // Only attach reasoning_details to the first tool call to avoid
+          // duplicating thinking blocks for parallel tool calls (Claude)
+          ...(index === 0 && Predicate.isNotNullish(reasoningDetails) && reasoningDetails.length > 0
+            ? { metadata: { openrouter: { reasoningDetails } } }
+            : undefined)
         })
       }
     }
 
-    if (Predicate.isNotNullable(message.annotations)) {
-      for (const annotation of message.annotations) {
+    const images = message.images
+    if (Predicate.isNotNullish(images)) {
+      for (const image of images) {
+        const url = image.image_url.url
+        if (url.startsWith("data:")) {
+          const mediaType = getMediaType(url, "image/jpeg")
+          const data = getBase64FromDataUrl(url)
+          parts.push({ type: "file", mediaType, data })
+        } else {
+          const id = yield* idGenerator.generateId()
+          parts.push({ type: "source", sourceType: "url", id, url, title: "" })
+        }
+      }
+    }
+
+    const annotations = choice.message.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,
+            title: annotation.url_citation.title ?? "",
             metadata: {
               openrouter: {
-                content: annotation.url_citation.content
+                ...(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)
+                  ? { endIndex: annotation.url_citation.end_index }
+                  : undefined)
               }
             }
           })
@@ -689,35 +774,33 @@ const makeResponse: (response: Generated.ChatResponse) => Effect.Effect<
       }
     }
 
-    if (Predicate.isNotNullable(message.images)) {
-      for (const image of message.images) {
-        parts.push({
-          type: "file",
-          mediaType: getMediaType(image.image_url.url) ?? "image/jpeg",
-          data: getBase64FromDataUrl(image.image_url.url)
-        })
-      }
+    // Extract file annotations to expose in provider metadata
+    const fileAnnotations = annotations?.filter((annotation) => {
+      return annotation.type === "file"
+    })
+
+    // Fix for Gemini 3 thoughtSignature: when there are tool calls with encrypted
+    // reasoning (thoughtSignature), the model returns 'stop' but expects continuation.
+    // Override to 'tool-calls' so the SDK knows to continue the conversation.
+    if (hasEncryptedReasoning && hasToolCalls && finishReason === "stop") {
+      finishReason = "tool_calls"
     }
 
     parts.push({
       type: "finish",
-      reason: InternalUtilities.resolveFinishReason(choice.finish_reason),
-      usage: {
-        inputTokens: response.usage?.prompt_tokens,
-        outputTokens: response.usage?.completion_tokens,
-        totalTokens: response.usage?.total_tokens,
-        reasoningTokens: response.usage?.completion_tokens_details?.reasoning_tokens,
-        cachedInputTokens: response.usage?.prompt_tokens_details?.cached_tokens
-      },
+      reason: resolveFinishReason(finishReason),
+      usage: getUsage(rawResponse.usage),
+      response: buildHttpResponseDetails(response),
       metadata: {
         openrouter: {
-          provider: response.provider,
-          usage: {
-            cost: response.usage?.cost,
-            promptTokensDetails: response.usage?.prompt_tokens_details,
-            completionTokensDetails: response.usage?.completion_tokens_details,
-            costDetails: response.usage?.cost_details
-          }
+          systemFingerprint: rawResponse.system_fingerprint ?? null,
+          usage: rawResponse.usage ?? null,
+          ...(Predicate.isNotUndefined(fileAnnotations) && fileAnnotations.length > 0
+            ? { annotations: fileAnnotations }
+            : undefined),
+          ...(Predicate.hasProperty(rawResponse, "provider") && Predicate.isString(rawResponse.provider)
+            ? { provider: rawResponse.provider }
+            : undefined)
         }
       }
     })
@@ -726,193 +809,290 @@ const makeResponse: (response: Generated.ChatResponse) => Effect.Effect<
   }
 )
 
-const makeStreamResponse: (stream: Stream.Stream<ChatStreamingResponseChunk, AiError.AiError>) => Effect.Effect<
-  Stream.Stream<Response.StreamPartEncoded, AiError.AiError>
-> = Effect.fnUntraced(
-  function*(stream) {
-    let idCounter = 0
-    let activeTextId: string | undefined = undefined
-    let activeReasoningId: string | undefined = undefined
-    let finishReason: Response.FinishReason = "unknown"
+const makeStreamResponse = Effect.fnUntraced(
+  function*({ response, stream }: {
+    readonly response: HttpClientResponse.HttpClientResponse
+    readonly stream: Stream.Stream<ChatStreamingResponseChunkData, AiError.AiError>
+  }): Effect.fn.Return<
+    Stream.Stream<Response.StreamPartEncoded, AiError.AiError>,
+    AiError.AiError,
+    IdGenerator.IdGenerator
+  > {
+    const idGenerator = yield* IdGenerator.IdGenerator
+
+    let textStarted = false
+    let reasoningStarted = false
     let responseMetadataEmitted = false
+    let reasoningDetailsAttachedToToolCall = false
+    let finishReason: Response.FinishReason = "other"
+    let openRouterResponseId: string | undefined = undefined
+    let activeReasoningId: string | undefined = undefined
+    let activeTextId: string | undefined = undefined
 
-    const activeToolCalls: Record<number, {
-      readonly index: number
+    let totalToolCalls = 0
+    const activeToolCalls: Array<{
       readonly id: string
+      readonly type: "function"
       readonly name: string
       params: string
-    }> = {}
+    }> = []
+
+    // Track reasoning details to preserve for multi-turn conversations
+    const accumulatedReasoningDetails: DeepMutable<ReasoningDetails> = []
+
+    // Track file annotations to expose in provider metadata
+    const accumulatedFileAnnotations: Array<FileAnnotation> = []
+
+    const usage: DeepMutable<Response.Usage> = {
+      inputTokens: {
+        total: undefined,
+        uncached: undefined,
+        cacheRead: undefined,
+        cacheWrite: undefined
+      },
+      outputTokens: {
+        total: undefined,
+        text: undefined,
+        reasoning: undefined
+      }
+    }
 
     return stream.pipe(
       Stream.mapEffect(Effect.fnUntraced(function*(event) {
         const parts: Array<Response.StreamPartEncoded> = []
 
-        if ("error" in event) {
-          parts.push({
-            type: "error",
-            error: event.error
-          })
-          return parts
+        if (Predicate.isNotUndefined(event.error)) {
+          finishReason = "error"
+          parts.push({ type: "error", error: event.error })
         }
 
-        // Response Metadata
-
         if (Predicate.isNotUndefined(event.id) && !responseMetadataEmitted) {
+          const timestamp = yield* DateTime.now
           parts.push({
             type: "response-metadata",
             id: event.id,
             modelId: event.model,
-            timestamp: DateTime.formatIso(yield* DateTime.now)
+            timestamp: DateTime.formatIso(timestamp),
+            request: buildHttpRequestDetails(response.request)
           })
           responseMetadataEmitted = true
         }
 
-        const choice = event.choices[0]
+        if (Predicate.isNotUndefined(event.usage)) {
+          const computed = getUsage(event.usage)
+          usage.inputTokens = computed.inputTokens
+          usage.outputTokens = computed.outputTokens
+        }
 
+        const choice = event.choices[0]
         if (Predicate.isUndefined(choice)) {
-          return yield* new AiError.MalformedOutput({
+          return yield* AiError.make({
             module: "OpenRouterLanguageModel",
-            method: "makeResponse",
-            description: "Received response with no valid choices"
+            method: "makeStreamResponse",
+            reason: new AiError.InvalidOutputError({
+              description: "Received response with empty choices"
+            })
           })
         }
 
-        const delta = choice.delta
+        if (Predicate.isNotNull(choice.finish_reason)) {
+          finishReason = resolveFinishReason(choice.finish_reason)
+        }
 
-        if (Predicate.isUndefined(delta)) {
+        const delta = choice.delta
+        if (Predicate.isNullish(delta)) {
           return parts
         }
 
-        // Reasoning Parts
-
-        const emitReasoningPart = (delta: string, metadata: OpenRouterReasoningInfo | undefined = undefined) => {
-          // End in-progress text part if present before starting reasoning
-          if (Predicate.isNotUndefined(activeTextId)) {
+        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: "text-end",
-              id: activeTextId
+              type: "reasoning-delta",
+              id: activeReasoningId!,
+              delta,
+              metadata
             })
-            activeTextId = undefined
           }
-          // Start a new reasoning part if necessary
-          if (Predicate.isUndefined(activeReasoningId)) {
-            activeReasoningId = (idCounter++).toString()
-            parts.push({
-              type: "reasoning-start",
-              id: activeReasoningId,
-              metadata: { openrouter: 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
+              } else {
+                // Start a new text detail
+                accumulatedReasoningDetails.push({ ...detail })
+              }
+            } else {
+              // Non-text details (encrypted, summary) are pushed as-is
+              accumulatedReasoningDetails.push(detail)
+            }
           }
-          // Emit the reasoning delta
-          parts.push({
-            type: "reasoning-delta",
-            id: activeReasoningId,
-            delta,
-            metadata: { openrouter: metadata }
-          })
-        }
 
-        if (Predicate.isNotNullable(delta.reasoning_details) && delta.reasoning_details.length > 0) {
-          for (const detail of delta.reasoning_details) {
+          // 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.summary": {
-                if (Predicate.isNotUndefined(detail.summary) && detail.summary.length > 0) {
-                  emitReasoningPart(detail.summary)
+              case "reasoning.text": {
+                if (Predicate.isNotNullish(detail.text)) {
+                  yield* emitReasoning(detail.text, metadata)
                 }
                 break
               }
-              case "reasoning.encrypted": {
-                if (Predicate.isNotUndefined(detail.data) && detail.data.length > 0) {
-                  emitReasoningPart("", {
-                    type: "encrypted_reasoning",
-                    format: detail.format,
-                    redactedData: detail.data
-                  })
+
+              case "reasoning.summary": {
+                if (Predicate.isNotNullish(detail.summary)) {
+                  yield* emitReasoning(detail.summary, metadata)
                 }
                 break
               }
-              case "reasoning.text": {
-                if (Predicate.isNotUndefined(detail.text) && detail.text.length > 0) {
-                  emitReasoningPart(detail.text, {
-                    type: "reasoning",
-                    signature: detail.signature
-                  })
+
+              case "reasoning.encrypted": {
+                if (Predicate.isNotNullish(detail.data)) {
+                  yield* emitReasoning("[REDACTED]", metadata)
                 }
                 break
               }
             }
           }
-        } else if (Predicate.isNotNullable(delta.reasoning) && delta.reasoning.length > 0) {
-          emitReasoningPart(delta.reasoning)
+        } else if (Predicate.isNotNullish(delta.reasoning)) {
+          yield* emitReasoning(delta.reasoning)
         }
 
-        // Text Parts
-
-        if (Predicate.isNotNullable(delta.content) && delta.content.length > 0) {
-          // End in-progress reasoning part if present before starting text
-          if (Predicate.isNotUndefined(activeReasoningId)) {
+        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
+              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
             })
-            activeReasoningId = undefined
+            reasoningStarted = false
           }
-          // Start a new text part if necessary
-          if (Predicate.isUndefined(activeTextId)) {
-            activeTextId = (idCounter++).toString()
+
+          if (!textStarted) {
+            activeTextId = openRouterResponseId ?? (yield* idGenerator.generateId())
             parts.push({
               type: "text-start",
               id: activeTextId
             })
+            textStarted = true
           }
-          // Emit the text delta
+
           parts.push({
             type: "text-delta",
-            id: activeTextId,
-            delta: delta.content
+            id: activeTextId!,
+            delta: content
           })
         }
 
-        // Source Parts
-
-        if (Predicate.isNotNullable(delta.annotations)) {
-          for (const annotation of delta.annotations) {
+        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,
+                title: annotation.url_citation.title ?? "",
                 metadata: {
                   openrouter: {
-                    content: annotation.url_citation.content
+                    ...(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)
             }
           }
         }
 
-        // Tool Call Parts
-
-        if (Predicate.isNotNullable(delta.tool_calls) && delta.tool_calls.length > 0) {
-          for (const toolCall of delta.tool_calls) {
-            // Get the active tool call, if present
-            let activeToolCall = activeToolCalls[toolCall.index]
+        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]
 
-            // If no active tool call was found, start a new active tool call
+            // Tool call start - OpenRouter returns all information except the
+            // tool call parameters in the first chunk
             if (Predicate.isUndefined(activeToolCall)) {
-              // The tool call id and function name always come back with the
-              // first tool call delta
+              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.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"
+                  })
+                })
+              }
+
               activeToolCall = {
-                index: toolCall.index,
-                id: toolCall.id!,
-                name: toolCall.function.name!,
+                id: toolCall.id,
+                type: "function",
+                name: toolCall.function.name,
                 params: toolCall.function.arguments ?? ""
               }
 
-              activeToolCalls[toolCall.index] = activeToolCall
+              activeToolCalls[index] = activeToolCall
 
               parts.push({
                 type: "tool-params-start",
@@ -931,7 +1111,7 @@ const makeStreamResponse: (stream: Stream.Stream<ChatStreamingResponseChunk, AiE
             } else {
               // If an active tool call was found, update and emit the delta for
               // the tool call's parameters
-              activeToolCall.params += toolCall.function.arguments
+              activeToolCall.params += toolCall.function?.arguments ?? ""
               parts.push({
                 type: "tool-params-delta",
                 id: activeToolCall.id,
@@ -940,18 +1120,32 @@ const makeStreamResponse: (stream: Stream.Stream<ChatStreamingResponseChunk, AiE
             }
 
             // 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-call",
                 id: activeToolCall.id,
                 name: activeToolCall.name,
-                params
+                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
+
+              // 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
@@ -960,97 +1154,169 @@ const makeStreamResponse: (stream: Stream.Stream<ChatStreamingResponseChunk, AiE
           }
         }
 
-        // File Parts
-
-        if (Predicate.isNotNullable(delta.images)) {
-          for (const image of delta.images) {
+        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",
+              mediaType: getMediaType(image.image_url.url, "image/jpeg"),
               data: getBase64FromDataUrl(image.image_url.url)
             })
           }
         }
 
-        // Finish Parts
-
-        if (Predicate.isNotNullable(choice.finish_reason)) {
-          finishReason = InternalUtilities.resolveFinishReason(choice.finish_reason)
-        }
-
         // Usage is only emitted by the last part of the stream, so we need to
         // handle flushing any remaining text / reasoning / tool calls
         if (Predicate.isNotUndefined(event.usage)) {
-          // Complete any remaining tool calls if the finish reason is tool-calls
+          // Fix for Gemini 3 thoughtSignature: when there are tool calls with encrypted
+          // reasoning (thoughtSignature), the model returns 'stop' but expects continuation.
+          // Override to 'tool-calls' so the SDK knows to continue the conversation.
+          const hasEncryptedReasoning = accumulatedReasoningDetails.some(
+            (detail) => detail.type === "reasoning.encrypted" && detail.data.length > 0
+          )
+          if (totalToolCalls > 0 && hasEncryptedReasoning && finishReason === "stop") {
+            finishReason = resolveFinishReason("tool-calls")
+          }
+
+          // Forward any unsent tool calls if finish reason is 'tool-calls'
           if (finishReason === "tool-calls") {
-            for (const toolCall of Object.values(activeToolCalls)) {
+            for (const toolCall of activeToolCalls) {
               // Coerce invalid tool call parameters to an empty object
-              const params = yield* Effect.try(() => Tool.unsafeSecureJsonParse(toolCall.params)).pipe(
-                Effect.catchAll(() => Effect.succeed({}))
-              )
-              parts.push({
-                type: "tool-params-end",
-                id: toolCall.id
-              })
+              let params: unknown
+              // @effect-diagnostics-next-line tryCatchInEffectGen:off
+              try {
+                params = Tool.unsafeSecureJsonParse(toolCall.params)
+              } catch {
+                params = {}
+              }
+
+              // Only attach reasoning_details to the first tool call to avoid
+              // duplicating thinking blocks for parallel tool calls (Claude)
               parts.push({
                 type: "tool-call",
                 id: toolCall.id,
                 name: toolCall.name,
-                params
+                params,
+                metadata: reasoningDetailsAttachedToToolCall ? undefined : {
+                  openrouter: { reasoningDetails: accumulatedReasoningDetails }
+                }
               })
-              delete activeToolCalls[toolCall.index]
+
+              reasoningDetailsAttachedToToolCall = true
             }
           }
 
-          // Flush remaining reasoning parts
-          if (Predicate.isNotUndefined(activeReasoningId)) {
+          // End reasoning first if it was started, to maintain proper order
+          if (reasoningStarted) {
             parts.push({
               type: "reasoning-end",
-              id: activeReasoningId
+              id: activeReasoningId!,
+              // Include accumulated reasoning_details so that we can update the
+              // reasoning part's provider metadata with the correct signature,
+              metadata: accumulatedReasoningDetails.length > 0
+                ? { openrouter: { reasoningDetails: accumulatedReasoningDetails } }
+                : undefined
             })
-            activeReasoningId = undefined
           }
 
-          // Flush remaining text parts
-          if (Predicate.isNotUndefined(activeTextId)) {
-            parts.push({
-              type: "text-end",
-              id: activeTextId
-            })
-            activeTextId = undefined
+          if (textStarted) {
+            parts.push({ type: "text-end", id: activeTextId! })
+          }
+
+          const metadata: Response.FinishPart["metadata"] = {
+            openrouter: {
+              ...(Predicate.isNotNullish(event.system_fingerprint)
+                ? { systemFingerprint: event.system_fingerprint }
+                : undefined),
+              ...(Predicate.isNotUndefined(event.usage) ? { usage: event.usage } : undefined),
+              ...(Predicate.hasProperty(event, "provider") && Predicate.isString(event.provider)
+                ? { provider: event.provider }
+                : undefined),
+              ...(accumulatedFileAnnotations.length > 0 ? { annotations: accumulatedFileAnnotations } : undefined)
+            }
           }
 
           parts.push({
             type: "finish",
             reason: finishReason,
-            usage: {
-              inputTokens: event.usage?.prompt_tokens,
-              outputTokens: event.usage?.completion_tokens,
-              totalTokens: event.usage?.total_tokens,
-              reasoningTokens: event.usage?.completion_tokens_details?.reasoning_tokens,
-              cachedInputTokens: event.usage?.prompt_tokens_details?.cached_tokens
-            },
-            metadata: {
-              openrouter: {
-                provider: event.provider,
-                usage: {
-                  cost: event.usage?.cost,
-                  promptTokensDetails: event.usage?.prompt_tokens_details,
-                  completionTokensDetails: event.usage?.completion_tokens_details,
-                  costDetails: event.usage?.cost_details
-                }
-              }
-            }
+            usage,
+            response: buildHttpResponseDetails(response),
+            metadata
           })
         }
 
         return parts
       })),
-      Stream.flattenIterables
+      Stream.flattenIterable
     )
   }
 )
 
+// =============================================================================
+// Tool Conversion
+// =============================================================================
+
+const prepareTools = Effect.fnUntraced(
+  function*({ options, transformer }: {
+    readonly options: LanguageModel.ProviderOptions
+    readonly transformer: LanguageModel.CodecTransformer
+  }): Effect.fn.Return<{
+    readonly tools: ReadonlyArray<typeof Generated.ToolDefinitionJson.Encoded> | undefined
+    readonly toolChoice: typeof Generated.ToolChoiceOption.Encoded | undefined
+  }, AiError.AiError> {
+    if (options.tools.length === 0) {
+      return { tools: undefined, toolChoice: undefined }
+    }
+
+    const hasProviderDefinedTools = options.tools.some((tool) => Tool.isProviderDefined(tool))
+    if (hasProviderDefinedTools) {
+      return yield* AiError.make({
+        module: "OpenRouterLanguageModel",
+        method: "prepareTools",
+        reason: new AiError.InvalidUserInputError({
+          description: "Provider-defined tools are unsupported by the OpenRouter " +
+            "provider integration at this time"
+        })
+      })
+    }
+
+    let tools: Array<typeof Generated.ToolDefinitionJson.Encoded> = []
+    let toolChoice: typeof Generated.ToolChoiceOption.Encoded | undefined = undefined
+
+    for (const tool of options.tools) {
+      const description = Tool.getDescription(tool)
+      const parameters = yield* tryJsonSchema(tool.parametersSchema, "prepareTools", transformer)
+      const strict = Tool.getStrictMode(tool) ?? null
+
+      tools.push({
+        type: "function",
+        function: {
+          name: tool.name,
+          parameters,
+          strict,
+          ...(Predicate.isNotUndefined(description) ? { description } : undefined)
+        }
+      })
+    }
+
+    if (options.toolChoice === "none") {
+      toolChoice = "none"
+    } else if (options.toolChoice === "auto") {
+      toolChoice = "auto"
+    } else if (options.toolChoice === "required") {
+      toolChoice = "required"
+    } else if ("tool" in options.toolChoice) {
+      toolChoice = { type: "function", function: { name: options.toolChoice.tool } }
+    } else {
+      const allowedTools = new Set(options.toolChoice.oneOf)
+      tools = tools.filter((tool) => allowedTools.has(tool.function.name))
+      toolChoice = options.toolChoice.mode === "required" ? "required" : "auto"
+    }
+
+    return { tools, toolChoice }
+  }
+)
+
 // =============================================================================
 // Telemetry
 // =============================================================================
@@ -1068,18 +1334,18 @@ const annotateRequest = (
       topP: request.top_p,
       maxTokens: request.max_tokens,
       stopSequences: Arr.ensure(request.stop).filter(
-        Predicate.isNotNullable
+        Predicate.isNotNullish
       )
     }
   })
 }
 
-const annotateResponse = (span: Span, response: Generated.ChatResponse): void => {
+const annotateResponse = (span: Span, response: Generated.SendChatCompletionRequest200): void => {
   addGenAIAnnotations(span, {
     response: {
       id: response.id,
       model: response.model,
-      finishReasons: response.choices.map((choice) => choice.finish_reason).filter(Predicate.isNotNullable)
+      finishReasons: response.choices.map((choice) => choice.finish_reason).filter(Predicate.isNotNullish)
     },
     usage: {
       inputTokens: response.usage?.prompt_tokens,
@@ -1103,15 +1369,15 @@ const annotateStreamResponse = (span: Span, part: Response.StreamPartEncoded) =>
         finishReasons: [part.reason]
       },
       usage: {
-        inputTokens: part.usage.inputTokens,
-        outputTokens: part.usage.outputTokens
+        inputTokens: part.usage.inputTokens.total,
+        outputTokens: part.usage.outputTokens.total
       }
     })
   }
 }
 
 // =============================================================================
-// Utilities
+// Internal Utilities
 // =============================================================================
 
 const getCacheControl = (
@@ -1124,14 +1390,119 @@ const getCacheControl = (
     | Prompt.ReasoningPart
     | Prompt.FilePart
     | Prompt.ToolResultPart
-): typeof Generated.CacheControlEphemeral.Encoded | undefined => part.options.openrouter?.cacheControl
+): typeof Generated.ChatMessageContentItemCacheControl.Encoded | null => part.options.openrouter?.cacheControl ?? null
+
+const findFirstReasoningDetails = (content: ReadonlyArray<Prompt.AssistantMessagePart>): ReasoningDetails | null => {
+  for (const part of content) {
+    // First try tool calls since they have complete accumulated reasoning details
+    if (part.type === "tool-call") {
+      const details = part.options.openrouter?.reasoningDetails
+      if (Predicate.isNotNullish(details) && Array.isArray(details) && details.length > 0) {
+        return details as ReasoningDetails
+      }
+    }
+
+    // Fallback to reasoning parts which have delta reasoning details
+    if (part.type === "reasoning") {
+      const details = part.options.openrouter?.reasoningDetails
+      if (Predicate.isNotNullish(details) && Array.isArray(details) && details.length > 0) {
+        return details as ReasoningDetails
+      }
+    }
+  }
+
+  return null
+}
+
+const getCodecTransformer = (model: string): LanguageModel.CodecTransformer => {
+  if (model.startsWith("anthropic/") || model.startsWith("claude-")) {
+    return toCodecAnthropic
+  }
+  if (
+    model.startsWith("openai/") ||
+    model.startsWith("gpt-") ||
+    model.startsWith("o1-") ||
+    model.startsWith("o3-") ||
+    model.startsWith("o4-")
+  ) {
+    return toCodecOpenAI
+  }
+  return LanguageModel.defaultCodecTransformer
+}
+
+const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError =>
+  AiError.make({
+    module: "OpenRouterLanguageModel",
+    method,
+    reason: new AiError.UnsupportedSchemaError({
+      description: error instanceof Error ? error.message : String(error)
+    })
+  })
+
+const tryJsonSchema = <S extends Schema.Top>(
+  schema: S,
+  method: string,
+  transformer: LanguageModel.CodecTransformer
+) =>
+  Effect.try({
+    try: () => Tool.getJsonSchemaFromSchema(schema, { transformer }),
+    catch: (error) => unsupportedSchemaError(error, method)
+  })
 
-const getMediaType = (dataUrl: string): string | undefined => {
+const getResponseFormat = Effect.fnUntraced(function*({ config, options, transformer }: {
+  readonly config: typeof Config.Service
+  readonly options: LanguageModel.ProviderOptions
+  readonly transformer: LanguageModel.CodecTransformer
+}): Effect.fn.Return<typeof Generated.ResponseFormatJSONSchema.Encoded | undefined, AiError.AiError> {
+  if (options.responseFormat.type === "json") {
+    const description = SchemaAST.resolveDescription(options.responseFormat.schema.ast)
+    const jsonSchema = yield* tryJsonSchema(options.responseFormat.schema, "getResponseFormat", transformer)
+    return {
+      type: "json_schema",
+      json_schema: {
+        name: options.responseFormat.objectName,
+        schema: jsonSchema,
+        strict: config.strictJsonSchema ?? null,
+        ...(Predicate.isNotUndefined(description) ? { description } : undefined)
+      }
+    }
+  }
+  return undefined
+})
+
+const getMediaType = (dataUrl: string, defaultMediaType: string): string => {
   const match = dataUrl.match(/^data:([^;]+)/)
-  return match ? match[1] : undefined
+  return match ? (match[1] ?? defaultMediaType) : defaultMediaType
 }
 
 const getBase64FromDataUrl = (dataUrl: string): string => {
   const match = dataUrl.match(/^data:[^;]*;base64,(.+)$/)
   return match ? match[1]! : dataUrl
 }
+
+const getUsage = (usage: Generated.ChatGenerationTokenUsage | undefined): Response.Usage => {
+  if (Predicate.isUndefined(usage)) {
+    return {
+      inputTokens: { uncached: undefined, total: 0, cacheRead: undefined, cacheWrite: undefined },
+      outputTokens: { total: 0, text: undefined, reasoning: undefined }
+    }
+  }
+  const promptTokens = usage.prompt_tokens
+  const completionTokens = usage.completion_tokens
+  const cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? 0
+  const cacheWriteTokens = usage.prompt_tokens_details?.cache_write_tokens ?? 0
+  const reasoningTokens = usage.completion_tokens_details?.reasoning_tokens ?? 0
+  return {
+    inputTokens: {
+      uncached: promptTokens - cacheReadTokens,
+      total: promptTokens,
+      cacheRead: cacheReadTokens,
+      cacheWrite: cacheWriteTokens
+    },
+    outputTokens: {
+      total: completionTokens,
+      text: completionTokens - reasoningTokens,
+      reasoning: reasoningTokens
+    }
+  }
+}