@effect/ai-openai 4.0.0-beta.7 → 4.0.0-beta.71

package/src/OpenAiLanguageModel.ts

@@ -1,28 +1,60 @@
 /**
- * OpenAI Language Model implementation.
+ * The `OpenAiLanguageModel` module provides the OpenAI Responses API
+ * implementation of Effect AI's `LanguageModel` service. It translates Effect
+ * AI prompts, files, tools, structured output requests, reasoning metadata, and
+ * provider options into OpenAI response requests, then converts OpenAI
+ * responses and streams back into Effect AI response parts.
  *
- * Provides a LanguageModel implementation for OpenAI's responses API,
- * supporting text generation, structured output, tool calling, and streaming.
+ * **Mental model**
  *
- * @since 1.0.0
+ * `OpenAiClient` owns HTTP transport and provider calls. This module owns
+ * protocol translation: request assembly, tool choice conversion, structured
+ * output codecs, streaming event handling, response metadata, and GenAI
+ * telemetry annotations. {@link model}, {@link layer}, and {@link make} all
+ * build the same OpenAI-backed `LanguageModel.LanguageModel` service from a
+ * model id and optional request defaults.
+ *
+ * **Common tasks**
+ *
+ * - Provide an OpenAI-backed `LanguageModel.LanguageModel` from an existing
+ *   `OpenAiClient`
+ * - Generate text or stream text through Effect AI's provider-neutral language
+ *   model API
+ * - Use OpenAI provider metadata for files, reasoning items, tool calls, and
+ *   response parts
+ * - Scope Responses API defaults with {@link Config} and
+ *   {@link withConfigOverride}
+ *
+ * **Gotchas**
+ *
+ * - Some OpenAI model families receive system instructions as developer
+ *   messages because the Responses API treats them differently.
+ * - File prompt parts are sent either as provider file ids or as base64
+ *   content, depending on `fileIdPrefixes`.
+ * - Structured output and tool-call behavior depends on both Effect AI tool
+ *   definitions and OpenAI model capabilities.
+ *
+ * @since 4.0.0
  */
+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 { 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 * as Schema from "effect/Schema"
 import * as AST from "effect/SchemaAST"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import type { Span } from "effect/Tracer"
-import type { DeepMutable, Simplify } from "effect/Types"
+import type { DeepMutable, Mutable, Simplify } from "effect/Types"
 import * as AiError from "effect/unstable/ai/AiError"
 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 * as Tool from "effect/unstable/ai/Tool"
@@ -31,6 +63,7 @@ import type * as HttpClientResponse from "effect/unstable/http/HttpClientRespons
 import * as Generated from "./Generated.ts"
 import * as InternalUtilities from "./internal/utilities.ts"
 import { OpenAiClient } from "./OpenAiClient.ts"
+import type * as OpenAiSchema from "./OpenAiSchema.ts"
 import { addGenAIAnnotations } from "./OpenAiTelemetry.ts"
 import type * as OpenAiTool from "./OpenAiTool.ts"
 
@@ -38,8 +71,10 @@ const ResponseModelIds = Generated.ModelIdsResponses.members[1]
 const SharedModelIds = Generated.ModelIdsShared.members[1]
 
 /**
- * @since 1.0.0
+ * OpenAI model identifiers supported by the Responses API language model.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Model = typeof ResponseModelIds.Encoded | typeof SharedModelIds.Encoded
 
@@ -55,15 +90,27 @@ type ImageDetail = "auto" | "low" | "high"
 /**
  * Service definition for OpenAI language model configuration.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use when you need to provide OpenAI Responses API request defaults through
+ * Effect context for language model operations.
+ *
+ * **Details**
+ *
+ * Config values are merged with the config object passed to `model`, `make`, or
+ * `layer`, with scoped context values taking precedence.
+ *
+ * @see {@link withConfigOverride} for scoping language model request overrides
+ *
  * @category services
+ * @since 4.0.0
  */
-export class Config extends ServiceMap.Service<
+export class Config extends Context.Service<
   Config,
   Simplify<
     & Partial<
       Omit<
-        typeof Generated.CreateResponse.Encoded,
+        typeof OpenAiSchema.CreateResponse.Encoded,
         "input" | "tools" | "tool_choice" | "stream" | "text"
       >
     >
@@ -105,7 +152,16 @@ export class Config extends ServiceMap.Service<
 // =============================================================================
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * OpenAI-specific options for file prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface FilePartOptions extends ProviderOptions {
+    /**
+     * Provider-specific file options for the OpenAI Responses API.
+     */
     readonly openai?: {
       /**
        * The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
@@ -114,7 +170,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-specific options for reasoning prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ReasoningPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific reasoning options for the OpenAI Responses API.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
@@ -129,7 +194,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-specific options for assistant tool-call prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolCallPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific tool-call options for the OpenAI Responses API.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
@@ -138,7 +212,7 @@ declare module "effect/unstable/ai/Prompt" {
       /**
        * The status of item.
        */
-      readonly status?: typeof Generated.Message.Encoded["status"] | null
+      readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
       /**
        * The ID of the approval request.
        */
@@ -146,7 +220,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-specific options for tool-result prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface ToolResultPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific tool-result options for the OpenAI Responses API.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
@@ -155,7 +238,7 @@ declare module "effect/unstable/ai/Prompt" {
       /**
        * The status of item.
        */
-      readonly status?: typeof Generated.Message.Encoded["status"] | null
+      readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
       /**
        * The ID of the approval request.
        */
@@ -163,7 +246,16 @@ declare module "effect/unstable/ai/Prompt" {
     } | null
   }
 
+  /**
+   * OpenAI-specific options for text prompt parts.
+   *
+   * @category request
+   * @since 4.0.0
+   */
   export interface TextPartOptions extends ProviderOptions {
+    /**
+     * Provider-specific text options for the OpenAI Responses API.
+     */
     readonly openai?: {
       /**
        * The ID of the item to reference.
@@ -172,18 +264,30 @@ declare module "effect/unstable/ai/Prompt" {
       /**
        * The status of item.
        */
-      readonly status?: typeof Generated.Message.Encoded["status"] | null
+      readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
       /**
        * A list of annotations that apply to the output text.
        */
-      readonly annotations?: ReadonlyArray<typeof Generated.Annotation.Encoded> | null
+      readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null
     } | null
   }
 }
 
 declare module "effect/unstable/ai/Response" {
+  /**
+   * OpenAI metadata attached to a complete text response part.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the text part.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the text part.
+       */
       readonly itemId?: string | null
       /**
        * If the model emits a refusal content part, the refusal explanation
@@ -194,63 +298,171 @@ declare module "effect/unstable/ai/Response" {
       /**
        * The status of item.
        */
-      readonly status?: typeof Generated.Message.Encoded["status"] | null
+      readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
       /**
        * The text content part annotations.
        */
-      readonly annotations?: ReadonlyArray<typeof Generated.Annotation.Encoded> | null
+      readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null
     }
   }
 
+  /**
+   * OpenAI metadata emitted when a streamed text part starts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed text start.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the streamed text part.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI metadata emitted when a streamed text part ends.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface TextEndPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed text end.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the streamed text part.
+       */
       readonly itemId?: string | null
-      readonly annotations?: ReadonlyArray<typeof Generated.Annotation.Encoded> | null
+      /**
+       * The annotations collected for the completed streamed text part.
+       */
+      readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null
     } | null
   }
 
+  /**
+   * OpenAI metadata attached to a complete reasoning response part.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the reasoning part.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
+      /**
+       * Encrypted reasoning content that can be sent back in later requests.
+       */
       readonly encryptedContent?: string | null
     } | null
   }
 
+  /**
+   * OpenAI metadata emitted when a streamed reasoning part starts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningStartPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning start.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
+      /**
+       * Encrypted reasoning content that can be sent back in later requests.
+       */
       readonly encryptedContent?: string | null
     } | null
   }
 
+  /**
+   * OpenAI metadata emitted for a streamed reasoning delta.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning delta.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI metadata emitted when a streamed reasoning part ends.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ReasoningEndPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the streamed reasoning end.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the reasoning part.
+       */
       readonly itemId?: string | null
+      /**
+       * Encrypted reasoning content that can be sent back in later requests.
+       */
       readonly encryptedContent?: string
     } | null
   }
 
+  /**
+   * OpenAI metadata attached to tool-call response parts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface ToolCallPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned for the tool call.
+     */
     readonly openai?: {
+      /**
+       * The OpenAI item ID associated with the tool call.
+       */
       readonly itemId?: string | null
     } | null
   }
 
+  /**
+   * OpenAI metadata attached to document source citations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface DocumentSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific citation metadata for the OpenAI Responses API.
+     */
     readonly openai?:
       | {
+        /**
+         * Identifies a citation to an uploaded file.
+         */
         readonly type: "file_citation"
         /**
          * The index of the file in the list of files.
@@ -262,6 +474,9 @@ declare module "effect/unstable/ai/Response" {
         readonly fileId: string
       }
       | {
+        /**
+         * Identifies a citation to a generated file path.
+         */
         readonly type: "file_path"
         /**
          * The index of the file in the list of files.
@@ -273,6 +488,9 @@ declare module "effect/unstable/ai/Response" {
         readonly fileId: string
       }
       | {
+        /**
+         * Identifies a citation to a file inside a container.
+         */
         readonly type: "container_file_citation"
         /**
          * The ID of the file.
@@ -286,8 +504,20 @@ declare module "effect/unstable/ai/Response" {
       | null
   }
 
+  /**
+   * OpenAI metadata attached to URL source citations.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface UrlSourcePartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific URL citation metadata for the OpenAI Responses API.
+     */
     readonly openai?: {
+      /**
+       * Identifies a citation to a URL.
+       */
       readonly type: "url_citation"
       /**
        * The index of the first character of the URL citation in the message.
@@ -300,8 +530,20 @@ declare module "effect/unstable/ai/Response" {
     } | null
   }
 
+  /**
+   * OpenAI metadata attached to finish response parts.
+   *
+   * @category response
+   * @since 4.0.0
+   */
   export interface FinishPartMetadata extends ProviderMetadata {
+    /**
+     * Provider-specific metadata returned when generation finishes.
+     */
     readonly openai?: {
+      /**
+       * The service tier reported by OpenAI for the response.
+       */
       readonly serviceTier?: "default" | "auto" | "flex" | "scale" | "priority" | null
     } | null
   }
@@ -312,31 +554,58 @@ declare module "effect/unstable/ai/Response" {
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * Creates an OpenAI model descriptor that can be provided with
+ * `Effect.provide`.
+ *
+ * **When to use**
+ *
+ * Use when you want an OpenAI language model value that carries provider and
+ * model metadata and can be supplied directly to an Effect program.
+ *
+ * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
+ * @see {@link make} for constructing the language model service effectfully
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: (string & {}) | Model,
   config?: Omit<typeof Config.Service, "model">
 ): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenAiClient> =>
-  AiModel.make("openai", layer({ model, config }))
+  AiModel.make("openai", model, layer({ model, config }))
 
 // TODO
 // /**
-//  * @since 1.0.0
+//  * @since 4.0.0
 //  * @category constructors
 //  */
 // export const modelWithTokenizer = (
 //   model: (string & {}) | Model,
 //   config?: Omit<typeof Config.Service, "model">
 // ): AiModel.Model<"openai", LanguageModel.LanguageModel | Tokenizer.Tokenizer, OpenAiClient> =>
-//   AiModel.make("openai", layerWithTokenizer({ model, config }))
+//   AiModel.make("openai", model, layerWithTokenizer({ model, config }))
 
 /**
- * Creates an OpenAI language model service.
+ * Creates an OpenAI `LanguageModel` service from a model identifier and
+ * optional request defaults.
+ *
+ * **When to use**
+ *
+ * Use when an Effect needs to construct a `LanguageModel.Service` value backed
+ * by `OpenAiClient`.
+ *
+ * **Details**
+ *
+ * The returned effect requires `OpenAiClient`. 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`.
+ *
+ * @see {@link layer} for providing the service as a `Layer`
+ * @see {@link model} for creating a model descriptor for `Effect.provide`
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: (string & {}) | Model
@@ -345,7 +614,7 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
   const client = yield* OpenAiClient
 
   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) }
   })
 
@@ -354,9 +623,9 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
       readonly config: typeof Config.Service
       readonly options: LanguageModel.ProviderOptions
       readonly toolNameMapper: Tool.NameMapper<Tools>
-    }): Effect.fn.Return<typeof Generated.CreateResponse.Encoded, AiError.AiError> {
-      const include = new Set<typeof Generated.IncludeEnum.Encoded>()
-      const capabilities = getModelCapabilities(config.model!)
+    }): Effect.fn.Return<typeof OpenAiSchema.CreateResponse.Encoded, AiError.AiError> {
+      const include = new Set<typeof OpenAiSchema.IncludeEnum.Encoded>()
+      const capabilities = getModelCapabilities(config.model as string)
       const messages = yield* prepareMessages({
         config,
         options,
@@ -369,26 +638,29 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
         options,
         toolNameMapper
       })
-      const responseFormat = prepareResponseFormat({
+      const responseFormat = yield* prepareResponseFormat({
         config,
         options
       })
-      const request: typeof Generated.CreateResponse.Encoded = {
-        ...config,
+      const { fileIdPrefixes: _fip, strictJsonSchema: _sjs, ...apiConfig } = config
+      const request: Mutable<typeof OpenAiSchema.CreateResponse.Encoded> = {
+        ...apiConfig,
         input: messages,
-        include: include.size > 0 ? Array.from(include) : null,
+        include: include.size > 0 ? Array.from(include) : undefined,
         text: {
-          verbosity: config.text?.verbosity ?? null,
+          verbosity: config.text?.verbosity ?? undefined,
           format: responseFormat
-        },
-        ...(Predicate.isNotUndefined(tools) ? { tools } : undefined),
-        ...(Predicate.isNotUndefined(toolChoice) ? { tool_choice: toolChoice } : undefined)
+        }
       }
+      if (tools) request.tools = tools
+      if (toolChoice) request.tool_choice = toolChoice
+      if (options.previousResponseId) request.previous_response_id = options.previousResponseId
       return request
     }
   )
 
   return yield* LanguageModel.make({
+    codecTransformer: toCodecOpenAI,
     generateText: Effect.fnUntraced(
       function*(options) {
         const config = yield* makeConfig
@@ -433,10 +705,27 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 })
 
 /**
- * Creates a layer for the OpenAI language model.
+ * Creates a layer that provides the OpenAI `LanguageModel.LanguageModel`
+ * service.
+ *
+ * **When to use**
+ *
+ * Use when composing application layers and you want OpenAI to satisfy
+ * `LanguageModel.LanguageModel` while supplying `OpenAiClient` from another
+ * layer.
+ *
+ * **Details**
+ *
+ * The `config` option supplies request defaults for the selected model. Scoped
+ * values from `withConfigOverride` are merged when each request is built and
+ * take precedence over these defaults.
+ *
+ * @see {@link make} for constructing the language model service effectfully
+ * @see {@link model} for creating a model descriptor for `Effect.provide`
+ * @see {@link withConfigOverride} for scoped request configuration overrides
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: (string & {}) | Model
@@ -445,39 +734,114 @@ export const layer = (options: {
   Layer.effect(LanguageModel.LanguageModel, make(options))
 
 /**
- * Provides config overrides for OpenAI language model operations.
+ * Provides scoped config overrides for OpenAI language model operations.
+ *
+ * **When to use**
+ *
+ * Use to apply OpenAI Responses API config overrides around one or more
+ * language model operations without changing the defaults passed to `model`,
+ * `make`, or `layer`.
+ *
+ * **Details**
+ *
+ * The override is dual, so it can be used in pipe form or as
+ * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+ * existing `Config` service in the current context, and the override values take
+ * precedence.
+ *
+ * @see {@link Config} for the scoped configuration service consumed by this function
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
-   * Provides config overrides for OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI language model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply OpenAI Responses API config overrides around one or more
+   * language model operations without changing the defaults passed to `model`,
+   * `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * The override is dual, so it can be used in pipe form or as
+   * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+   * existing `Config` service in the current context, and the override values take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped configuration service consumed by this function
    *
-   * @since 1.0.0
    * @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 OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI language model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply OpenAI Responses API config overrides around one or more
+   * language model operations without changing the defaults passed to `model`,
+   * `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * The override is dual, so it can be used in pipe form or as
+   * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+   * existing `Config` service in the current context, and the override values take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped configuration service consumed by this function
    *
-   * @since 1.0.0
    * @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 OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI language model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply OpenAI Responses API config overrides around one or more
+   * language model operations without changing the defaults passed to `model`,
+   * `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * The override is dual, so it can be used in pipe form or as
+   * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+   * existing `Config` service in the current context, and the override values take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped configuration service consumed by this function
    *
-   * @since 1.0.0
    * @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 OpenAI language model operations.
+   * Provides scoped config overrides for OpenAI language model operations.
+   *
+   * **When to use**
+   *
+   * Use to apply OpenAI Responses API config overrides around one or more
+   * language model operations without changing the defaults passed to `model`,
+   * `make`, or `layer`.
+   *
+   * **Details**
+   *
+   * The override is dual, so it can be used in pipe form or as
+   * `withConfigOverride(effect, overrides)`. Overrides are merged with any
+   * existing `Config` service in the current context, and the override values take
+   * precedence.
+   *
+   * @see {@link Config} for the scoped configuration service consumed by this function
    *
-   * @since 1.0.0
    * @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) =>
@@ -512,10 +876,10 @@ const prepareMessages = Effect.fnUntraced(
   }: {
     readonly config: typeof Config.Service
     readonly options: LanguageModel.ProviderOptions
-    readonly include: Set<typeof Generated.IncludeEnum.Encoded>
+    readonly include: Set<typeof OpenAiSchema.IncludeEnum.Encoded>
     readonly capabilities: ModelCapabilities
     readonly toolNameMapper: Tool.NameMapper<Tools>
-  }): Effect.fn.Return<ReadonlyArray<typeof Generated.InputItem.Encoded>, AiError.AiError> {
+  }): Effect.fn.Return<ReadonlyArray<typeof OpenAiSchema.InputItem.Encoded>, AiError.AiError> {
     const processedApprovalIds = new Set<string>()
 
     const hasConversation = Predicate.isNotNullish(config.conversation)
@@ -547,27 +911,28 @@ const prepareMessages = Effect.fnUntraced(
     if (config.store === false && capabilities.isReasoningModel) {
       include.add("reasoning.encrypted_content")
     }
-    if (Predicate.isNotUndefined(codeInterpreterTool)) {
+    if (codeInterpreterTool) {
       include.add("code_interpreter_call.outputs")
     }
-    if (Predicate.isNotUndefined(webSearchTool) || Predicate.isNotUndefined(webSearchPreviewTool)) {
+    if (webSearchTool || webSearchPreviewTool) {
       include.add("web_search_call.action.sources")
     }
 
-    const messages: Array<typeof Generated.InputItem.Encoded> = []
+    const messages: Array<typeof OpenAiSchema.InputItem.Encoded> = []
+    const prompt = options.incrementalPrompt ?? options.prompt
 
-    for (const message of options.prompt.content) {
+    for (const message of prompt.content) {
       switch (message.role) {
         case "system": {
           messages.push({
-            role: getSystemMessageMode(config.model!),
+            role: getSystemMessageMode(config.model as string),
             content: message.content
           })
           break
         }
 
         case "user": {
-          const content: Array<typeof Generated.InputContent.Encoded> = []
+          const content: Array<typeof OpenAiSchema.InputContent.Encoded> = []
 
           for (let index = 0; index < message.content.length; index++) {
             const part = message.content[index]
@@ -630,7 +995,7 @@ const prepareMessages = Effect.fnUntraced(
         }
 
         case "assistant": {
-          const reasoningMessages: Record<string, DeepMutable<typeof Generated.ReasoningItem.Encoded>> = {}
+          const reasoningMessages: Record<string, DeepMutable<typeof OpenAiSchema.ReasoningItem.Encoded>> = {}
 
           for (const part of message.content) {
             switch (part.type) {
@@ -689,7 +1054,7 @@ const prepareMessages = Effect.fnUntraced(
                       }
                     }
                   } else {
-                    const summaryParts: Array<typeof Generated.SummaryTextContent.Encoded> = []
+                    const summaryParts: Array<typeof OpenAiSchema.SummaryTextContent.Encoded> = []
 
                     if (part.text.length > 0) {
                       summaryParts.push({ type: "summary_text", text: part.text })
@@ -700,7 +1065,9 @@ const prepareMessages = Effect.fnUntraced(
                         type: "reasoning",
                         id,
                         summary: summaryParts,
-                        encrypted_content: encryptedContent ?? null
+                        ...(Predicate.isNotNull(encryptedContent)
+                          ? { encrypted_content: encryptedContent }
+                          : undefined)
                       }
 
                       messages.push(reasoningMessages[id])
@@ -921,7 +1288,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>
 })
 
@@ -936,7 +1303,56 @@ const buildHttpResponseDetails = (
 // Response Conversion
 // =============================================================================
 
-type ResponseStreamEvent = typeof Generated.ResponseStreamEvent.Type
+type ResponseStreamEvent = typeof OpenAiSchema.ResponseStreamEvent.Type
+
+type KnownResponseStreamEventType =
+  | "response.created"
+  | "response.completed"
+  | "response.incomplete"
+  | "response.failed"
+  | "response.output_item.added"
+  | "response.output_item.done"
+  | "response.output_text.delta"
+  | "response.output_text.annotation.added"
+  | "response.reasoning_summary_part.added"
+  | "response.reasoning_summary_part.done"
+  | "response.reasoning_summary_text.delta"
+  | "response.function_call_arguments.delta"
+  | "response.function_call_arguments.done"
+  | "response.code_interpreter_call_code.delta"
+  | "response.code_interpreter_call_code.done"
+  | "response.apply_patch_call_operation_diff.delta"
+  | "response.apply_patch_call_operation_diff.done"
+  | "response.image_generation_call.partial_image"
+  | "error"
+
+type KnownResponseStreamEvent = Extract<ResponseStreamEvent, { readonly type: KnownResponseStreamEventType }>
+
+const knownResponseStreamEventTypes = new Set<KnownResponseStreamEventType>([
+  "response.created",
+  "response.completed",
+  "response.incomplete",
+  "response.failed",
+  "response.output_item.added",
+  "response.output_item.done",
+  "response.output_text.delta",
+  "response.output_text.annotation.added",
+  "response.reasoning_summary_part.added",
+  "response.reasoning_summary_part.done",
+  "response.reasoning_summary_text.delta",
+  "response.function_call_arguments.delta",
+  "response.function_call_arguments.done",
+  "response.code_interpreter_call_code.delta",
+  "response.code_interpreter_call_code.done",
+  "response.apply_patch_call_operation_diff.delta",
+  "response.apply_patch_call_operation_diff.done",
+  "response.image_generation_call.partial_image",
+  "error"
+])
+
+const isKnownResponseStreamEvent = (
+  event: ResponseStreamEvent
+): event is KnownResponseStreamEvent => knownResponseStreamEventTypes.has(event.type as KnownResponseStreamEventType)
 
 const makeResponse = Effect.fnUntraced(
   function*<Tools extends ReadonlyArray<Tool.Any>>({
@@ -946,7 +1362,7 @@ const makeResponse = Effect.fnUntraced(
     toolNameMapper
   }: {
     readonly options: LanguageModel.ProviderOptions
-    readonly rawResponse: Generated.Response
+    readonly rawResponse: OpenAiSchema.Response
     readonly response: HttpClientResponse.HttpClientResponse
     readonly toolNameMapper: Tool.NameMapper<Tools>
   }): Effect.fn.Return<
@@ -985,7 +1401,7 @@ const makeResponse = Effect.fnUntraced(
             id: part.call_id,
             name: toolName,
             params: { call_id: part.call_id, operation: part.operation },
-            metadata: { openai: { ...makeItemIdMetadata(part.id) } }
+            metadata: { openai: makeItemIdMetadata(part.id) }
           })
           break
         }
@@ -1036,10 +1452,11 @@ const makeResponse = Effect.fnUntraced(
 
         case "function_call": {
           hasToolCalls = true
+
           const toolName = part.name
-          const toolParams = part.arguments
-          const params = yield* Effect.try({
-            try: () => Tool.unsafeSecureJsonParse(toolParams),
+
+          const toolParams = yield* Effect.try({
+            try: () => Tool.unsafeSecureJsonParse(part.arguments),
             catch: (cause) =>
               AiError.make({
                 module: "OpenAiLanguageModel",
@@ -1051,12 +1468,15 @@ const makeResponse = Effect.fnUntraced(
                 })
               })
           })
+
+          const params = yield* transformToolCallParams(options.tools, part.name, toolParams)
+
           parts.push({
             type: "tool-call",
             id: part.call_id,
             name: toolName,
             params,
-            metadata: { openai: { ...makeItemIdMetadata(part.id) } }
+            metadata: { openai: makeItemIdMetadata(part.id) }
           })
           break
         }
@@ -1087,7 +1507,7 @@ const makeResponse = Effect.fnUntraced(
             id: part.call_id,
             name: toolName,
             params: { action: part.action },
-            metadata: { openai: { ...makeItemIdMetadata(part.id) } }
+            metadata: { openai: makeItemIdMetadata(part.id) }
           })
           break
         }
@@ -1097,13 +1517,17 @@ const makeResponse = Effect.fnUntraced(
             ? (approvalRequests.get(part.approval_request_id) ?? part.id)
             : part.id
 
-          const toolName = `mcp.${part.name}`
+          const { toolName, params } = yield* normalizeMcpToolCall({
+            toolNameMapper,
+            toolParams: part.arguments,
+            method: "makeResponse"
+          })
 
           parts.push({
             type: "tool-call",
             id: toolId,
             name: toolName,
-            params: part.arguments,
+            params,
             providerExecuted: true
           })
 
@@ -1114,14 +1538,14 @@ const makeResponse = Effect.fnUntraced(
             isFailure: false,
             providerExecuted: true,
             result: {
-              type: "call",
+              type: "mcp_call",
               name: part.name,
               arguments: part.arguments,
               server_label: part.server_label,
               ...(Predicate.isNotNullish(part.output) ? { output: part.output } : undefined),
               ...(Predicate.isNotNullish(part.error) ? { error: part.error } : undefined)
             },
-            metadata: { openai: { ...makeItemIdMetadata(part.id) } }
+            metadata: { openai: makeItemIdMetadata(part.id) }
           })
 
           break
@@ -1135,20 +1559,11 @@ const makeResponse = Effect.fnUntraced(
         case "mcp_approval_request": {
           const approvalRequestId = (part as any).approval_request_id ?? part.id
           const toolId = yield* idGenerator.generateId()
-          const toolName = `mcp.${part.name}`
 
-          const params = yield* Effect.try({
-            try: () => Tool.unsafeSecureJsonParse(part.arguments),
-            catch: (cause) =>
-              AiError.make({
-                module: "OpenAiLanguageModel",
-                method: "makeResponse",
-                reason: new AiError.ToolParameterValidationError({
-                  toolName,
-                  toolParams: {},
-                  description: `Failed securely JSON parse tool parameters: ${cause}`
-                })
-              })
+          const { toolName, params } = yield* normalizeMcpToolCall({
+            toolNameMapper,
+            toolParams: part.arguments,
+            method: "makeResponse"
           })
 
           parts.push({
@@ -1296,7 +1711,7 @@ const makeResponse = Effect.fnUntraced(
             id: part.call_id,
             name: toolName,
             params: { action: part.action },
-            metadata: { openai: { ...makeItemIdMetadata(part.id) } }
+            metadata: { openai: makeItemIdMetadata(part.id) }
           })
           break
         }
@@ -1335,7 +1750,7 @@ const makeResponse = Effect.fnUntraced(
       reason: finishReason,
       usage: getUsage(rawResponse.usage),
       response: buildHttpResponseDetails(response),
-      ...(rawResponse.service_tier && { metadata: { openai: { serviceTier: rawResponse.service_tier } } })
+      ...toServiceTier(rawResponse.service_tier)
     })
 
     return parts
@@ -1368,18 +1783,44 @@ const makeStreamResponse = Effect.fnUntraced(
     let hasToolCalls = false
 
     // Track annotations for current message to include in text-end metadata
-    const activeAnnotations: Array<typeof Generated.Annotation.Encoded> = []
+    const activeAnnotations: Array<typeof OpenAiSchema.Annotation.Encoded> = []
+
+    type ReasoningSummaryPartStatus = "active" | "can-conclude" | "concluded"
+    type ReasoningPart = {
+      encryptedContent: string | undefined
+      summaryParts: Record<number, ReasoningSummaryPartStatus>
+    }
 
     // Track active reasoning items with state machine for proper concluding logic
-    const activeReasoning: Record<string, {
-      readonly encryptedContent: string | undefined
-      readonly summaryParts: Record<number, "active" | "can-conclude" | "concluded">
-    }> = {}
+    const activeReasoning: Record<string, ReasoningPart> = {}
+
+    const getOrCreateReasoningPart = (
+      itemId: string,
+      encryptedContent?: string | null
+    ): ReasoningPart => {
+      const activePart = activeReasoning[itemId]
+      if (Predicate.isNotUndefined(activePart)) {
+        if (Predicate.isNotNullish(encryptedContent)) {
+          activePart.encryptedContent = encryptedContent
+        }
+        return activePart
+      }
+
+      const reasoningPart: ReasoningPart = {
+        encryptedContent: Predicate.isNotNullish(encryptedContent) ? encryptedContent : undefined,
+        summaryParts: {}
+      }
+      activeReasoning[itemId] = reasoningPart
+      return reasoningPart
+    }
 
     // Track active tool calls with optional provider-specific state
     const activeToolCalls: Record<number, {
       readonly id: string
       readonly name: string
+      readonly functionCall?: {
+        emitted: boolean
+      }
       readonly applyPatch?: {
         hasDiff: boolean
         endEmitted: boolean
@@ -1399,6 +1840,10 @@ const makeStreamResponse = Effect.fnUntraced(
       Stream.mapEffect(Effect.fnUntraced(function*(event) {
         const parts: Array<Response.StreamPartEncoded> = []
 
+        if (!isKnownResponseStreamEvent(event)) {
+          return parts
+        }
+
         switch (event.type) {
           case "response.created": {
             const createdAt = new Date(event.response.created_at * 1000)
@@ -1428,7 +1873,7 @@ const makeStreamResponse = Effect.fnUntraced(
               ),
               usage: getUsage(event.response.usage),
               response: buildHttpResponseDetails(response),
-              ...(event.response.service_tier && { metadata: { openai: { serviceTier: event.response.service_tier } } })
+              ...toServiceTier(event.response.service_tier)
             })
             break
           }
@@ -1529,7 +1974,8 @@ const makeStreamResponse = Effect.fnUntraced(
               case "function_call": {
                 activeToolCalls[event.output_index] = {
                   id: event.item.call_id,
-                  name: event.item.name
+                  name: event.item.name,
+                  functionCall: { emitted: false }
                 }
                 parts.push({
                   type: "tool-params-start",
@@ -1566,34 +2012,33 @@ const makeStreamResponse = Effect.fnUntraced(
                 parts.push({
                   type: "text-start",
                   id: event.item.id,
-                  metadata: { openai: { ...makeItemIdMetadata(event.item.id) } }
+                  metadata: { openai: makeItemIdMetadata(event.item.id) }
                 })
                 break
               }
 
               case "reasoning": {
-                const encryptedContent = event.item.encrypted_content ?? undefined
-                activeReasoning[event.item.id] = {
-                  encryptedContent,
-                  summaryParts: { 0: "active" }
-                }
-                parts.push({
-                  type: "reasoning-start",
-                  id: `${event.item.id}:0`,
-                  metadata: {
-                    openai: {
-                      ...makeItemIdMetadata(event.item.id),
-                      ...makeEncryptedContentMetadata(event.item.encrypted_content)
+                const reasoningPart = getOrCreateReasoningPart(event.item.id, event.item.encrypted_content)
+                if (Predicate.isUndefined(reasoningPart.summaryParts[0])) {
+                  reasoningPart.summaryParts[0] = "active"
+                  parts.push({
+                    type: "reasoning-start",
+                    id: `${event.item.id}:0`,
+                    metadata: {
+                      openai: {
+                        ...makeItemIdMetadata(event.item.id),
+                        ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
+                      }
                     }
-                  }
-                })
+                  })
+                }
                 break
               }
 
               case "shell_call": {
                 const toolName = toolNameMapper.getCustomName("shell")
                 activeToolCalls[event.output_index] = {
-                  id: event.item.id,
+                  id: event.item.id ?? event.item.call_id,
                   name: toolName
                 }
                 break
@@ -1644,7 +2089,7 @@ const makeStreamResponse = Effect.fnUntraced(
                     parts.push({
                       type: "tool-params-delta",
                       id: toolCall.id,
-                      delta: InternalUtilities.escapeJSONDelta(event.item.operation.diff)
+                      delta: InternalUtilities.escapeJSONDelta(event.item.operation.diff ?? "")
                     })
                   }
                   parts.push({
@@ -1666,7 +2111,7 @@ const makeStreamResponse = Effect.fnUntraced(
                     id: toolCall.id,
                     name: toolName,
                     params: { call_id: event.item.call_id, operation: event.item.operation },
-                    metadata: { openai: { ...makeItemIdMetadata(event.item.id) } }
+                    metadata: { openai: makeItemIdMetadata(event.item.id) }
                   })
                 }
                 delete activeToolCalls[event.output_index]
@@ -1729,12 +2174,20 @@ const makeStreamResponse = Effect.fnUntraced(
               }
 
               case "function_call": {
+                const toolCall = activeToolCalls[event.output_index]
+                if (Predicate.isNotUndefined(toolCall?.functionCall?.emitted) && toolCall.functionCall.emitted) {
+                  delete activeToolCalls[event.output_index]
+                  break
+                }
                 delete activeToolCalls[event.output_index]
+
                 hasToolCalls = true
+
                 const toolName = event.item.name
-                const toolParams = event.item.arguments
-                const params = yield* Effect.try({
-                  try: () => Tool.unsafeSecureJsonParse(toolParams),
+                const toolArgs = event.item.arguments
+
+                const toolParams = yield* Effect.try({
+                  try: () => Tool.unsafeSecureJsonParse(toolArgs),
                   catch: (cause) =>
                     AiError.make({
                       module: "OpenAiLanguageModel",
@@ -1746,17 +2199,22 @@ const makeStreamResponse = Effect.fnUntraced(
                       })
                     })
                 })
+
+                const params = yield* transformToolCallParams(options.tools, toolName, toolParams)
+
                 parts.push({
                   type: "tool-params-end",
                   id: event.item.call_id
                 })
+
                 parts.push({
                   type: "tool-call",
                   id: event.item.call_id,
                   name: toolName,
                   params,
-                  metadata: { openai: { ...makeItemIdMetadata(event.item.id) } }
+                  metadata: { openai: makeItemIdMetadata(event.item.id) }
                 })
+
                 break
               }
 
@@ -1780,7 +2238,7 @@ const makeStreamResponse = Effect.fnUntraced(
                   id: event.item.call_id,
                   name: toolName,
                   params: { action: event.item.action },
-                  metadata: { openai: { ...makeItemIdMetadata(event.item.id) } }
+                  metadata: { openai: makeItemIdMetadata(event.item.id) }
                 })
                 break
               }
@@ -1794,13 +2252,17 @@ const makeStreamResponse = Effect.fnUntraced(
                     event.item.id)
                   : event.item.id
 
-                const toolName = `mcp.${event.item.name}`
+                const { toolName, params } = yield* normalizeMcpToolCall({
+                  toolNameMapper,
+                  toolParams: event.item.arguments,
+                  method: "makeStreamResponse"
+                })
 
                 parts.push({
                   type: "tool-call",
                   id: toolId,
                   name: toolName,
-                  params: event.item.arguments,
+                  params,
                   providerExecuted: true
                 })
 
@@ -1811,14 +2273,14 @@ const makeStreamResponse = Effect.fnUntraced(
                   isFailure: false,
                   providerExecuted: true,
                   result: {
-                    type: "call",
+                    type: "mcp_call",
                     name: event.item.name,
                     arguments: event.item.arguments,
                     server_label: event.item.server_label,
                     ...(Predicate.isNotNullish(event.item.output) ? { output: event.item.output } : undefined),
                     ...(Predicate.isNotNullish(event.item.error) ? { error: event.item.error } : undefined)
                   },
-                  metadata: { openai: { ...makeItemIdMetadata(event.item.id) } }
+                  metadata: { openai: makeItemIdMetadata(event.item.id) }
                 })
 
                 break
@@ -1833,12 +2295,16 @@ const makeStreamResponse = Effect.fnUntraced(
                 const toolId = yield* idGenerator.generateId()
                 const approvalRequestId = (event.item as any).approval_request_id ?? event.item.id
                 streamApprovalRequests.set(approvalRequestId, toolId)
-                const toolName = `mcp.${event.item.name}`
+                const { toolName, params } = yield* normalizeMcpToolCall({
+                  toolNameMapper,
+                  toolParams: event.item.arguments,
+                  method: "makeStreamResponse"
+                })
                 parts.push({
                   type: "tool-call",
                   id: toolId,
                   name: toolName,
-                  params: event.item.arguments,
+                  params,
                   providerExecuted: true
                 })
                 parts.push({
@@ -1862,7 +2328,7 @@ const makeStreamResponse = Effect.fnUntraced(
               }
 
               case "reasoning": {
-                const reasoningPart = activeReasoning[event.item.id]
+                const reasoningPart = getOrCreateReasoningPart(event.item.id, event.item.encrypted_content)
                 for (const [summaryIndex, status] of Object.entries(reasoningPart.summaryParts)) {
                   if (status === "active" || status === "can-conclude") {
                     parts.push({
@@ -1871,7 +2337,7 @@ const makeStreamResponse = Effect.fnUntraced(
                       metadata: {
                         openai: {
                           ...makeItemIdMetadata(event.item.id),
-                          ...makeEncryptedContentMetadata(event.item.encrypted_content)
+                          ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
                         }
                       }
                     })
@@ -1886,10 +2352,10 @@ const makeStreamResponse = Effect.fnUntraced(
                 const toolName = toolNameMapper.getCustomName("shell")
                 parts.push({
                   type: "tool-call",
-                  id: event.item.id,
+                  id: event.item.id ?? event.item.call_id,
                   name: toolName,
                   params: { action: event.item.action },
-                  metadata: { openai: { ...makeItemIdMetadata(event.item.id) } }
+                  metadata: { openai: makeItemIdMetadata(event.item.id) }
                 })
                 break
               }
@@ -1924,7 +2390,7 @@ const makeStreamResponse = Effect.fnUntraced(
           }
 
           case "response.output_text.annotation.added": {
-            const annotation = event.annotation as typeof Generated.Annotation.Encoded
+            const annotation = event.annotation as typeof OpenAiSchema.Annotation.Encoded
             // Track annotation for text-end metadata
             activeAnnotations.push(annotation)
             if (annotation.type === "container_file_citation") {
@@ -2006,6 +2472,48 @@ const makeStreamResponse = Effect.fnUntraced(
             break
           }
 
+          case "response.function_call_arguments.done": {
+            const toolCall = activeToolCalls[event.output_index]
+            if (
+              Predicate.isNotUndefined(toolCall?.functionCall) &&
+              !toolCall.functionCall.emitted
+            ) {
+              hasToolCalls = true
+
+              const toolParams = yield* Effect.try({
+                try: () => Tool.unsafeSecureJsonParse(event.arguments),
+                catch: (cause) =>
+                  AiError.make({
+                    module: "OpenAiLanguageModel",
+                    method: "makeStreamResponse",
+                    reason: new AiError.ToolParameterValidationError({
+                      toolName: toolCall.name,
+                      toolParams: {},
+                      description: `Failed securely JSON parse tool parameters: ${cause}`
+                    })
+                  })
+              })
+
+              const params = yield* transformToolCallParams(options.tools, toolCall.name, toolParams)
+
+              parts.push({
+                type: "tool-params-end",
+                id: toolCall.id
+              })
+
+              parts.push({
+                type: "tool-call",
+                id: toolCall.id,
+                name: toolCall.name,
+                params,
+                metadata: { openai: makeItemIdMetadata(event.item_id) }
+              })
+
+              toolCall.functionCall.emitted = true
+            }
+            break
+          }
+
           case "response.apply_patch_call_operation_diff.delta": {
             const toolCall = activeToolCalls[event.output_index]
             if (Predicate.isNotUndefined(toolCall?.applyPatch)) {
@@ -2095,28 +2603,28 @@ const makeStreamResponse = Effect.fnUntraced(
           }
 
           case "response.reasoning_summary_part.added": {
-            // The first reasoning start is pushed in the `response.output_item.added` block
+            const reasoningPart = getOrCreateReasoningPart(event.item_id)
             if (event.summary_index > 0) {
-              const reasoningPart = activeReasoning[event.item_id]
-              if (Predicate.isNotUndefined(reasoningPart)) {
-                // Conclude all can-conclude parts before starting new one
-                for (const [summaryIndex, status] of Object.entries(reasoningPart.summaryParts)) {
-                  if (status === "can-conclude") {
-                    parts.push({
-                      type: "reasoning-end",
-                      id: `${event.item_id}:${summaryIndex}`,
-                      metadata: {
-                        openai: {
-                          ...makeItemIdMetadata(event.item_id),
-                          ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
-                        }
+              // Conclude all can-conclude parts before starting new one
+              for (const [summaryIndex, status] of Object.entries(reasoningPart.summaryParts)) {
+                if (status === "can-conclude") {
+                  parts.push({
+                    type: "reasoning-end",
+                    id: `${event.item_id}:${summaryIndex}`,
+                    metadata: {
+                      openai: {
+                        ...makeItemIdMetadata(event.item_id),
+                        ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
                       }
-                    })
-                    reasoningPart.summaryParts[Number(summaryIndex)] = "concluded"
-                  }
+                    }
+                  })
+                  reasoningPart.summaryParts[Number(summaryIndex)] = "concluded"
                 }
-                reasoningPart.summaryParts[event.summary_index] = "active"
               }
+            }
+
+            if (Predicate.isUndefined(reasoningPart.summaryParts[event.summary_index])) {
+              reasoningPart.summaryParts[event.summary_index] = "active"
               parts.push({
                 type: "reasoning-start",
                 id: `${event.item_id}:${event.summary_index}`,
@@ -2136,26 +2644,27 @@ const makeStreamResponse = Effect.fnUntraced(
               type: "reasoning-delta",
               id: `${event.item_id}:${event.summary_index}`,
               delta: event.delta,
-              metadata: { openai: { ...makeItemIdMetadata(event.item_id) } }
+              metadata: { openai: makeItemIdMetadata(event.item_id) }
             })
             break
           }
 
           case "response.reasoning_summary_part.done": {
+            const reasoningPart = getOrCreateReasoningPart(event.item_id)
             // When OpenAI stores message data, we can immediately conclude the
             // reasoning part given that we do not need the encrypted content
             if (config.store === true) {
               parts.push({
                 type: "reasoning-end",
                 id: `${event.item_id}:${event.summary_index}`,
-                metadata: { openai: { ...makeItemIdMetadata(event.item_id) } }
+                metadata: { openai: makeItemIdMetadata(event.item_id) }
               })
               // Mark the summary part concluded
-              activeReasoning[event.item_id].summaryParts[event.summary_index] = "concluded"
+              reasoningPart.summaryParts[event.summary_index] = "concluded"
             } else {
               // Mark the summary part as can-conclude given we still need a
               // final summary part with the encrypted content
-              activeReasoning[event.item_id].summaryParts[event.summary_index] = "can-conclude"
+              reasoningPart.summaryParts[event.summary_index] = "can-conclude"
             }
             break
           }
@@ -2174,7 +2683,7 @@ const makeStreamResponse = Effect.fnUntraced(
 
 const annotateRequest = (
   span: Span,
-  request: typeof Generated.CreateResponse.Encoded
+  request: typeof OpenAiSchema.CreateResponse.Encoded
 ): void => {
   addGenAIAnnotations(span, {
     system: "openai",
@@ -2194,7 +2703,7 @@ const annotateRequest = (
   })
 }
 
-const annotateResponse = (span: Span, response: Generated.Response): void => {
+const annotateResponse = (span: Span, response: OpenAiSchema.Response): void => {
   const finishReason = response.incomplete_details?.reason as string | undefined
   addGenAIAnnotations(span, {
     response: {
@@ -2244,7 +2753,7 @@ const annotateStreamResponse = (span: Span, part: Response.StreamPartEncoded) =>
 // Tool Conversion
 // =============================================================================
 
-type OpenAiToolChoice = typeof Generated.CreateResponse.Encoded["tool_choice"]
+type OpenAiToolChoice = typeof OpenAiSchema.CreateResponse.Encoded["tool_choice"]
 
 const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Tool.Any>>({
   config,
@@ -2255,7 +2764,7 @@ const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Too
   readonly options: LanguageModel.ProviderOptions
   readonly toolNameMapper: Tool.NameMapper<Tools>
 }): Effect.fn.Return<{
-  readonly tools: ReadonlyArray<typeof Generated.Tool.Encoded> | undefined
+  readonly tools: ReadonlyArray<typeof OpenAiSchema.Tool.Encoded> | undefined
   readonly toolChoice: OpenAiToolChoice | undefined
 }, AiError.AiError> {
   // Return immediately if no tools are in the toolkit
@@ -2263,7 +2772,7 @@ const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Too
     return { tools: undefined, toolChoice: undefined }
   }
 
-  const tools: Array<typeof Generated.Tool.Encoded> = []
+  const tools: Array<typeof OpenAiSchema.Tool.Encoded> = []
   let toolChoice: OpenAiToolChoice | undefined = undefined
 
   // Filter the incoming tools down to the set of allowed tools as indicated by
@@ -2279,14 +2788,16 @@ const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Too
 
   // Convert the tools in the toolkit to the provider-defined format
   for (const tool of allowedTools) {
-    if (Tool.isUserDefined(tool)) {
+    if (Tool.isUserDefined(tool) || Tool.isDynamic(tool)) {
       const strict = Tool.getStrictMode(tool) ?? config.strictJsonSchema ?? true
+      const description = Tool.getDescription(tool)
+      const parameters = yield* tryToolJsonSchema(tool, "prepareTools")
       tools.push({
         type: "function",
         name: tool.name,
-        description: Tool.getDescription(tool) ?? null,
-        parameters: Tool.getJsonSchema(tool) as { readonly [x: string]: Schema.Json },
-        strict
+        parameters,
+        strict,
+        ...(Predicate.isNotUndefined(description) ? { description } : undefined)
       })
     }
 
@@ -2468,35 +2979,63 @@ const getStatus = (
     | Prompt.TextPart
     | Prompt.ToolCallPart
     | Prompt.ToolResultPart
-): typeof Generated.Message.Encoded["status"] | null => part.options.openai?.status ?? null
+): typeof OpenAiSchema.MessageStatus.Encoded | null => part.options.openai?.status ?? null
 const getEncryptedContent = (
   part: Prompt.ReasoningPart
 ): string | null => part.options.openai?.encryptedContent ?? null
 
 const getImageDetail = (part: Prompt.FilePart): ImageDetail => part.options.openai?.imageDetail ?? "auto"
 
-const makeItemIdMetadata = (itemId: string | undefined) => Predicate.isNotUndefined(itemId) ? { itemId } : undefined
+const makeItemIdMetadata = (itemId: string | undefined) => Predicate.isNotUndefined(itemId) ? { itemId } : {}
 
 const makeEncryptedContentMetadata = (encryptedContent: string | null | undefined) =>
   Predicate.isNotNullish(encryptedContent) ? { encryptedContent } : undefined
 
-const prepareResponseFormat = ({ config, options }: {
+const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError =>
+  AiError.make({
+    module: "OpenAiLanguageModel",
+    method,
+    reason: new AiError.UnsupportedSchemaError({
+      description: error instanceof Error ? error.message : String(error)
+    })
+  })
+
+const tryCodecTransform = <S extends Schema.Top>(schema: S, method: string) =>
+  Effect.try({
+    try: () => toCodecOpenAI(schema),
+    catch: (error) => unsupportedSchemaError(error, method)
+  })
+
+const tryJsonSchema = <S extends Schema.Top>(schema: S, method: string) =>
+  Effect.try({
+    try: () => Tool.getJsonSchemaFromSchema(schema, { transformer: toCodecOpenAI }),
+    catch: (error) => unsupportedSchemaError(error, method)
+  })
+
+const tryToolJsonSchema = <T extends Tool.Any>(tool: T, method: string) =>
+  Effect.try({
+    try: () => Tool.getJsonSchema(tool, { transformer: toCodecOpenAI }),
+    catch: (error) => unsupportedSchemaError(error, method)
+  })
+
+const prepareResponseFormat = Effect.fnUntraced(function*({ config, options }: {
   readonly config: typeof Config.Service
   readonly options: LanguageModel.ProviderOptions
-}): typeof Generated.TextResponseFormatConfiguration.Encoded => {
+}): Effect.fn.Return<typeof OpenAiSchema.TextResponseFormatConfiguration.Encoded, AiError.AiError> {
   if (options.responseFormat.type === "json") {
     const name = options.responseFormat.objectName
     const schema = options.responseFormat.schema
+    const jsonSchema = yield* tryJsonSchema(schema, "prepareResponseFormat")
     return {
       type: "json_schema",
       name,
       description: AST.resolveDescription(schema.ast) ?? "Response with a JSON object",
-      schema: Tool.getJsonSchemaFromSchema(schema) as any,
+      schema: jsonSchema,
       strict: config.strictJsonSchema ?? true
     }
   }
   return { type: "text" }
-}
+})
 
 interface ModelCapabilities {
   readonly isReasoningModel: boolean
@@ -2570,7 +3109,42 @@ const getApprovalRequestIdMapping = (prompt: Prompt.Prompt): ReadonlyMap<string,
   return mapping
 }
 
-const getUsage = (usage: Generated.ResponseUsage | null | undefined): Response.Usage => {
+const normalizeMcpToolCall = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Tool.Any>>({
+  toolNameMapper,
+  toolParams,
+  method
+}: {
+  readonly toolNameMapper: Tool.NameMapper<Tools>
+  readonly toolParams: unknown
+  readonly method: string
+}): Effect.fn.Return<{
+  readonly toolName: string
+  readonly params: unknown
+}, AiError.AiError> {
+  const toolName = toolNameMapper.getCustomName("mcp")
+
+  if (typeof toolParams !== "string") {
+    return { toolName, params: toolParams }
+  }
+
+  const params = yield* Effect.try({
+    try: () => Tool.unsafeSecureJsonParse(toolParams),
+    catch: (cause) =>
+      AiError.make({
+        module: "OpenAiLanguageModel",
+        method,
+        reason: new AiError.ToolParameterValidationError({
+          toolName,
+          toolParams,
+          description: `Failed to securely JSON parse tool parameters: ${cause}`
+        })
+      })
+  })
+
+  return { toolName, params }
+})
+
+const getUsage = (usage: OpenAiSchema.ResponseUsage | null | undefined): Response.Usage => {
   if (Predicate.isNullish(usage)) {
     return {
       inputTokens: {
@@ -2589,8 +3163,8 @@ const getUsage = (usage: Generated.ResponseUsage | null | undefined): Response.U
 
   const inputTokens = usage.input_tokens
   const outputTokens = usage.output_tokens
-  const cachedTokens = usage.input_tokens_details.cached_tokens
-  const reasoningTokens = usage.output_tokens_details.reasoning_tokens
+  const cachedTokens = getUsageTokenDetail(usage.input_tokens_details, "cached_tokens")
+  const reasoningTokens = getUsageTokenDetail(usage.output_tokens_details, "reasoning_tokens")
 
   return {
     inputTokens: {
@@ -2606,3 +3180,64 @@ const getUsage = (usage: Generated.ResponseUsage | null | undefined): Response.U
     }
   }
 }
+
+type ServiceTier = "default" | "auto" | "flex" | "scale" | "priority" | null
+
+const toServiceTier = (value: string | undefined): {
+  readonly metadata: {
+    readonly openai: {
+      readonly serviceTier: ServiceTier
+    }
+  }
+} | undefined => {
+  switch (value) {
+    case "default":
+    case "auto":
+    case "flex":
+    case "scale":
+    case "priority":
+      return { metadata: { openai: { serviceTier: value } } }
+    default:
+      return undefined
+  }
+}
+
+const getUsageTokenDetail = (details: unknown, key: string): number =>
+  Predicate.hasProperty(details, key) && typeof details[key] === "number" ? details[key] : 0
+
+const transformToolCallParams = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Tool.Any>>(
+  tools: Tools,
+  toolName: string,
+  toolParams: unknown
+): Effect.fn.Return<unknown, AiError.AiError> {
+  const tool = tools.find((tool) => tool.name === toolName)
+
+  if (Predicate.isUndefined(tool)) {
+    return yield* AiError.make({
+      module: "OpenAiLanguageModel",
+      method: "makeResponse",
+      reason: new AiError.ToolNotFoundError({
+        toolName,
+        availableTools: tools.map((tool) => tool.name)
+      })
+    })
+  }
+
+  const { codec } = yield* tryCodecTransform(tool.parametersSchema, "makeResponse")
+
+  const transform = Schema.decodeEffect(codec)
+
+  return yield* (
+    transform(toolParams) as Effect.Effect<unknown, Schema.SchemaError>
+  ).pipe(Effect.mapError((error) =>
+    AiError.make({
+      module: "OpenAiLanguageModel",
+      method: "makeResponse",
+      reason: new AiError.ToolParameterValidationError({
+        toolName,
+        toolParams,
+        description: error.issue.toString()
+      })
+    })
+  ))
+})