The best way to control Claude Code, Codex and more from any computer or phone

main
ts 3,412 lines 114 KB
Raw
1 /**
2 * The `OpenAiLanguageModel` module provides the OpenAI Responses API
3 * implementation of Effect AI's `LanguageModel` service. It translates Effect
4 * AI prompts, files, tools, structured output requests, reasoning metadata, and
5 * provider options into OpenAI response requests, then converts OpenAI
6 * non-streaming or streaming response results back into Effect AI response
7 * content and metadata.
8 *
9 * @stability unstable
10 * @since 4.0.0
11 */
12 import * as AiError from "effect/ai/AiError"
13 import * as IdGenerator from "effect/ai/IdGenerator"
14 import * as LanguageModel from "effect/ai/LanguageModel"
15 import * as AiModel from "effect/ai/Model"
16 import { toCodecOpenAI } from "effect/ai/OpenAiStructuredOutput"
17 import type * as Prompt from "effect/ai/Prompt"
18 import type * as Response from "effect/ai/Response"
19 import * as Tool from "effect/ai/Tool"
20 import * as Context from "effect/Context"
21 import * as DateTime from "effect/DateTime"
22 import * as Effect from "effect/Effect"
23 import * as Base64 from "effect/encoding/Base64"
24 import { dual } from "effect/Function"
25 import type * as HttpClientResponse from "effect/http/HttpClientResponse"
26 import * as Layer from "effect/Layer"
27 import * as Option from "effect/Option"
28 import * as Predicate from "effect/Predicate"
29 import * as Redactable from "effect/Redactable"
30 import * as Schema from "effect/Schema"
31 import * as AST from "effect/SchemaAST"
32 import * as Stream from "effect/Stream"
33 import type { Span } from "effect/Tracer"
34 import type { DeepMutable, Mutable, Simplify } from "effect/Types"
35 import * as Generated from "./Generated.ts"
36 import * as InternalUtilities from "./internal/utilities.ts"
37 import { OpenAiClient, OpenAiSocket } from "./OpenAiClient.ts"
38 import type * as OpenAiSchema from "./OpenAiSchema.ts"
39 import { addGenAIAnnotations } from "./OpenAiTelemetry.ts"
40 import type * as OpenAiTool from "./OpenAiTool.ts"
41
42 const ResponseModelIds = Generated.ModelIdsResponses.members[1]
43 const SharedModelIds = Generated.ModelIdsShared.members[1]
44
45 /**
46 * OpenAI model identifiers supported by the Responses API language model.
47 *
48 * @stability unstable
49 * @category models
50 * @since 4.0.0
51 */
52 export type Model = typeof ResponseModelIds.Encoded | typeof SharedModelIds.Encoded
53
54 /**
55 * Image detail level for vision requests.
56 */
57 type ImageDetail = "auto" | "low" | "high"
58
59 type PromptCacheBreakpoint = { readonly mode: "explicit" }
60
61 // =============================================================================
62 // Configuration
63 // =============================================================================
64
65 /**
66 * Context service for OpenAI language model configuration.
67 *
68 * **When to use**
69 *
70 * Use when you need to provide OpenAI Responses API request defaults through
71 * Effect context for language model operations.
72 *
73 * **Details**
74 *
75 * Config values are merged with the config object passed to `model`, `make`, or
76 * `layer`, with scoped context values taking precedence.
77 *
78 * Explicit `include` values are merged with automatic entries without duplicates.
79 *
80 * @see {@link withConfigOverride} for scoping language model request overrides
81 *
82 * @stability unstable
83 * @category services
84 * @since 4.0.0
85 */
86 export class Config extends Context.Service<
87 Config,
88 Simplify<
89 & Partial<
90 Omit<
91 typeof OpenAiSchema.CreateResponse.Encoded,
92 "input" | "tools" | "tool_choice" | "stream" | "text"
93 >
94 >
95 & {
96 /**
97 * File ID prefixes used to identify file IDs in Responses API.
98 * When undefined, all file data is treated as base64 content.
99 *
100 * Examples:
101 * - OpenAI: ['file-'] for IDs like 'file-abc123'
102 * - Azure OpenAI: ['assistant-'] for IDs like 'assistant-abc123'
103 */
104 readonly fileIdPrefixes?: ReadonlyArray<string> | undefined
105 /**
106 * Configuration options for a text response from the model.
107 */
108 readonly text?: {
109 /**
110 * Constrains the verbosity of the model's response. Lower values will
111 * result in more concise responses, while higher values will result in
112 * more verbose responses.
113 *
114 * Defaults to `"medium"`.
115 */
116 readonly verbosity?: "low" | "medium" | "high" | undefined
117 } | undefined
118 /**
119 * Whether to use strict JSON schema validation.
120 *
121 * Defaults to `true`.
122 */
123 readonly strictJsonSchema?: boolean | undefined
124 /**
125 * Whether stored response items should be sent as item references.
126 *
127 * Set to `false` for OpenAI-compatible providers that support response
128 * storage and `previous_response_id`, but require historical assistant
129 * content to be serialized inline.
130 *
131 * Defaults to `true` when `store` is `true`.
132 */
133 readonly useItemReferences?: boolean | undefined
134 /**
135 * Override reasoning model detection. Reasoning models use the `developer`
136 * role for system prompts and request `reasoning.encrypted_content` when
137 * item references are disabled or a WebSocket connection is used.
138 *
139 * Defaults to `true` except for `gpt-3*`, `gpt-4*`, `chatgpt-*`,
140 * `chat-latest`, and `gpt-<version>-chat*`. Fine-tuned `ft:` models follow
141 * their base model.
142 *
143 * Set to `false` for deployments that do not support these defaults.
144 * Explicit `include` values are still preserved.
145 */
146 readonly reasoningModel?: boolean | undefined
147 }
148 >
149 >()("@effect/ai-openai/OpenAiLanguageModel/Config") {}
150
151 // =============================================================================
152 // Provider Options / Metadata
153 // =============================================================================
154
155 declare module "effect/ai/Prompt" {
156 /**
157 * OpenAI-specific options for system messages.
158 *
159 * @stability unstable
160 * @category models
161 * @since 4.0.0
162 */
163 export interface SystemMessageOptions extends ProviderOptions {
164 /**
165 * Provider-specific system message options for the OpenAI Responses API.
166 */
167 readonly openai?: {
168 /**
169 * Marks the system input text as the end of a reusable prompt prefix.
170 *
171 * Requires GPT-5.6 or later. OpenAI may reject requests that use this
172 * option with earlier models.
173 */
174 readonly promptCacheBreakpoint?: PromptCacheBreakpoint | null
175 } | null
176 }
177
178 /**
179 * OpenAI-specific options for file prompt parts.
180 *
181 * @stability unstable
182 * @category models
183 * @since 4.0.0
184 */
185 export interface FilePartOptions extends ProviderOptions {
186 /**
187 * Provider-specific file options for the OpenAI Responses API.
188 */
189 readonly openai?: {
190 /**
191 * The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
192 */
193 readonly imageDetail?: ImageDetail | null
194 /**
195 * Marks the input image or file as the end of a reusable prompt prefix.
196 *
197 * Requires GPT-5.6 or later. OpenAI may reject requests that use this
198 * option with earlier models.
199 */
200 readonly promptCacheBreakpoint?: PromptCacheBreakpoint | null
201 } | null
202 }
203
204 /**
205 * OpenAI-specific options for reasoning prompt parts.
206 *
207 * @stability unstable
208 * @category models
209 * @since 4.0.0
210 */
211 export interface ReasoningPartOptions extends ProviderOptions {
212 /**
213 * Provider-specific reasoning options for the OpenAI Responses API.
214 */
215 readonly openai?: {
216 /**
217 * The ID of the item to reference.
218 */
219 readonly itemId?: string | null
220 /**
221 * Encrypted reasoning returned by OpenAI for `store: false` or when
222 * `include` contains `reasoning.encrypted_content`.
223 */
224 readonly encryptedContent?: string | null
225 } | null
226 }
227
228 /**
229 * OpenAI-specific options for assistant tool-call prompt parts.
230 *
231 * @stability unstable
232 * @category models
233 * @since 4.0.0
234 */
235 export interface ToolCallPartOptions extends ProviderOptions {
236 /**
237 * Provider-specific tool-call options for the OpenAI Responses API.
238 */
239 readonly openai?: {
240 /**
241 * The ID of the item to reference.
242 */
243 readonly itemId?: string | null
244 /**
245 * The status of item.
246 */
247 readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
248 /**
249 * The ID of the approval request.
250 */
251 readonly approvalRequestId?: string | null
252 } | null
253 }
254
255 /**
256 * OpenAI-specific options for tool-result prompt parts.
257 *
258 * @stability unstable
259 * @category models
260 * @since 4.0.0
261 */
262 export interface ToolResultPartOptions extends ProviderOptions {
263 /**
264 * Provider-specific tool-result options for the OpenAI Responses API.
265 */
266 readonly openai?: {
267 /**
268 * The ID of the item to reference.
269 */
270 readonly itemId?: string | null
271 /**
272 * The status of item.
273 */
274 readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
275 /**
276 * The ID of the approval request.
277 */
278 readonly approvalId?: string | null
279 } | null
280 }
281
282 /**
283 * OpenAI-specific options for text prompt parts.
284 *
285 * @stability unstable
286 * @category models
287 * @since 4.0.0
288 */
289 export interface TextPartOptions extends ProviderOptions {
290 /**
291 * Provider-specific text options for the OpenAI Responses API.
292 */
293 readonly openai?: {
294 /**
295 * The ID of the item to reference.
296 */
297 readonly itemId?: string | null
298 /**
299 * The status of item.
300 */
301 readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
302 /**
303 * A list of annotations that apply to the output text.
304 */
305 readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null
306 /**
307 * Marks the input text as the end of a reusable prompt prefix.
308 *
309 * Requires GPT-5.6 or later. OpenAI may reject requests that use this
310 * option with earlier models.
311 */
312 readonly promptCacheBreakpoint?: PromptCacheBreakpoint | null
313 } | null
314 }
315 }
316
317 declare module "effect/ai/Response" {
318 /**
319 * OpenAI metadata attached to a complete text response part.
320 *
321 * @stability unstable
322 * @category models
323 * @since 4.0.0
324 */
325 export interface TextPartMetadata extends ProviderMetadata {
326 /**
327 * Provider-specific metadata returned for the text part.
328 */
329 readonly openai?: {
330 /**
331 * The OpenAI item ID associated with the text part.
332 */
333 readonly itemId?: string | null
334 /**
335 * If the model emits a refusal content part, the refusal explanation
336 * from the model will be contained in the metadata of an empty text
337 * part.
338 */
339 readonly refusal?: string | null
340 /**
341 * The status of item.
342 */
343 readonly status?: typeof OpenAiSchema.MessageStatus.Encoded | null
344 /**
345 * The text content part annotations.
346 */
347 readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null
348 }
349 }
350
351 /**
352 * OpenAI metadata emitted when a streamed text part starts.
353 *
354 * @stability unstable
355 * @category models
356 * @since 4.0.0
357 */
358 export interface TextStartPartMetadata extends ProviderMetadata {
359 /**
360 * Provider-specific metadata returned for the streamed text start.
361 */
362 readonly openai?: {
363 /**
364 * The OpenAI item ID associated with the streamed text part.
365 */
366 readonly itemId?: string | null
367 } | null
368 }
369
370 /**
371 * OpenAI metadata emitted when a streamed text part ends.
372 *
373 * @stability unstable
374 * @category models
375 * @since 4.0.0
376 */
377 export interface TextEndPartMetadata extends ProviderMetadata {
378 /**
379 * Provider-specific metadata returned for the streamed text end.
380 */
381 readonly openai?: {
382 /**
383 * The OpenAI item ID associated with the streamed text part.
384 */
385 readonly itemId?: string | null
386 /**
387 * The annotations collected for the completed streamed text part.
388 */
389 readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null
390 } | null
391 }
392
393 /**
394 * OpenAI metadata attached to a complete reasoning response part.
395 *
396 * @stability unstable
397 * @category models
398 * @since 4.0.0
399 */
400 export interface ReasoningPartMetadata extends ProviderMetadata {
401 /**
402 * Provider-specific metadata returned for the reasoning part.
403 */
404 readonly openai?: {
405 /**
406 * The OpenAI item ID associated with the reasoning part.
407 */
408 readonly itemId?: string | null
409 /**
410 * Encrypted reasoning content that can be sent back in later requests.
411 */
412 readonly encryptedContent?: string | null
413 } | null
414 }
415
416 /**
417 * OpenAI metadata emitted when a streamed reasoning part starts.
418 *
419 * @stability unstable
420 * @category models
421 * @since 4.0.0
422 */
423 export interface ReasoningStartPartMetadata extends ProviderMetadata {
424 /**
425 * Provider-specific metadata returned for the streamed reasoning start.
426 */
427 readonly openai?: {
428 /**
429 * The OpenAI item ID associated with the reasoning part.
430 */
431 readonly itemId?: string | null
432 /**
433 * Encrypted reasoning content that can be sent back in later requests.
434 */
435 readonly encryptedContent?: string | null
436 } | null
437 }
438
439 /**
440 * OpenAI metadata emitted for a streamed reasoning delta.
441 *
442 * @stability unstable
443 * @category models
444 * @since 4.0.0
445 */
446 export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
447 /**
448 * Provider-specific metadata returned for the streamed reasoning delta.
449 */
450 readonly openai?: {
451 /**
452 * The OpenAI item ID associated with the reasoning part.
453 */
454 readonly itemId?: string | null
455 } | null
456 }
457
458 /**
459 * OpenAI metadata emitted when a streamed reasoning part ends.
460 *
461 * @stability unstable
462 * @category models
463 * @since 4.0.0
464 */
465 export interface ReasoningEndPartMetadata extends ProviderMetadata {
466 /**
467 * Provider-specific metadata returned for the streamed reasoning end.
468 */
469 readonly openai?: {
470 /**
471 * The OpenAI item ID associated with the reasoning part.
472 */
473 readonly itemId?: string | null
474 /**
475 * Encrypted reasoning content that can be sent back in later requests.
476 */
477 readonly encryptedContent?: string
478 } | null
479 }
480
481 /**
482 * OpenAI metadata attached to tool-call response parts.
483 *
484 * @stability unstable
485 * @category models
486 * @since 4.0.0
487 */
488 export interface ToolCallPartMetadata extends ProviderMetadata {
489 /**
490 * Provider-specific metadata returned for the tool call.
491 */
492 readonly openai?: {
493 /**
494 * The OpenAI item ID associated with the tool call.
495 */
496 readonly itemId?: string | null
497 } | null
498 }
499
500 /**
501 * OpenAI metadata attached to document source citations.
502 *
503 * @stability unstable
504 * @category models
505 * @since 4.0.0
506 */
507 export interface DocumentSourcePartMetadata extends ProviderMetadata {
508 /**
509 * Provider-specific citation metadata for the OpenAI Responses API.
510 */
511 readonly openai?:
512 | {
513 /**
514 * Identifies a citation to an uploaded file.
515 */
516 readonly type: "file_citation"
517 /**
518 * The index of the file in the list of files.
519 */
520 readonly index: number
521 /**
522 * The ID of the file.
523 */
524 readonly fileId: string
525 }
526 | {
527 /**
528 * Identifies a citation to a generated file path.
529 */
530 readonly type: "file_path"
531 /**
532 * The index of the file in the list of files.
533 */
534 readonly index: number
535 /**
536 * The ID of the file.
537 */
538 readonly fileId: string
539 }
540 | {
541 /**
542 * Identifies a citation to a file inside a container.
543 */
544 readonly type: "container_file_citation"
545 /**
546 * The ID of the file.
547 */
548 readonly fileId: string
549 /**
550 * The ID of the container file.
551 */
552 readonly containerId: string
553 }
554 | null
555 }
556
557 /**
558 * OpenAI metadata attached to URL source citations.
559 *
560 * @stability unstable
561 * @category models
562 * @since 4.0.0
563 */
564 export interface UrlSourcePartMetadata extends ProviderMetadata {
565 /**
566 * Provider-specific URL citation metadata for the OpenAI Responses API.
567 */
568 readonly openai?: {
569 /**
570 * Identifies a citation to a URL.
571 */
572 readonly type: "url_citation"
573 /**
574 * The index of the first character of the URL citation in the message.
575 */
576 readonly startIndex: number
577 /**
578 * The index of the last character of the URL citation in the message.
579 */
580 readonly endIndex: number
581 } | null
582 }
583
584 /**
585 * OpenAI metadata attached to finish response parts.
586 *
587 * @stability unstable
588 * @category models
589 * @since 4.0.0
590 */
591 export interface FinishPartMetadata extends ProviderMetadata {
592 /**
593 * Provider-specific metadata returned when generation finishes.
594 */
595 readonly openai?: {
596 /**
597 * The service tier reported by OpenAI for the response.
598 */
599 readonly serviceTier?: "default" | "auto" | "flex" | "scale" | "priority" | "ultrafast" | null
600 /**
601 * Prompt cache diagnostics for `prompt_cache_options.comparison_response_id`.
602 */
603 readonly promptCacheDiagnostics?: OpenAiSchema.PromptCacheDiagnostics
604 } | null
605 }
606 }
607
608 // =============================================================================
609 // Language Model
610 // =============================================================================
611
612 /**
613 * Creates an OpenAI model descriptor that can be provided with
614 * `Effect.provide`.
615 *
616 * **When to use**
617 *
618 * Use when you want an OpenAI language model value that carries provider and
619 * model metadata and can be supplied directly to an Effect program.
620 *
621 * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
622 * @see {@link make} for constructing the language model service effectfully
623 *
624 * @stability unstable
625 * @category constructors
626 * @since 4.0.0
627 */
628 export const model = (
629 model: (string & {}) | Model,
630 config?: Omit<typeof Config.Service, "model">
631 ): AiModel.Model<"openai", LanguageModel.LanguageModel, OpenAiClient> =>
632 AiModel.make("openai", model, layer({ model, config }))
633
634 // TODO
635 // /**
636 // * @since 4.0.0
637 // * @category constructors
638 // */
639 // export const modelWithTokenizer = (
640 // model: (string & {}) | Model,
641 // config?: Omit<typeof Config.Service, "model">
642 // ): AiModel.Model<"openai", LanguageModel.LanguageModel | Tokenizer.Tokenizer, OpenAiClient> =>
643 // AiModel.make("openai", model, layerWithTokenizer({ model, config }))
644
645 /**
646 * Creates an OpenAI `LanguageModel` service from a model identifier and
647 * optional request defaults.
648 *
649 * **When to use**
650 *
651 * Use to construct an OpenAI Responses API language model service backed by
652 * `OpenAiClient`.
653 *
654 * **Details**
655 *
656 * The returned effect requires `OpenAiClient`. Request defaults from the
657 * `config` option are merged with any `Config` service in the context, with
658 * context values taking precedence. The service supports both `generateText`
659 * and `streamText`.
660 *
661 * @see {@link layer} for providing the service as a `Layer`
662 * @see {@link model} for creating a model descriptor for `Effect.provide`
663 *
664 * @stability unstable
665 * @category constructors
666 * @since 4.0.0
667 */
668 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
669 readonly model: (string & {}) | Model
670 readonly config?: Omit<typeof Config.Service, "model"> | undefined
671 }): Effect.fn.Return<LanguageModel.LanguageModel, never, OpenAiClient> {
672 const client = yield* OpenAiClient
673
674 const makeConfig = Effect.gen(function*() {
675 const services = yield* Effect.context<never>()
676 return { model, ...providerConfig, ...Context.getOrUndefined(services, Config) }
677 })
678
679 const makeRequest = Effect.fnUntraced(
680 function*<Tools extends ReadonlyArray<Tool.Any>>({ config, options, toolNameMapper }: {
681 readonly config: typeof Config.Service
682 readonly options: LanguageModel.ProviderOptions
683 readonly toolNameMapper: Tool.NameMapper<Tools>
684 }): Effect.fn.Return<typeof OpenAiSchema.CreateResponse.Encoded, AiError.AiError> {
685 const include = new Set<typeof OpenAiSchema.IncludeEnum.Encoded>(config.include)
686 const messages = yield* prepareMessages({
687 config,
688 options,
689 isReasoningModel: resolveReasoningModel(config),
690 include,
691 toolNameMapper
692 })
693 const { toolChoice, tools } = yield* prepareTools({
694 config,
695 options,
696 toolNameMapper
697 })
698 const responseFormat = yield* prepareResponseFormat({
699 config,
700 options
701 })
702 const {
703 fileIdPrefixes: _fip,
704 strictJsonSchema: _sjs,
705 useItemReferences: _uir,
706 reasoningModel: _rm,
707 ...apiConfig
708 } = config
709 const request: Mutable<typeof OpenAiSchema.CreateResponse.Encoded> = {
710 ...apiConfig,
711 input: messages,
712 include: include.size > 0 ? Array.from(include) : undefined,
713 text: {
714 verbosity: config.text?.verbosity ?? undefined,
715 format: responseFormat
716 }
717 }
718 if (tools) request.tools = tools
719 if (toolChoice) request.tool_choice = toolChoice
720 if (options.previousResponseId) request.previous_response_id = options.previousResponseId
721 return request
722 }
723 )
724
725 return yield* LanguageModel.make({
726 codecTransformer: toCodecOpenAI,
727 generateText: Effect.fnUntraced(
728 function*(options) {
729 const config = yield* makeConfig
730 const toolNameMapper = new Tool.NameMapper(options.tools)
731 const request = yield* makeRequest({ config, options, toolNameMapper })
732 annotateRequest(options.span, request)
733 const [rawResponse, response] = yield* client.createResponse(request)
734 annotateResponse(options.span, rawResponse)
735 return yield* makeResponse({
736 options,
737 rawResponse,
738 response,
739 toolNameMapper
740 })
741 }
742 ),
743 streamText: Effect.fnUntraced(
744 function*(options) {
745 const config = yield* makeConfig
746 const toolNameMapper = new Tool.NameMapper(options.tools)
747 const request = yield* makeRequest({ config, options, toolNameMapper })
748 annotateRequest(options.span, request)
749 const [response, stream] = yield* client.createResponseStream(request)
750 return yield* makeStreamResponse({
751 stream,
752 response,
753 config,
754 options,
755 toolNameMapper
756 })
757 },
758 (effect, options) =>
759 effect.pipe(
760 Stream.unwrap,
761 Stream.map((response) => {
762 annotateStreamResponse(options.span, response)
763 return response
764 })
765 )
766 )
767 })
768 })
769
770 /**
771 * Creates a layer that provides the OpenAI `LanguageModel.LanguageModel`
772 * service.
773 *
774 * **When to use**
775 *
776 * Use when composing application layers and you want OpenAI to satisfy
777 * `LanguageModel.LanguageModel` while supplying `OpenAiClient` from another
778 * layer.
779 *
780 * **Details**
781 *
782 * The `config` option supplies request defaults for the selected model. Scoped
783 * values from `withConfigOverride` are merged when each request is built and
784 * take precedence over these defaults.
785 *
786 * @see {@link make} for constructing the language model service effectfully
787 * @see {@link model} for creating a model descriptor for `Effect.provide`
788 * @see {@link withConfigOverride} for scoped request configuration overrides
789 *
790 * @stability unstable
791 * @category layers
792 * @since 4.0.0
793 */
794 export const layer = (options: {
795 readonly model: (string & {}) | Model
796 readonly config?: Omit<typeof Config.Service, "model"> | undefined
797 }): Layer.Layer<LanguageModel.LanguageModel, never, OpenAiClient> =>
798 Layer.effect(LanguageModel.LanguageModel, make(options))
799
800 /**
801 * Provides scoped config overrides for OpenAI language model operations.
802 *
803 * **When to use**
804 *
805 * Use to apply OpenAI Responses API config overrides around one or more
806 * language model operations without changing the defaults passed to `model`,
807 * `make`, or `layer`.
808 *
809 * **Details**
810 *
811 * The override is dual, so it can be used in pipe form or as
812 * `withConfigOverride(effect, overrides)`. Overrides are merged with any
813 * existing `Config` service in the current context, and the override values take
814 * precedence.
815 *
816 * @see {@link Config} for the scoped configuration service consumed by this function
817 *
818 * @stability unstable
819 * @category configuration
820 * @since 4.0.0
821 */
822 export const withConfigOverride: {
823 (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
824 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
825 } = dual<
826 (
827 overrides: typeof Config.Service
828 ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
829 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
830 >(2, (self, overrides) =>
831 Effect.flatMap(
832 Effect.serviceOption(Config),
833 (config) =>
834 Effect.provideService(self, Config, {
835 ...(config._tag === "Some" ? config.value : {}),
836 ...overrides
837 })
838 ))
839
840 // =============================================================================
841 // Prompt Conversion
842 // =============================================================================
843
844 const prepareMessages = Effect.fnUntraced(
845 function*<Tools extends ReadonlyArray<Tool.Any>>({
846 config,
847 options,
848 isReasoningModel,
849 include,
850 toolNameMapper
851 }: {
852 readonly config: typeof Config.Service
853 readonly options: LanguageModel.ProviderOptions
854 readonly include: Set<typeof OpenAiSchema.IncludeEnum.Encoded>
855 readonly isReasoningModel: boolean
856 readonly toolNameMapper: Tool.NameMapper<Tools>
857 }): Effect.fn.Return<ReadonlyArray<typeof OpenAiSchema.InputItem.Encoded>, AiError.AiError> {
858 const processedApprovalIds = new Set<string>()
859 const websocketMode = Option.isSome(yield* Effect.serviceOption(OpenAiSocket))
860
861 const hasConversation = Predicate.isNotNullish(config.conversation)
862 const useItemReferences = config.store === true &&
863 config.useItemReferences !== false &&
864 options.incrementalFallback !== true
865
866 // Provider-Defined Tools
867 const applyPatchTool = options.tools.find((tool): tool is ReturnType<typeof OpenAiTool.ApplyPatch> =>
868 Tool.isProviderDefined(tool) && tool.name === "OpenAiApplyPatch"
869 )
870 const codeInterpreterTool = options.tools.find((tool): tool is ReturnType<typeof OpenAiTool.CodeInterpreter> =>
871 Tool.isProviderDefined(tool) && tool.name === "OpenAiCodeInterpreter"
872 )
873 const shellTool = options.tools.find((tool): tool is ReturnType<typeof OpenAiTool.Shell> =>
874 Tool.isProviderDefined(tool) && tool.name === "OpenAiShell"
875 )
876 const localShellTool = options.tools.find((tool): tool is ReturnType<typeof OpenAiTool.LocalShell> =>
877 Tool.isProviderDefined(tool) && tool.name === "OpenAiLocalShell"
878 )
879 const webSearchTool = options.tools.find((tool): tool is ReturnType<typeof OpenAiTool.WebSearch> =>
880 Tool.isProviderDefined(tool) && tool.name === "OpenAiWebSearch"
881 )
882 const webSearchPreviewTool = options.tools.find((tool): tool is ReturnType<typeof OpenAiTool.WebSearchPreview> =>
883 Tool.isProviderDefined(tool) && tool.name === "OpenAiWebSearchPreview"
884 )
885
886 // Handle Included Features
887 if (Predicate.isNotUndefined(config.top_logprobs)) {
888 include.add("message.output_text.logprobs")
889 }
890 if ((websocketMode || !useItemReferences) && isReasoningModel) {
891 include.add("reasoning.encrypted_content")
892 }
893 if (codeInterpreterTool) {
894 include.add("code_interpreter_call.outputs")
895 }
896 if (webSearchTool || webSearchPreviewTool) {
897 include.add("web_search_call.action.sources")
898 }
899
900 const messages: Array<typeof OpenAiSchema.InputItem.Encoded> = []
901 const prompt = options.incrementalPrompt ?? options.prompt
902
903 for (const message of prompt.content) {
904 switch (message.role) {
905 case "system": {
906 messages.push({
907 role: isReasoningModel ? "developer" : "system",
908 content: [{
909 type: "input_text",
910 text: message.content,
911 ...getPromptCacheBreakpoint(message)
912 }]
913 })
914 break
915 }
916
917 case "user": {
918 const content: Array<typeof OpenAiSchema.InputContent.Encoded> = []
919
920 for (let index = 0; index < message.content.length; index++) {
921 const part = message.content[index]
922
923 switch (part.type) {
924 case "text": {
925 content.push({
926 type: "input_text",
927 text: part.text,
928 ...getPromptCacheBreakpoint(part)
929 })
930 break
931 }
932
933 case "file": {
934 content.push(yield* prepareFilePart(part, index, config))
935 break
936 }
937 }
938 }
939
940 messages.push({ role: "user", content })
941
942 break
943 }
944
945 case "assistant": {
946 const reasoningMessages: Record<string, DeepMutable<typeof OpenAiSchema.ReasoningItem.Encoded>> = Object
947 .create(null)
948
949 const providerExecutedParts = message.content.filter((part) =>
950 (part.type === "tool-call" || part.type === "tool-result") && part.providerExecuted
951 )
952 const unreplayableProviderItem = (name: string, id: string) =>
953 AiError.make({
954 module: "OpenAiLanguageModel",
955 method: "prepareMessages",
956 reason: new AiError.InvalidRequestError({
957 description: `Cannot replay provider-executed tool item '${name}' ('${id}') losslessly`
958 })
959 })
960
961 for (const part of message.content) {
962 switch (part.type) {
963 case "text": {
964 const id = getItemId(part)
965
966 // When in conversation mode, skip items that already exist in the
967 // conversation context to avoid "Duplicate item found" errors
968 if (hasConversation && Predicate.isNotNull(id)) {
969 break
970 }
971
972 if (useItemReferences && Predicate.isNotNull(id)) {
973 messages.push({ type: "item_reference", id })
974 break
975 }
976
977 messages.push({
978 id: id!,
979 type: "message",
980 role: "assistant",
981 status: part.options.openai?.status ?? "completed",
982 content: [{
983 type: "output_text",
984 text: part.text,
985 annotations: part.options.openai?.annotations ?? [],
986 logprobs: []
987 }]
988 })
989
990 break
991 }
992
993 case "reasoning": {
994 const id = getItemId(part)
995 const encryptedContent = getEncryptedContent(part)
996
997 if (hasConversation && Predicate.isNotNull(id)) {
998 break
999 }
1000
1001 if (Predicate.isNotNull(id)) {
1002 const message = reasoningMessages[id]
1003
1004 if (useItemReferences) {
1005 // Use item references to refer to reasoning (single reference)
1006 // when the first part is encountered
1007 if (Predicate.isUndefined(message)) {
1008 messages.push({ type: "item_reference", id })
1009
1010 // Store unused reasoning message to mark its id as used
1011 reasoningMessages[id] = {
1012 type: "reasoning",
1013 id,
1014 summary: []
1015 }
1016 }
1017 } else {
1018 const summaryParts: Array<typeof OpenAiSchema.SummaryTextContent.Encoded> = []
1019
1020 if (part.text.length > 0) {
1021 summaryParts.push({ type: "summary_text", text: part.text })
1022 }
1023
1024 if (Predicate.isUndefined(message)) {
1025 reasoningMessages[id] = {
1026 type: "reasoning",
1027 id,
1028 summary: summaryParts,
1029 ...(Predicate.isNotNull(encryptedContent)
1030 ? { encrypted_content: encryptedContent }
1031 : undefined)
1032 }
1033
1034 messages.push(reasoningMessages[id])
1035 } else {
1036 message.summary.push(...summaryParts)
1037
1038 // Update encrypted content to enable setting it in the
1039 // last summary part
1040 if (Predicate.isNotNull(encryptedContent)) {
1041 message.encrypted_content = encryptedContent
1042 }
1043 }
1044 }
1045 }
1046
1047 break
1048 }
1049
1050 case "tool-call": {
1051 const id = getItemId(part)
1052 const status = getStatus(part)
1053
1054 if (hasConversation && Predicate.isNotNull(id)) {
1055 break
1056 }
1057
1058 if (useItemReferences && Predicate.isNotNull(id)) {
1059 messages.push({ type: "item_reference", id })
1060 break
1061 }
1062
1063 if (part.providerExecuted) {
1064 if (
1065 config.store !== true && options.incrementalFallback !== true
1066 ) {
1067 break
1068 }
1069 const result = providerExecutedParts.find((candidate) =>
1070 candidate.type === "tool-result" && candidate.id === part.id && candidate.name === part.name
1071 )
1072 if (Predicate.isUndefined(result) || result.type !== "tool-result") {
1073 return yield* unreplayableProviderItem(part.name, part.id)
1074 }
1075 if (
1076 Predicate.hasProperty(result.result, "type") &&
1077 result.result.type === "execution-denied"
1078 ) {
1079 break
1080 }
1081
1082 const itemId = getItemId(part) ?? getItemId(result) ?? part.id
1083 switch (part.name) {
1084 case "OpenAiWebSearch":
1085 case "OpenAiWebSearchPreview": {
1086 if (!Predicate.hasProperty(result.result, "status")) {
1087 return yield* unreplayableProviderItem(part.name, part.id)
1088 }
1089 messages.push({
1090 type: "web_search_call",
1091 id: itemId,
1092 ...(Predicate.hasProperty(result.result, "action")
1093 ? { action: result.result.action }
1094 : undefined),
1095 status: result.result.status as string
1096 })
1097 break
1098 }
1099 case "OpenAiCodeInterpreter": {
1100 if (
1101 !Predicate.hasProperty(part.params, "code") ||
1102 !Predicate.hasProperty(part.params, "container_id") ||
1103 !Predicate.hasProperty(result.result, "status") ||
1104 !Predicate.hasProperty(result.result, "outputs")
1105 ) {
1106 return yield* unreplayableProviderItem(part.name, part.id)
1107 }
1108 messages.push({
1109 type: "code_interpreter_call",
1110 id: itemId,
1111 code: part.params.code as string | null,
1112 container_id: part.params.container_id as string,
1113 status: result.result.status as any,
1114 outputs: result.result.outputs as any
1115 })
1116 break
1117 }
1118 case "OpenAiFileSearch": {
1119 if (
1120 !Predicate.hasProperty(result.result, "status") ||
1121 !Predicate.hasProperty(result.result, "queries") ||
1122 !Predicate.hasProperty(result.result, "results")
1123 ) {
1124 return yield* unreplayableProviderItem(part.name, part.id)
1125 }
1126 messages.push({
1127 type: "file_search_call",
1128 id: itemId,
1129 status: result.result.status as string,
1130 queries: result.result.queries as Array<string>,
1131 results: result.result.results
1132 })
1133 break
1134 }
1135 case "OpenAiImageGeneration": {
1136 if (!Predicate.hasProperty(result.result, "result")) {
1137 return yield* unreplayableProviderItem(part.name, part.id)
1138 }
1139 messages.push({
1140 type: "image_generation_call",
1141 id: itemId,
1142 result: result.result.result as string | null,
1143 status: (Predicate.hasProperty(result.result, "status")
1144 ? result.result.status
1145 : "completed") as any
1146 })
1147 break
1148 }
1149 default: {
1150 return yield* unreplayableProviderItem(part.name, part.id)
1151 }
1152 }
1153 break
1154 }
1155
1156 const toolName = toolNameMapper.getProviderName(part.name)
1157
1158 if (Predicate.isNotUndefined(localShellTool) && toolName === "local_shell") {
1159 const params = yield* Schema.decodeUnknownEffect(localShellTool.parametersSchema)(part.params).pipe(
1160 Effect.mapError((error) =>
1161 AiError.make({
1162 module: "OpenAiLanguageModel",
1163 method: "prepareMessages",
1164 reason: new AiError.ToolParameterValidationError({
1165 toolName: "local_shell",
1166 description: error.message
1167 })
1168 })
1169 )
1170 )
1171
1172 messages.push({
1173 id: id!,
1174 type: "local_shell_call",
1175 call_id: part.id,
1176 status: status ?? "completed",
1177 action: params.action
1178 })
1179
1180 break
1181 }
1182
1183 if (Predicate.isNotUndefined(shellTool) && toolName === "shell") {
1184 const params = yield* Schema.decodeUnknownEffect(shellTool.parametersSchema)(part.params).pipe(
1185 Effect.mapError((error) =>
1186 AiError.make({
1187 module: "OpenAiLanguageModel",
1188 method: "prepareMessages",
1189 reason: new AiError.ToolParameterValidationError({
1190 toolName: "shell",
1191 description: error.message
1192 })
1193 })
1194 )
1195 )
1196
1197 messages.push({
1198 id: id!,
1199 type: "shell_call",
1200 call_id: part.id,
1201 status: status ?? "completed",
1202 action: params.action
1203 })
1204
1205 break
1206 }
1207
1208 messages.push({
1209 type: "function_call",
1210 name: toolName,
1211 call_id: part.id,
1212 arguments: JSON.stringify(part.params),
1213 ...(Predicate.isNotNull(id) ? { id } : {}),
1214 ...(Predicate.isNotNull(status) ? { status } : {})
1215 })
1216
1217 break
1218 }
1219
1220 // Assistant tool-result parts are always provider executed
1221 case "tool-result": {
1222 // Skip execution denied results - these have no corresponding
1223 // item in OpenAI's store
1224 if (
1225 Predicate.hasProperty(part.result, "type") &&
1226 part.result.type === "execution-denied"
1227 ) {
1228 break
1229 }
1230
1231 if (hasConversation) {
1232 break
1233 }
1234
1235 if (useItemReferences) {
1236 const id = getItemId(part) ?? part.id
1237 messages.push({ type: "item_reference", id })
1238 } else if (
1239 part.providerExecuted &&
1240 (config.store === true || options.incrementalFallback === true)
1241 ) {
1242 const call = providerExecutedParts.find((candidate) =>
1243 candidate.type === "tool-call" && candidate.id === part.id && candidate.name === part.name
1244 )
1245 if (Predicate.isUndefined(call)) {
1246 return yield* unreplayableProviderItem(part.name, part.id)
1247 }
1248 }
1249 }
1250 }
1251 }
1252
1253 break
1254 }
1255
1256 case "tool": {
1257 for (const part of message.content) {
1258 if (part.type === "tool-approval-response") {
1259 if (processedApprovalIds.has(part.approvalId)) {
1260 continue
1261 }
1262
1263 processedApprovalIds.add(part.approvalId)
1264
1265 if (useItemReferences) {
1266 messages.push({ type: "item_reference", id: part.approvalId })
1267 }
1268
1269 messages.push({
1270 type: "mcp_approval_response",
1271 approval_request_id: part.approvalId,
1272 approve: part.approved
1273 } as any)
1274
1275 continue
1276 }
1277
1278 // Skip execution-denied results that already have an approvalId -
1279 // this indicates that the part was already handled via tool-approval-response
1280 if (
1281 Predicate.hasProperty(part.result, "type") &&
1282 part.result.type === "execution-denied"
1283 ) {
1284 if (Predicate.isNotNullish(part.options.openai?.approvalId)) {
1285 continue
1286 }
1287 }
1288
1289 const id = getItemId(part) ?? part.id
1290 const status = getStatus(part)
1291 const toolName = toolNameMapper.getProviderName(part.name)
1292
1293 if (Predicate.isNotUndefined(applyPatchTool) && toolName === "apply_patch") {
1294 messages.push({
1295 id,
1296 type: "apply_patch_call_output",
1297 call_id: part.id,
1298 ...(part.result as any)
1299 })
1300 continue
1301 }
1302
1303 if (Predicate.isNotUndefined(shellTool) && toolName === "shell") {
1304 messages.push({
1305 id,
1306 type: "shell_call_output",
1307 call_id: part.id,
1308 output: part.result as any,
1309 ...(Predicate.isNotNull(status) ? { status } : {})
1310 })
1311 continue
1312 }
1313
1314 if (Predicate.isNotUndefined(localShellTool) && toolName === "local_shell") {
1315 messages.push({
1316 id,
1317 type: "local_shell_call_output",
1318 call_id: part.id,
1319 output: part.result as any,
1320 ...(Predicate.isNotNull(status) ? { status } : {})
1321 })
1322 continue
1323 }
1324
1325 messages.push({
1326 type: "function_call_output",
1327 call_id: part.id,
1328 output: Predicate.isUndefined(part.modelOutput)
1329 ? typeof part.result === "string" ? part.result : JSON.stringify(part.result)
1330 : yield* prepareToolResultOutput(part.modelOutput, config),
1331 ...(Predicate.isNotNull(status) ? { status } : {})
1332 })
1333 }
1334
1335 break
1336 }
1337 }
1338 }
1339
1340 return messages
1341 }
1342 )
1343
1344 // =============================================================================
1345 // HTTP Details
1346 // =============================================================================
1347
1348 const buildHttpResponseDetails = (
1349 response: HttpClientResponse.HttpClientResponse
1350 ): typeof Response.HttpResponseDetails.Type => ({
1351 status: response.status,
1352 headers: Redactable.redact(response.headers) as Record<string, string>
1353 })
1354
1355 // =============================================================================
1356 // Response Conversion
1357 // =============================================================================
1358
1359 type ResponseStreamEvent = typeof OpenAiSchema.ResponseStreamEvent.Type
1360
1361 type KnownResponseStreamEventType =
1362 | "response.created"
1363 | "response.completed"
1364 | "response.incomplete"
1365 | "response.failed"
1366 | "response.output_item.added"
1367 | "response.output_item.done"
1368 | "response.output_text.delta"
1369 | "response.output_text.annotation.added"
1370 | "response.reasoning_summary_part.added"
1371 | "response.reasoning_summary_part.done"
1372 | "response.reasoning_summary_text.delta"
1373 | "response.function_call_arguments.delta"
1374 | "response.function_call_arguments.done"
1375 | "response.code_interpreter_call_code.delta"
1376 | "response.code_interpreter_call_code.done"
1377 | "response.apply_patch_call_operation_diff.delta"
1378 | "response.apply_patch_call_operation_diff.done"
1379 | "response.image_generation_call.partial_image"
1380 | "error"
1381
1382 type KnownResponseStreamEvent = Extract<ResponseStreamEvent, { readonly type: KnownResponseStreamEventType }>
1383
1384 const knownResponseStreamEventTypes = new Set<KnownResponseStreamEventType>([
1385 "response.created",
1386 "response.completed",
1387 "response.incomplete",
1388 "response.failed",
1389 "response.output_item.added",
1390 "response.output_item.done",
1391 "response.output_text.delta",
1392 "response.output_text.annotation.added",
1393 "response.reasoning_summary_part.added",
1394 "response.reasoning_summary_part.done",
1395 "response.reasoning_summary_text.delta",
1396 "response.function_call_arguments.delta",
1397 "response.function_call_arguments.done",
1398 "response.code_interpreter_call_code.delta",
1399 "response.code_interpreter_call_code.done",
1400 "response.apply_patch_call_operation_diff.delta",
1401 "response.apply_patch_call_operation_diff.done",
1402 "response.image_generation_call.partial_image",
1403 "error"
1404 ])
1405
1406 const isKnownResponseStreamEvent = (
1407 event: ResponseStreamEvent
1408 ): event is KnownResponseStreamEvent => knownResponseStreamEventTypes.has(event.type as KnownResponseStreamEventType)
1409
1410 const makeResponse = Effect.fnUntraced(
1411 function*<Tools extends ReadonlyArray<Tool.Any>>({
1412 options,
1413 rawResponse,
1414 response,
1415 toolNameMapper
1416 }: {
1417 readonly options: LanguageModel.ProviderOptions
1418 readonly rawResponse: OpenAiSchema.Response
1419 readonly response: HttpClientResponse.HttpClientResponse
1420 readonly toolNameMapper: Tool.NameMapper<Tools>
1421 }): Effect.fn.Return<
1422 Array<Response.PartEncoded>,
1423 AiError.AiError,
1424 IdGenerator.IdGenerator
1425 > {
1426 const idGenerator = yield* IdGenerator.IdGenerator
1427
1428 const approvalRequests = getApprovalRequestIdMapping(options.prompt)
1429
1430 const webSearchTool = options.tools.find((tool) =>
1431 Tool.isProviderDefined(tool) &&
1432 (tool.name === "OpenAiWebSearch" ||
1433 tool.name === "OpenAiWebSearchPreview")
1434 ) as Tool.AnyProviderDefined | undefined
1435
1436 let hasToolCalls = false
1437 const parts: Array<Response.PartEncoded> = []
1438
1439 const createdAt = new Date(rawResponse.created_at * 1000)
1440 parts.push({
1441 type: "response-metadata",
1442 id: rawResponse.id,
1443 modelId: rawResponse.model as string,
1444 timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(createdAt))
1445 })
1446
1447 for (const part of rawResponse.output) {
1448 switch (part.type) {
1449 case "apply_patch_call": {
1450 const toolName = toolNameMapper.getCustomName("apply_patch")
1451 parts.push({
1452 type: "tool-call",
1453 id: part.call_id,
1454 name: toolName,
1455 params: { call_id: part.call_id, operation: part.operation },
1456 metadata: { openai: makeItemIdMetadata(part.id) }
1457 })
1458 break
1459 }
1460
1461 case "code_interpreter_call": {
1462 const toolName = toolNameMapper.getCustomName("code_interpreter")
1463 const status = part.status ?? "completed"
1464 parts.push({
1465 type: "tool-call",
1466 id: part.id,
1467 name: toolName,
1468 params: { code: part.code ?? null, container_id: part.container_id },
1469 providerExecuted: true
1470 })
1471 parts.push({
1472 type: "tool-result",
1473 id: part.id,
1474 name: toolName,
1475 isFailure: status !== "completed",
1476 result: { status, outputs: part.outputs ?? null },
1477 providerExecuted: true
1478 })
1479 break
1480 }
1481
1482 case "file_search_call": {
1483 const toolName = toolNameMapper.getCustomName("file_search")
1484 parts.push({
1485 type: "tool-call",
1486 id: part.id,
1487 name: toolName,
1488 params: {},
1489 providerExecuted: true
1490 })
1491 parts.push({
1492 type: "tool-result",
1493 id: part.id,
1494 name: toolName,
1495 isFailure: part.status !== "completed",
1496 result: {
1497 status: part.status,
1498 queries: part.queries,
1499 results: part.results ?? null
1500 },
1501 providerExecuted: true
1502 })
1503 break
1504 }
1505
1506 case "function_call": {
1507 hasToolCalls = true
1508
1509 const toolName = part.name
1510
1511 const toolParams = yield* Effect.try({
1512 try: () => Tool.unsafeSecureJsonParse(part.arguments),
1513 catch: (cause) =>
1514 AiError.make({
1515 module: "OpenAiLanguageModel",
1516 method: "makeResponse",
1517 reason: new AiError.ToolParameterValidationError({
1518 toolName,
1519 description: `Faled to securely JSON parse tool parameters: ${cause}`
1520 })
1521 })
1522 })
1523
1524 const params = yield* transformToolCallParams(options, part.name, toolParams)
1525
1526 parts.push({
1527 type: "tool-call",
1528 id: part.call_id,
1529 name: toolName,
1530 params,
1531 metadata: { openai: makeItemIdMetadata(part.id) }
1532 })
1533 break
1534 }
1535
1536 case "image_generation_call": {
1537 const toolName = toolNameMapper.getCustomName("image_generation")
1538 const status = part.status ?? "completed"
1539 parts.push({
1540 type: "tool-call",
1541 id: part.id,
1542 name: toolName,
1543 params: {},
1544 providerExecuted: true
1545 })
1546 parts.push({
1547 type: "tool-result",
1548 id: part.id,
1549 name: toolName,
1550 isFailure: status !== "completed",
1551 result: status === "completed"
1552 ? { result: part.result }
1553 : { status, result: part.result }
1554 })
1555 break
1556 }
1557
1558 case "local_shell_call": {
1559 const toolName = toolNameMapper.getCustomName("local_shell")
1560 parts.push({
1561 type: "tool-call",
1562 id: part.call_id,
1563 name: toolName,
1564 params: { action: part.action },
1565 metadata: { openai: makeItemIdMetadata(part.id) }
1566 })
1567 break
1568 }
1569
1570 case "mcp_call": {
1571 const toolId = Predicate.isNotNullish(part.approval_request_id)
1572 ? (approvalRequests.get(part.approval_request_id) ?? part.id)
1573 : part.id
1574
1575 const { toolName, params } = yield* normalizeMcpToolCall({
1576 toolNameMapper,
1577 toolParams: part.arguments,
1578 method: "makeResponse"
1579 })
1580
1581 parts.push({
1582 type: "tool-call",
1583 id: toolId,
1584 name: toolName,
1585 params,
1586 providerExecuted: true
1587 })
1588
1589 parts.push({
1590 type: "tool-result",
1591 id: toolId,
1592 name: toolName,
1593 isFailure: Predicate.isNotNullish(part.error),
1594 providerExecuted: true,
1595 result: {
1596 type: "mcp_call",
1597 name: part.name,
1598 arguments: part.arguments,
1599 server_label: part.server_label,
1600 ...(Predicate.isNotNullish(part.output) ? { output: part.output } : undefined),
1601 ...(Predicate.isNotNullish(part.error) ? { error: part.error } : undefined)
1602 },
1603 metadata: { openai: makeItemIdMetadata(part.id) }
1604 })
1605
1606 break
1607 }
1608
1609 case "mcp_list_tools": {
1610 // Skip
1611 break
1612 }
1613
1614 case "mcp_approval_request": {
1615 const approvalRequestId = (part as any).approval_request_id ?? part.id
1616 const toolId = yield* idGenerator.generateId()
1617
1618 const { toolName, params } = yield* normalizeMcpToolCall({
1619 toolNameMapper,
1620 toolParams: part.arguments,
1621 method: "makeResponse"
1622 })
1623
1624 parts.push({
1625 type: "tool-call",
1626 id: toolId,
1627 name: toolName,
1628 params,
1629 providerExecuted: true
1630 })
1631
1632 parts.push({
1633 type: "tool-approval-request",
1634 toolCallId: toolId,
1635 approvalId: approvalRequestId
1636 })
1637
1638 break
1639 }
1640
1641 case "message": {
1642 for (const contentPart of part.content) {
1643 switch (contentPart.type) {
1644 case "output_text": {
1645 const annotations = contentPart.annotations.length > 0
1646 ? { annotations: contentPart.annotations as any }
1647 : undefined
1648
1649 parts.push({
1650 type: "text",
1651 text: contentPart.text,
1652 metadata: {
1653 openai: {
1654 ...makeItemIdMetadata(part.id),
1655 ...annotations
1656 }
1657 }
1658 })
1659 for (const annotation of contentPart.annotations) {
1660 if (annotation.type === "container_file_citation") {
1661 parts.push({
1662 type: "source",
1663 sourceType: "document",
1664 id: yield* idGenerator.generateId(),
1665 mediaType: "text/plain",
1666 title: annotation.filename,
1667 fileName: annotation.filename,
1668 metadata: {
1669 openai: {
1670 type: annotation.type,
1671 fileId: annotation.file_id,
1672 containerId: annotation.container_id
1673 }
1674 }
1675 })
1676 }
1677 if (annotation.type === "file_citation") {
1678 parts.push({
1679 type: "source",
1680 sourceType: "document",
1681 id: yield* idGenerator.generateId(),
1682 mediaType: "text/plain",
1683 title: annotation.filename,
1684 fileName: annotation.filename,
1685 metadata: {
1686 openai: {
1687 type: annotation.type,
1688 fileId: annotation.file_id,
1689 index: annotation.index
1690 }
1691 }
1692 })
1693 }
1694 if (annotation.type === "file_path") {
1695 parts.push({
1696 type: "source",
1697 sourceType: "document",
1698 id: yield* idGenerator.generateId(),
1699 mediaType: "application/octet-stream",
1700 title: annotation.file_id,
1701 fileName: annotation.file_id,
1702 metadata: {
1703 openai: {
1704 type: annotation.type,
1705 fileId: annotation.file_id,
1706 index: annotation.index
1707 }
1708 }
1709 })
1710 }
1711 if (annotation.type === "url_citation") {
1712 parts.push({
1713 type: "source",
1714 sourceType: "url",
1715 id: yield* idGenerator.generateId(),
1716 url: annotation.url,
1717 title: annotation.title,
1718 metadata: {
1719 openai: {
1720 type: annotation.type,
1721 startIndex: annotation.start_index,
1722 endIndex: annotation.end_index
1723 }
1724 }
1725 })
1726 }
1727 }
1728 break
1729 }
1730 case "refusal": {
1731 parts.push({
1732 type: "text",
1733 text: "",
1734 metadata: { openai: { refusal: contentPart.refusal } }
1735 })
1736 break
1737 }
1738 }
1739 }
1740 break
1741 }
1742
1743 case "reasoning": {
1744 const metadata = {
1745 openai: {
1746 ...makeItemIdMetadata(part.id),
1747 ...makeEncryptedContentMetadata(part.encrypted_content)
1748 }
1749 }
1750 // If there are no summary parts, we have to add an empty one to
1751 // propagate the part identifier and encrypted content
1752 if (part.summary.length === 0) {
1753 parts.push({ type: "reasoning", text: "", metadata })
1754 } else {
1755 for (const summary of part.summary) {
1756 parts.push({ type: "reasoning", text: summary.text, metadata })
1757 }
1758 }
1759 break
1760 }
1761
1762 case "shell_call": {
1763 const toolName = toolNameMapper.getCustomName("shell")
1764 parts.push({
1765 type: "tool-call",
1766 id: part.call_id,
1767 name: toolName,
1768 params: { action: part.action },
1769 metadata: { openai: makeItemIdMetadata(part.id) }
1770 })
1771 break
1772 }
1773
1774 case "web_search_call": {
1775 const toolName = toolNameMapper.getCustomName(
1776 webSearchTool?.name ?? "web_search"
1777 )
1778 parts.push({
1779 type: "tool-call",
1780 id: part.id,
1781 name: toolName,
1782 params: webSearchTool?.name === "OpenAiWebSearchPreview" || Predicate.isUndefined(part.action)
1783 ? {}
1784 : { action: part.action },
1785 providerExecuted: true
1786 })
1787 parts.push({
1788 type: "tool-result",
1789 id: part.id,
1790 name: toolName,
1791 isFailure: part.status !== "completed",
1792 result: {
1793 ...(Predicate.isUndefined(part.action) ? undefined : { action: part.action }),
1794 status: part.status
1795 },
1796 providerExecuted: true
1797 })
1798 break
1799 }
1800 }
1801 }
1802
1803 const finishReason = InternalUtilities.resolveFinishReason(
1804 rawResponse.incomplete_details?.reason,
1805 hasToolCalls
1806 )
1807
1808 parts.push({
1809 type: "finish",
1810 reason: finishReason,
1811 usage: getUsage(rawResponse.usage),
1812 response: buildHttpResponseDetails(response),
1813 ...toFinishMetadata(rawResponse)
1814 })
1815
1816 return parts
1817 }
1818 )
1819
1820 const makeStreamResponse = Effect.fnUntraced(
1821 function*<Tools extends ReadonlyArray<Tool.Any>>({
1822 stream,
1823 response,
1824 config,
1825 options,
1826 toolNameMapper
1827 }: {
1828 readonly config: typeof Config.Service
1829 readonly stream: Stream.Stream<ResponseStreamEvent, AiError.AiError>
1830 readonly response: HttpClientResponse.HttpClientResponse
1831 readonly options: LanguageModel.ProviderOptions
1832 readonly toolNameMapper: Tool.NameMapper<Tools>
1833 }): Effect.fn.Return<
1834 Stream.Stream<Response.StreamPartEncoded, AiError.AiError>,
1835 AiError.AiError,
1836 IdGenerator.IdGenerator
1837 > {
1838 const idGenerator = yield* IdGenerator.IdGenerator
1839 const websocketMode = Option.isSome(yield* Effect.serviceOption(OpenAiSocket))
1840
1841 const approvalRequests = getApprovalRequestIdMapping(options.prompt)
1842 const streamApprovalRequests = new Map<string, string>()
1843
1844 let hasToolCalls = false
1845
1846 // Track annotations for current message to include in text-end metadata
1847 const activeAnnotations: Array<typeof OpenAiSchema.Annotation.Encoded> = []
1848
1849 type ReasoningSummaryPartStatus = "active" | "can-conclude" | "concluded"
1850 type ReasoningPart = {
1851 encryptedContent: string | undefined
1852 summaryParts: Record<number, ReasoningSummaryPartStatus>
1853 }
1854
1855 // Track active reasoning items with state machine for proper concluding logic
1856 const activeReasoning: Record<string, ReasoningPart> = Object.create(null)
1857
1858 const getOrCreateReasoningPart = (
1859 itemId: string,
1860 encryptedContent?: string | null
1861 ): ReasoningPart => {
1862 const activePart = activeReasoning[itemId]
1863 if (Predicate.isNotUndefined(activePart)) {
1864 if (Predicate.isNotNullish(encryptedContent)) {
1865 activePart.encryptedContent = encryptedContent
1866 }
1867 return activePart
1868 }
1869
1870 const reasoningPart: ReasoningPart = {
1871 encryptedContent: Predicate.isNotNullish(encryptedContent) ? encryptedContent : undefined,
1872 summaryParts: {}
1873 }
1874 activeReasoning[itemId] = reasoningPart
1875 return reasoningPart
1876 }
1877
1878 // Track active tool calls with optional provider-specific state
1879 const activeToolCalls: Record<number, {
1880 readonly id: string
1881 readonly name: string
1882 readonly functionCall?: {
1883 emitted: boolean
1884 }
1885 readonly applyPatch?: {
1886 hasDiff: boolean
1887 endEmitted: boolean
1888 }
1889 readonly codeInterpreter?: {
1890 readonly containerId: string
1891 hasCode: boolean
1892 streamedCode: string
1893 }
1894 }> = {}
1895
1896 const finishCodeInterpreterCall = (
1897 outputIndex: number,
1898 code: string | null,
1899 parts: Array<Response.StreamPartEncoded>
1900 ) => {
1901 const toolCall = activeToolCalls[outputIndex]
1902 if (Predicate.isUndefined(toolCall?.codeInterpreter)) {
1903 return
1904 }
1905 parts.push({
1906 type: "tool-params-delta",
1907 id: toolCall.id,
1908 delta: toolCall.codeInterpreter.hasCode ? "\"}" : `${JSON.stringify(code)}}`
1909 })
1910 parts.push({ type: "tool-params-end", id: toolCall.id })
1911 parts.push({
1912 type: "tool-call",
1913 id: toolCall.id,
1914 name: toolCall.name,
1915 params: {
1916 code: toolCall.codeInterpreter.hasCode ? toolCall.codeInterpreter.streamedCode : code,
1917 container_id: toolCall.codeInterpreter.containerId
1918 },
1919 providerExecuted: true
1920 })
1921 delete activeToolCalls[outputIndex]
1922 }
1923
1924 const webSearchTool = options.tools.find((tool) =>
1925 Tool.isProviderDefined(tool) &&
1926 (tool.name === "OpenAiWebSearch" ||
1927 tool.name === "OpenAiWebSearchPreview")
1928 ) as ReturnType<typeof OpenAiTool.WebSearch> | ReturnType<typeof OpenAiTool.WebSearchPreview> | undefined
1929
1930 return stream.pipe(
1931 Stream.mapEffect(Effect.fnUntraced(function*(event) {
1932 const parts: Array<Response.StreamPartEncoded> = []
1933
1934 if (!isKnownResponseStreamEvent(event)) {
1935 return parts
1936 }
1937
1938 switch (event.type) {
1939 case "response.created": {
1940 const createdAt = new Date(event.response.created_at * 1000)
1941 parts.push({
1942 type: "response-metadata",
1943 id: event.response.id,
1944 modelId: event.response.model,
1945 timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(createdAt))
1946 })
1947 break
1948 }
1949
1950 case "error": {
1951 parts.push({ type: "error", error: event })
1952 break
1953 }
1954
1955 case "response.completed":
1956 case "response.incomplete": {
1957 parts.push({
1958 type: "finish",
1959 reason: InternalUtilities.resolveFinishReason(
1960 event.response.incomplete_details?.reason,
1961 hasToolCalls
1962 ),
1963 usage: getUsage(event.response.usage),
1964 response: buildHttpResponseDetails(response),
1965 ...toFinishMetadata(event.response)
1966 })
1967 break
1968 }
1969
1970 case "response.failed": {
1971 if (event.response.error) {
1972 parts.push({ type: "error", error: event.response.error })
1973 }
1974 parts.push({
1975 type: "finish",
1976 reason: "error",
1977 usage: getUsage(event.response.usage),
1978 response: buildHttpResponseDetails(response),
1979 ...toFinishMetadata(event.response)
1980 })
1981 break
1982 }
1983
1984 case "response.output_item.added": {
1985 switch (event.item.type) {
1986 case "apply_patch_call": {
1987 const toolId = event.item.call_id
1988 const toolName = toolNameMapper.getCustomName("apply_patch")
1989 const operation = event.item.operation
1990 activeToolCalls[event.output_index] = {
1991 id: toolId,
1992 name: toolName,
1993 applyPatch: {
1994 hasDiff: operation.type !== "delete_file",
1995 endEmitted: operation.type === "delete_file"
1996 }
1997 }
1998 parts.push({
1999 type: "tool-params-start",
2000 id: toolId,
2001 name: toolName
2002 })
2003
2004 if (operation.type === "delete_file") {
2005 parts.push({
2006 type: "tool-params-delta",
2007 id: toolId,
2008 delta: JSON.stringify({
2009 call_id: toolId,
2010 operation: operation
2011 })
2012 })
2013 parts.push({
2014 type: "tool-params-end",
2015 id: toolId
2016 })
2017 } else {
2018 parts.push({
2019 type: "tool-params-delta",
2020 id: toolId,
2021 delta: `{"call_id":"${InternalUtilities.escapeJSONDelta(toolId)}",` +
2022 `"operation":{"type":"${InternalUtilities.escapeJSONDelta(operation.type)}",` +
2023 `"path":"${InternalUtilities.escapeJSONDelta(operation.path)}","diff":"`
2024 })
2025 }
2026 break
2027 }
2028
2029 case "code_interpreter_call": {
2030 const toolName = toolNameMapper.getCustomName("code_interpreter")
2031 activeToolCalls[event.output_index] = {
2032 id: event.item.id,
2033 name: toolName,
2034 codeInterpreter: { containerId: event.item.container_id, hasCode: false, streamedCode: "" }
2035 }
2036 parts.push({
2037 type: "tool-params-start",
2038 id: event.item.id,
2039 name: toolName,
2040 providerExecuted: true
2041 })
2042 parts.push({
2043 type: "tool-params-delta",
2044 id: event.item.id,
2045 delta: `{"container_id":${JSON.stringify(event.item.container_id)},"code":`
2046 })
2047 break
2048 }
2049
2050 case "computer_call": {
2051 const toolName = toolNameMapper.getCustomName("computer_use")
2052 activeToolCalls[event.output_index] = {
2053 id: event.item.id,
2054 name: toolName
2055 }
2056 parts.push({
2057 type: "tool-params-start",
2058 id: event.item.id,
2059 name: toolName,
2060 providerExecuted: true
2061 })
2062 break
2063 }
2064
2065 case "file_search_call": {
2066 const toolName = toolNameMapper.getCustomName("file_search")
2067 parts.push({
2068 type: "tool-call",
2069 id: event.item.id,
2070 name: toolName,
2071 params: {},
2072 providerExecuted: true
2073 })
2074 break
2075 }
2076
2077 case "function_call": {
2078 activeToolCalls[event.output_index] = {
2079 id: event.item.call_id,
2080 name: event.item.name,
2081 functionCall: { emitted: false }
2082 }
2083 parts.push({
2084 type: "tool-params-start",
2085 id: event.item.call_id,
2086 name: event.item.name
2087 })
2088 break
2089 }
2090
2091 case "image_generation_call": {
2092 const toolName = toolNameMapper.getCustomName("image_generation")
2093 parts.push({
2094 type: "tool-call",
2095 id: event.item.id,
2096 name: toolName,
2097 params: {},
2098 providerExecuted: true
2099 })
2100 break
2101 }
2102
2103 case "mcp_call":
2104 case "mcp_list_tools":
2105 case "mcp_approval_request": {
2106 // We emit MCP tool call / approvals on `output_item.done` to facilitate:
2107 // - Aliasing tool call identifiers when an approval request id exists
2108 // - Emit a proper tool-approval-request part for MCP approvals
2109 break
2110 }
2111
2112 case "message": {
2113 // Clear annotations for new message
2114 activeAnnotations.length = 0
2115 parts.push({
2116 type: "text-start",
2117 id: event.item.id,
2118 metadata: { openai: makeItemIdMetadata(event.item.id) }
2119 })
2120 break
2121 }
2122
2123 case "reasoning": {
2124 const reasoningPart = getOrCreateReasoningPart(event.item.id, event.item.encrypted_content)
2125 if (Predicate.isUndefined(reasoningPart.summaryParts[0])) {
2126 reasoningPart.summaryParts[0] = "active"
2127 parts.push({
2128 type: "reasoning-start",
2129 id: `${event.item.id}:0`,
2130 metadata: {
2131 openai: {
2132 ...makeItemIdMetadata(event.item.id),
2133 ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
2134 }
2135 }
2136 })
2137 }
2138 break
2139 }
2140
2141 case "shell_call": {
2142 const toolName = toolNameMapper.getCustomName("shell")
2143 activeToolCalls[event.output_index] = {
2144 id: event.item.id ?? event.item.call_id,
2145 name: toolName
2146 }
2147 break
2148 }
2149
2150 case "web_search_call": {
2151 const toolName = toolNameMapper.getCustomName(
2152 webSearchTool?.providerName ?? "web_search"
2153 )
2154 activeToolCalls[event.output_index] = {
2155 id: event.item.id,
2156 name: toolName
2157 }
2158 if (webSearchTool?.name === "OpenAiWebSearch") {
2159 break
2160 }
2161 parts.push({
2162 type: "tool-params-start",
2163 id: event.item.id,
2164 name: webSearchTool?.name ?? "OpenAiWebSearch",
2165 providerExecuted: true
2166 })
2167 parts.push({
2168 type: "tool-params-end",
2169 id: event.item.id
2170 })
2171 parts.push({
2172 type: "tool-call",
2173 id: event.item.id,
2174 name: toolName,
2175 params: {},
2176 providerExecuted: true
2177 })
2178 break
2179 }
2180 }
2181
2182 break
2183 }
2184
2185 case "response.output_item.done": {
2186 switch (event.item.type) {
2187 case "apply_patch_call": {
2188 const toolCall = activeToolCalls[event.output_index]
2189 if (
2190 Predicate.isNotUndefined(toolCall.applyPatch) &&
2191 !toolCall.applyPatch.endEmitted &&
2192 event.item.operation.type !== "delete_file"
2193 ) {
2194 if (!toolCall.applyPatch.hasDiff) {
2195 parts.push({
2196 type: "tool-params-delta",
2197 id: toolCall.id,
2198 delta: InternalUtilities.escapeJSONDelta(event.item.operation.diff ?? "")
2199 })
2200 }
2201 parts.push({
2202 type: "tool-params-delta",
2203 id: toolCall.id,
2204 delta: `"}}`
2205 })
2206 parts.push({
2207 type: "tool-params-end",
2208 id: toolCall.id
2209 })
2210 toolCall.applyPatch.endEmitted = true
2211 }
2212 // Emit the final tool call with the complete diff when the status is completed
2213 if (Predicate.isNotUndefined(toolCall) && event.item.status === "completed") {
2214 const toolName = toolNameMapper.getCustomName("apply_patch")
2215 parts.push({
2216 type: "tool-call",
2217 id: toolCall.id,
2218 name: toolName,
2219 params: { call_id: event.item.call_id, operation: event.item.operation },
2220 metadata: { openai: makeItemIdMetadata(event.item.id) }
2221 })
2222 }
2223 delete activeToolCalls[event.output_index]
2224 break
2225 }
2226
2227 case "code_interpreter_call": {
2228 finishCodeInterpreterCall(event.output_index, event.item.code ?? null, parts)
2229 const toolName = toolNameMapper.getCustomName("code_interpreter")
2230 const status = event.item.status ?? "completed"
2231 parts.push({
2232 type: "tool-result",
2233 id: event.item.id,
2234 name: toolName,
2235 isFailure: status !== "completed",
2236 result: { status, outputs: event.item.outputs ?? null },
2237 providerExecuted: true
2238 })
2239 break
2240 }
2241
2242 case "computer_call": {
2243 delete activeToolCalls[event.output_index]
2244 const toolName = toolNameMapper.getCustomName("computer_use")
2245 parts.push({
2246 type: "tool-params-end",
2247 id: event.item.id
2248 })
2249 parts.push({
2250 type: "tool-call",
2251 id: event.item.id,
2252 name: toolName,
2253 params: {},
2254 providerExecuted: true
2255 })
2256 parts.push({
2257 type: "tool-result",
2258 id: event.item.id,
2259 name: toolName,
2260 isFailure: false,
2261 result: { status: event.item.status ?? "completed" }
2262 })
2263 break
2264 }
2265
2266 case "file_search_call": {
2267 delete activeToolCalls[event.output_index]
2268 const toolName = toolNameMapper.getCustomName("file_search")
2269 parts.push({
2270 type: "tool-result",
2271 id: event.item.id,
2272 name: toolName,
2273 isFailure: event.item.status !== "completed",
2274 result: {
2275 status: event.item.status,
2276 queries: event.item.queries,
2277 results: event.item.results ?? null
2278 },
2279 providerExecuted: true
2280 })
2281 break
2282 }
2283
2284 case "function_call": {
2285 const toolCall = activeToolCalls[event.output_index]
2286 if (Predicate.isNotUndefined(toolCall?.functionCall?.emitted) && toolCall.functionCall.emitted) {
2287 delete activeToolCalls[event.output_index]
2288 break
2289 }
2290 delete activeToolCalls[event.output_index]
2291
2292 hasToolCalls = true
2293
2294 const toolName = event.item.name
2295 const toolArgs = event.item.arguments
2296
2297 const toolParams = yield* Effect.try({
2298 try: () => Tool.unsafeSecureJsonParse(toolArgs),
2299 catch: (cause) =>
2300 AiError.make({
2301 module: "OpenAiLanguageModel",
2302 method: "makeStreamResponse",
2303 reason: new AiError.ToolParameterValidationError({
2304 toolName,
2305 description: `Failed securely JSON parse tool parameters: ${cause}`
2306 })
2307 })
2308 })
2309
2310 const params = yield* transformToolCallParams(options, toolName, toolParams)
2311
2312 parts.push({
2313 type: "tool-params-end",
2314 id: event.item.call_id
2315 })
2316
2317 parts.push({
2318 type: "tool-call",
2319 id: event.item.call_id,
2320 name: toolName,
2321 params,
2322 metadata: { openai: makeItemIdMetadata(event.item.id) }
2323 })
2324
2325 break
2326 }
2327
2328 case "image_generation_call": {
2329 const toolName = toolNameMapper.getCustomName("image_generation")
2330 const status = event.item.status ?? "completed"
2331 parts.push({
2332 type: "tool-result",
2333 id: event.item.id,
2334 name: toolName,
2335 isFailure: status !== "completed",
2336 result: status === "completed"
2337 ? { result: event.item.result }
2338 : { status, result: event.item.result },
2339 providerExecuted: true
2340 })
2341 break
2342 }
2343
2344 case "local_shell_call": {
2345 const toolName = toolNameMapper.getCustomName("local_shell")
2346 parts.push({
2347 type: "tool-call",
2348 id: event.item.call_id,
2349 name: toolName,
2350 params: { action: event.item.action },
2351 metadata: { openai: makeItemIdMetadata(event.item.id) }
2352 })
2353 break
2354 }
2355
2356 case "mcp_call": {
2357 const approvalRequestId = event.item.approval_request_id
2358
2359 // Track approval with our own tool call identifiers
2360 const toolId = Predicate.isNotNullish(approvalRequestId)
2361 ? (streamApprovalRequests.get(approvalRequestId) ?? approvalRequests.get(approvalRequestId) ??
2362 event.item.id)
2363 : event.item.id
2364
2365 const { toolName, params } = yield* normalizeMcpToolCall({
2366 toolNameMapper,
2367 toolParams: event.item.arguments,
2368 method: "makeStreamResponse"
2369 })
2370
2371 parts.push({
2372 type: "tool-call",
2373 id: toolId,
2374 name: toolName,
2375 params,
2376 providerExecuted: true
2377 })
2378
2379 parts.push({
2380 type: "tool-result",
2381 id: toolId,
2382 name: toolName,
2383 isFailure: Predicate.isNotNullish(event.item.error),
2384 providerExecuted: true,
2385 result: {
2386 type: "mcp_call",
2387 name: event.item.name,
2388 arguments: event.item.arguments,
2389 server_label: event.item.server_label,
2390 ...(Predicate.isNotNullish(event.item.output) ? { output: event.item.output } : undefined),
2391 ...(Predicate.isNotNullish(event.item.error) ? { error: event.item.error } : undefined)
2392 },
2393 metadata: { openai: makeItemIdMetadata(event.item.id) }
2394 })
2395
2396 break
2397 }
2398
2399 case "mcp_list_tools": {
2400 // Skip
2401 break
2402 }
2403
2404 case "mcp_approval_request": {
2405 const toolId = yield* idGenerator.generateId()
2406 const approvalRequestId = (event.item as any).approval_request_id ?? event.item.id
2407 streamApprovalRequests.set(approvalRequestId, toolId)
2408 const { toolName, params } = yield* normalizeMcpToolCall({
2409 toolNameMapper,
2410 toolParams: event.item.arguments,
2411 method: "makeStreamResponse"
2412 })
2413 parts.push({
2414 type: "tool-call",
2415 id: toolId,
2416 name: toolName,
2417 params,
2418 providerExecuted: true
2419 })
2420 parts.push({
2421 type: "tool-approval-request",
2422 approvalId: approvalRequestId,
2423 toolCallId: toolId
2424 })
2425 break
2426 }
2427
2428 case "message": {
2429 const annotations = activeAnnotations.length > 0
2430 ? { annotations: activeAnnotations.slice() }
2431 : undefined
2432 parts.push({
2433 type: "text-end",
2434 id: event.item.id,
2435 metadata: { openai: { ...annotations, ...makeItemIdMetadata(event.item.id) } }
2436 })
2437 break
2438 }
2439
2440 case "reasoning": {
2441 const reasoningPart = getOrCreateReasoningPart(event.item.id, event.item.encrypted_content)
2442 for (const [summaryIndex, status] of Object.entries(reasoningPart.summaryParts)) {
2443 if (status === "active" || status === "can-conclude") {
2444 parts.push({
2445 type: "reasoning-end",
2446 id: `${event.item.id}:${summaryIndex}`,
2447 metadata: {
2448 openai: {
2449 ...makeItemIdMetadata(event.item.id),
2450 ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
2451 }
2452 }
2453 })
2454 }
2455 }
2456 delete activeReasoning[event.item.id]
2457 break
2458 }
2459
2460 case "shell_call": {
2461 delete activeToolCalls[event.output_index]
2462 const toolName = toolNameMapper.getCustomName("shell")
2463 parts.push({
2464 type: "tool-call",
2465 id: event.item.id ?? event.item.call_id,
2466 name: toolName,
2467 params: { action: event.item.action },
2468 metadata: { openai: makeItemIdMetadata(event.item.id) }
2469 })
2470 break
2471 }
2472
2473 case "web_search_call": {
2474 delete activeToolCalls[event.output_index]
2475 const toolName = toolNameMapper.getCustomName(
2476 webSearchTool?.name ?? "web_search"
2477 )
2478 if (webSearchTool?.name === "OpenAiWebSearch") {
2479 parts.push({
2480 type: "tool-call",
2481 id: event.item.id,
2482 name: toolName,
2483 params: Predicate.isUndefined(event.item.action) ? {} : { action: event.item.action },
2484 providerExecuted: true
2485 })
2486 }
2487 parts.push({
2488 type: "tool-result",
2489 id: event.item.id,
2490 name: toolName,
2491 isFailure: event.item.status !== "completed",
2492 result: {
2493 ...(Predicate.isUndefined(event.item.action) ? undefined : { action: event.item.action }),
2494 status: event.item.status
2495 },
2496 providerExecuted: true
2497 })
2498 break
2499 }
2500 }
2501
2502 break
2503 }
2504
2505 case "response.output_text.delta": {
2506 parts.push({
2507 type: "text-delta",
2508 id: event.item_id,
2509 delta: event.delta
2510 })
2511 break
2512 }
2513
2514 case "response.output_text.annotation.added": {
2515 const annotation = event.annotation as typeof OpenAiSchema.Annotation.Encoded
2516 // Track annotation for text-end metadata
2517 activeAnnotations.push(annotation)
2518 if (annotation.type === "container_file_citation") {
2519 parts.push({
2520 type: "source",
2521 sourceType: "document",
2522 id: yield* idGenerator.generateId(),
2523 mediaType: "text/plain",
2524 title: annotation.filename,
2525 fileName: annotation.filename,
2526 metadata: {
2527 openai: {
2528 type: annotation.type,
2529 fileId: annotation.file_id,
2530 containerId: annotation.container_id
2531 }
2532 }
2533 })
2534 } else if (annotation.type === "file_citation") {
2535 parts.push({
2536 type: "source",
2537 sourceType: "document",
2538 id: yield* idGenerator.generateId(),
2539 mediaType: "text/plain",
2540 title: annotation.filename,
2541 fileName: annotation.filename,
2542 metadata: {
2543 openai: {
2544 type: annotation.type,
2545 fileId: annotation.file_id,
2546 index: annotation.index
2547 }
2548 }
2549 })
2550 } else if (annotation.type === "file_path") {
2551 parts.push({
2552 type: "source",
2553 sourceType: "document",
2554 id: yield* idGenerator.generateId(),
2555 mediaType: "application/octet-stream",
2556 title: annotation.file_id,
2557 fileName: annotation.file_id,
2558 metadata: {
2559 openai: {
2560 type: annotation.type,
2561 fileId: annotation.file_id,
2562 index: annotation.index
2563 }
2564 }
2565 })
2566 } else if (annotation.type === "url_citation") {
2567 parts.push({
2568 type: "source",
2569 sourceType: "url",
2570 id: yield* idGenerator.generateId(),
2571 url: annotation.url,
2572 title: annotation.title,
2573 metadata: {
2574 openai: {
2575 type: annotation.type,
2576 startIndex: annotation.start_index,
2577 endIndex: annotation.end_index
2578 }
2579 }
2580 })
2581 }
2582 break
2583 }
2584
2585 case "response.function_call_arguments.delta": {
2586 const toolCallPart = activeToolCalls[event.output_index]
2587 if (Predicate.isNotUndefined(toolCallPart)) {
2588 parts.push({
2589 type: "tool-params-delta",
2590 id: toolCallPart.id,
2591 delta: event.delta
2592 })
2593 }
2594 break
2595 }
2596
2597 case "response.function_call_arguments.done": {
2598 const toolCall = activeToolCalls[event.output_index]
2599 if (
2600 Predicate.isNotUndefined(toolCall?.functionCall) &&
2601 !toolCall.functionCall.emitted
2602 ) {
2603 hasToolCalls = true
2604
2605 const toolParams = yield* Effect.try({
2606 try: () => Tool.unsafeSecureJsonParse(event.arguments),
2607 catch: (cause) =>
2608 AiError.make({
2609 module: "OpenAiLanguageModel",
2610 method: "makeStreamResponse",
2611 reason: new AiError.ToolParameterValidationError({
2612 toolName: toolCall.name,
2613 description: `Failed securely JSON parse tool parameters: ${cause}`
2614 })
2615 })
2616 })
2617
2618 const params = yield* transformToolCallParams(options, toolCall.name, toolParams)
2619
2620 parts.push({
2621 type: "tool-params-end",
2622 id: toolCall.id
2623 })
2624
2625 parts.push({
2626 type: "tool-call",
2627 id: toolCall.id,
2628 name: toolCall.name,
2629 params,
2630 metadata: { openai: makeItemIdMetadata(event.item_id) }
2631 })
2632
2633 toolCall.functionCall.emitted = true
2634 }
2635 break
2636 }
2637
2638 case "response.apply_patch_call_operation_diff.delta": {
2639 const toolCall = activeToolCalls[event.output_index]
2640 if (Predicate.isNotUndefined(toolCall?.applyPatch)) {
2641 parts.push({
2642 type: "tool-params-delta",
2643 id: toolCall.id,
2644 delta: InternalUtilities.escapeJSONDelta(event.delta)
2645 })
2646 toolCall.applyPatch.hasDiff = true
2647 }
2648 break
2649 }
2650
2651 case "response.apply_patch_call_operation_diff.done": {
2652 const toolCall = activeToolCalls[event.output_index]
2653 if (Predicate.isNotUndefined(toolCall?.applyPatch) && !toolCall.applyPatch.endEmitted) {
2654 if (!toolCall.applyPatch.hasDiff && Predicate.isNotUndefined(event.delta)) {
2655 parts.push({
2656 type: "tool-params-delta",
2657 id: toolCall.id,
2658 delta: InternalUtilities.escapeJSONDelta(event.delta)
2659 })
2660 toolCall.applyPatch.hasDiff = true
2661 }
2662 parts.push({
2663 type: "tool-params-delta",
2664 id: toolCall.id,
2665 delta: `"}}`
2666 })
2667 parts.push({
2668 type: "tool-params-end",
2669 id: toolCall.id
2670 })
2671 toolCall.applyPatch.endEmitted = true
2672 }
2673 break
2674 }
2675
2676 case "response.code_interpreter_call_code.delta": {
2677 const toolCall = activeToolCalls[event.output_index]
2678 if (Predicate.isNotUndefined(toolCall?.codeInterpreter)) {
2679 parts.push({
2680 type: "tool-params-delta",
2681 id: toolCall.id,
2682 delta: (toolCall.codeInterpreter.hasCode ? "" : "\"") +
2683 InternalUtilities.escapeJSONDelta(event.delta)
2684 })
2685 toolCall.codeInterpreter.hasCode = true
2686 toolCall.codeInterpreter.streamedCode += event.delta
2687 }
2688 break
2689 }
2690
2691 case "response.code_interpreter_call_code.done": {
2692 finishCodeInterpreterCall(event.output_index, event.code, parts)
2693 break
2694 }
2695
2696 case "response.image_generation_call.partial_image": {
2697 const toolName = toolNameMapper.getCustomName("image_generation")
2698 parts.push({
2699 type: "tool-result",
2700 id: event.item_id,
2701 name: toolName,
2702 isFailure: false,
2703 providerExecuted: false,
2704 result: { result: event.partial_image_b64 },
2705 preliminary: true
2706 })
2707 break
2708 }
2709
2710 case "response.reasoning_summary_part.added": {
2711 const reasoningPart = getOrCreateReasoningPart(event.item_id)
2712 if (event.summary_index > 0) {
2713 // Conclude all can-conclude parts before starting new one
2714 for (const [summaryIndex, status] of Object.entries(reasoningPart.summaryParts)) {
2715 if (status === "can-conclude") {
2716 parts.push({
2717 type: "reasoning-end",
2718 id: `${event.item_id}:${summaryIndex}`,
2719 metadata: {
2720 openai: {
2721 ...makeItemIdMetadata(event.item_id),
2722 ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
2723 }
2724 }
2725 })
2726 reasoningPart.summaryParts[Number(summaryIndex)] = "concluded"
2727 }
2728 }
2729 }
2730
2731 if (Predicate.isUndefined(reasoningPart.summaryParts[event.summary_index])) {
2732 reasoningPart.summaryParts[event.summary_index] = "active"
2733 parts.push({
2734 type: "reasoning-start",
2735 id: `${event.item_id}:${event.summary_index}`,
2736 metadata: {
2737 openai: {
2738 ...makeItemIdMetadata(event.item_id),
2739 ...makeEncryptedContentMetadata(reasoningPart.encryptedContent)
2740 }
2741 }
2742 })
2743 }
2744 break
2745 }
2746
2747 case "response.reasoning_summary_text.delta": {
2748 parts.push({
2749 type: "reasoning-delta",
2750 id: `${event.item_id}:${event.summary_index}`,
2751 delta: event.delta,
2752 metadata: { openai: makeItemIdMetadata(event.item_id) }
2753 })
2754 break
2755 }
2756
2757 case "response.reasoning_summary_part.done": {
2758 const reasoningPart = getOrCreateReasoningPart(event.item_id)
2759 // HTTP requests using stored item references do not need encrypted
2760 // content, so the reasoning part can be concluded immediately.
2761 if (!websocketMode && config.store === true && config.useItemReferences !== false) {
2762 parts.push({
2763 type: "reasoning-end",
2764 id: `${event.item_id}:${event.summary_index}`,
2765 metadata: { openai: makeItemIdMetadata(event.item_id) }
2766 })
2767 // Mark the summary part concluded
2768 reasoningPart.summaryParts[event.summary_index] = "concluded"
2769 } else {
2770 // Mark the summary part as can-conclude given we still need a
2771 // final summary part with the encrypted content
2772 reasoningPart.summaryParts[event.summary_index] = "can-conclude"
2773 }
2774 break
2775 }
2776 }
2777
2778 return parts
2779 })),
2780 Stream.flattenIterable
2781 )
2782 }
2783 )
2784
2785 // =============================================================================
2786 // Telemetry
2787 // =============================================================================
2788
2789 const annotateRequest = (
2790 span: Span,
2791 request: typeof OpenAiSchema.CreateResponse.Encoded
2792 ): void => {
2793 addGenAIAnnotations(span, {
2794 provider: { name: "openai" },
2795 operation: { name: "chat" },
2796 request: {
2797 model: request.model as string,
2798 temperature: request.temperature as number | undefined,
2799 topP: request.top_p as number | undefined,
2800 maxTokens: request.max_output_tokens as number | undefined
2801 },
2802 openai: {
2803 request: {
2804 serviceTier: request.service_tier as string | undefined
2805 }
2806 }
2807 })
2808 }
2809
2810 const annotateResponse = (span: Span, response: OpenAiSchema.Response): void => {
2811 const finishReason = response.incomplete_details?.reason as string | undefined
2812 addGenAIAnnotations(span, {
2813 response: {
2814 id: response.id,
2815 model: response.model as string,
2816 finishReasons: Predicate.isNotUndefined(finishReason) ? [finishReason] : undefined
2817 },
2818 usage: {
2819 inputTokens: response.usage?.input_tokens as number | undefined,
2820 outputTokens: response.usage?.output_tokens as number | undefined
2821 },
2822 openai: {
2823 response: {
2824 serviceTier: response.service_tier as string | undefined
2825 }
2826 }
2827 })
2828 }
2829
2830 const annotateStreamResponse = (span: Span, part: Response.StreamPartEncoded) => {
2831 if (part.type === "response-metadata") {
2832 addGenAIAnnotations(span, {
2833 response: {
2834 id: part.id,
2835 model: part.modelId
2836 }
2837 })
2838 }
2839 if (part.type === "finish") {
2840 const serviceTier = (part.metadata as any)?.openai?.serviceTier as string | undefined
2841 addGenAIAnnotations(span, {
2842 response: {
2843 finishReasons: [part.reason]
2844 },
2845 usage: {
2846 inputTokens: part.usage.inputTokens.total,
2847 outputTokens: part.usage.outputTokens.total
2848 },
2849 openai: {
2850 response: { serviceTier }
2851 }
2852 })
2853 }
2854 }
2855
2856 // =============================================================================
2857 // Tool Conversion
2858 // =============================================================================
2859
2860 type OpenAiToolChoice = typeof OpenAiSchema.CreateResponse.Encoded["tool_choice"]
2861
2862 const prepareTools = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Tool.Any>>({
2863 config,
2864 options,
2865 toolNameMapper
2866 }: {
2867 readonly config: typeof Config.Service
2868 readonly options: LanguageModel.ProviderOptions
2869 readonly toolNameMapper: Tool.NameMapper<Tools>
2870 }): Effect.fn.Return<{
2871 readonly tools: ReadonlyArray<typeof OpenAiSchema.Tool.Encoded> | undefined
2872 readonly toolChoice: OpenAiToolChoice | undefined
2873 }, AiError.AiError> {
2874 // Return immediately if no tools are in the toolkit
2875 if (options.tools.length === 0) {
2876 return { tools: undefined, toolChoice: undefined }
2877 }
2878
2879 const tools: Array<typeof OpenAiSchema.Tool.Encoded> = []
2880 let toolChoice: OpenAiToolChoice | undefined = undefined
2881
2882 // Filter the incoming tools down to the set of allowed tools as indicated by
2883 // the tool choice. This must be done here given that there is no tool name
2884 // in OpenAI's provider-defined tools, so there would be no way to perform
2885 // this filter otherwise
2886 let allowedTools = options.tools
2887 if (typeof options.toolChoice === "object" && "oneOf" in options.toolChoice) {
2888 const allowedToolNames = new Set(options.toolChoice.oneOf)
2889 allowedTools = options.tools.filter((tool) => allowedToolNames.has(tool.name))
2890 toolChoice = options.toolChoice.mode === "required" ? "required" : "auto"
2891 }
2892
2893 // Convert the tools in the toolkit to the provider-defined format
2894 for (const tool of allowedTools) {
2895 if (Tool.isUserDefined(tool) || Tool.isDynamic(tool)) {
2896 const strict = Tool.getStrictMode(tool) ?? config.strictJsonSchema ?? true
2897 const description = Tool.getDescription(tool)
2898 const parameters = yield* tryToolJsonSchema(tool, "prepareTools")
2899 tools.push({
2900 type: "function",
2901 name: tool.name,
2902 parameters,
2903 strict,
2904 ...(Predicate.isNotUndefined(description) ? { description } : undefined)
2905 })
2906 }
2907
2908 if (Tool.isProviderDefined(tool)) {
2909 const openAiTool = tool as OpenAiTool.OpenAiTool
2910 switch (openAiTool.name) {
2911 case "OpenAiApplyPatch": {
2912 tools.push({ type: "apply_patch" })
2913 break
2914 }
2915 case "OpenAiCodeInterpreter": {
2916 const args = yield* Schema.decodeUnknownEffect(openAiTool.argsSchema)(tool.args).pipe(
2917 Effect.mapError((error) =>
2918 AiError.make({
2919 module: "OpenAiLanguageModel",
2920 method: "prepareTools",
2921 reason: new AiError.ToolConfigurationError({
2922 toolName: openAiTool.name,
2923 description: error.message
2924 })
2925 })
2926 )
2927 )
2928 tools.push({
2929 ...args,
2930 type: "code_interpreter"
2931 })
2932 break
2933 }
2934 case "OpenAiFileSearch": {
2935 const args = yield* Schema.decodeUnknownEffect(openAiTool.argsSchema)(tool.args).pipe(
2936 Effect.mapError((error) =>
2937 AiError.make({
2938 module: "OpenAiLanguageModel",
2939 method: "prepareTools",
2940 reason: new AiError.ToolConfigurationError({
2941 toolName: openAiTool.name,
2942 description: error.message
2943 })
2944 })
2945 )
2946 )
2947 tools.push({
2948 ...args,
2949 type: "file_search"
2950 })
2951 break
2952 }
2953 case "OpenAiShell": {
2954 tools.push({ type: "shell" })
2955 break
2956 }
2957 case "OpenAiImageGeneration": {
2958 const args = yield* Schema.decodeUnknownEffect(openAiTool.argsSchema)(tool.args).pipe(
2959 Effect.mapError((error) =>
2960 AiError.make({
2961 module: "OpenAiLanguageModel",
2962 method: "prepareTools",
2963 reason: new AiError.ToolConfigurationError({
2964 toolName: openAiTool.name,
2965 description: error.message
2966 })
2967 })
2968 )
2969 )
2970 tools.push({
2971 ...args,
2972 type: "image_generation"
2973 })
2974 break
2975 }
2976 case "OpenAiLocalShell": {
2977 tools.push({ type: "local_shell" })
2978 break
2979 }
2980 case "OpenAiMcp": {
2981 const args = yield* Schema.decodeUnknownEffect(openAiTool.argsSchema)(tool.args).pipe(
2982 Effect.mapError((error) =>
2983 AiError.make({
2984 module: "OpenAiLanguageModel",
2985 method: "prepareTools",
2986 reason: new AiError.ToolConfigurationError({
2987 toolName: openAiTool.name,
2988 description: error.message
2989 })
2990 })
2991 )
2992 )
2993 tools.push({
2994 ...args,
2995 type: "mcp"
2996 })
2997 break
2998 }
2999 case "OpenAiWebSearch": {
3000 const args = yield* Schema.decodeUnknownEffect(openAiTool.argsSchema)(tool.args).pipe(
3001 Effect.mapError((error) =>
3002 AiError.make({
3003 module: "OpenAiLanguageModel",
3004 method: "prepareTools",
3005 reason: new AiError.ToolConfigurationError({
3006 toolName: openAiTool.name,
3007 description: error.message
3008 })
3009 })
3010 )
3011 )
3012 tools.push({
3013 ...args,
3014 type: "web_search"
3015 })
3016 break
3017 }
3018 case "OpenAiWebSearchPreview": {
3019 const args = yield* Schema.decodeUnknownEffect(openAiTool.argsSchema)(tool.args).pipe(
3020 Effect.mapError((error) =>
3021 AiError.make({
3022 module: "OpenAiLanguageModel",
3023 method: "prepareTools",
3024 reason: new AiError.ToolConfigurationError({
3025 toolName: openAiTool.name,
3026 description: error.message
3027 })
3028 })
3029 )
3030 )
3031 tools.push({
3032 ...args,
3033 type: "web_search_preview"
3034 })
3035 break
3036 }
3037 default: {
3038 return yield* AiError.make({
3039 module: "OpenAiLanguageModel",
3040 method: "prepareTools",
3041 reason: new AiError.InvalidRequestError({
3042 description: `Unknown provider-defined tool '${tool.name}'`
3043 })
3044 })
3045 }
3046 }
3047 }
3048 }
3049
3050 if (options.toolChoice === "auto" || options.toolChoice === "none" || options.toolChoice === "required") {
3051 toolChoice = options.toolChoice
3052 }
3053
3054 if (typeof options.toolChoice === "object" && "tool" in options.toolChoice) {
3055 const toolName = toolNameMapper.getProviderName(options.toolChoice.tool)
3056 const providerNames = toolNameMapper.providerNames
3057 if (providerNames.includes(toolName)) {
3058 toolChoice = { type: toolName as any }
3059 } else {
3060 toolChoice = { type: "function", name: options.toolChoice.tool }
3061 }
3062 }
3063
3064 return { tools, toolChoice }
3065 })
3066
3067 const prepareToolResultOutput = Effect.fnUntraced(function*(
3068 modelOutput: ReadonlyArray<Prompt.ToolModelOutputPart>,
3069 config: typeof Config.Service
3070 ): Effect.fn.Return<string | Array<typeof OpenAiSchema.InputContent.Encoded>, AiError.AiError> {
3071 if (modelOutput.length === 0) {
3072 return ""
3073 }
3074 const output: Array<typeof OpenAiSchema.InputContent.Encoded> = []
3075 for (let index = 0; index < modelOutput.length; index++) {
3076 const part = modelOutput[index]
3077 output.push(
3078 part.type === "text"
3079 ? { type: "input_text", text: part.text, ...getPromptCacheBreakpoint(part) }
3080 : yield* prepareFilePart(part, index, config)
3081 )
3082 }
3083 return output
3084 })
3085
3086 const prepareFilePart = Effect.fnUntraced(function*(
3087 part: Prompt.FilePart,
3088 index: number,
3089 config: typeof Config.Service
3090 ): Effect.fn.Return<typeof OpenAiSchema.InputContent.Encoded, AiError.AiError> {
3091 const promptCacheBreakpoint = getPromptCacheBreakpoint(part)
3092
3093 if (part.mediaType.startsWith("image/")) {
3094 const detail = getImageDetail(part)
3095 const mediaType = part.mediaType === "image/*" ? "image/jpeg" : part.mediaType
3096
3097 if (typeof part.data === "string" && isFileId(part.data, config)) {
3098 return { type: "input_image", file_id: part.data, detail, ...promptCacheBreakpoint }
3099 }
3100
3101 const imageUrl = part.data instanceof URL
3102 ? part.data.toString()
3103 : part.data instanceof Uint8Array
3104 ? `data:${mediaType};base64,${Base64.encode(part.data)}`
3105 : /^(data:|https?:\/\/)/i.test(part.data)
3106 ? part.data
3107 : `data:${mediaType};base64,${part.data}`
3108 return { type: "input_image", image_url: imageUrl, detail, ...promptCacheBreakpoint }
3109 }
3110
3111 if (part.mediaType === "application/pdf") {
3112 if (typeof part.data === "string" && isFileId(part.data, config)) {
3113 return { type: "input_file", file_id: part.data, ...promptCacheBreakpoint }
3114 }
3115
3116 if (part.data instanceof URL || (typeof part.data === "string" && /^https?:\/\//i.test(part.data))) {
3117 return { type: "input_file", file_url: part.data.toString(), ...promptCacheBreakpoint }
3118 }
3119
3120 const fileData = part.data instanceof Uint8Array
3121 ? `data:application/pdf;base64,${Base64.encode(part.data)}`
3122 : /^data:/i.test(part.data)
3123 ? part.data
3124 : `data:application/pdf;base64,${part.data}`
3125 return {
3126 type: "input_file",
3127 filename: part.fileName ?? `part-${index}.pdf`,
3128 file_data: fileData,
3129 ...promptCacheBreakpoint
3130 }
3131 }
3132
3133 return yield* AiError.make({
3134 module: "OpenAiLanguageModel",
3135 method: "prepareMessages",
3136 reason: new AiError.InvalidRequestError({
3137 description: `Detected unsupported media type for file: '${part.mediaType}'`
3138 })
3139 })
3140 })
3141
3142 // =============================================================================
3143 // Utilities
3144 // =============================================================================
3145
3146 const isFileId = (data: string, config: typeof Config.Service): boolean =>
3147 config.fileIdPrefixes != null && config.fileIdPrefixes.some((prefix) => data.startsWith(prefix))
3148
3149 const getItemId = (
3150 part:
3151 | Prompt.TextPart
3152 | Prompt.ReasoningPart
3153 | Prompt.ToolCallPart
3154 | Prompt.ToolResultPart
3155 ): string | null => part.options.openai?.itemId ?? null
3156 const getStatus = (
3157 part:
3158 | Prompt.TextPart
3159 | Prompt.ToolCallPart
3160 | Prompt.ToolResultPart
3161 ): typeof OpenAiSchema.MessageStatus.Encoded | null => part.options.openai?.status ?? null
3162 const getEncryptedContent = (
3163 part: Prompt.ReasoningPart
3164 ): string | null => part.options.openai?.encryptedContent ?? null
3165
3166 const getImageDetail = (part: Prompt.FilePart): ImageDetail => part.options.openai?.imageDetail ?? "auto"
3167
3168 const getPromptCacheBreakpoint = (
3169 input: Prompt.SystemMessage | Prompt.TextPart | Prompt.FilePart
3170 ) => {
3171 const promptCacheBreakpoint = input.options.openai?.promptCacheBreakpoint
3172 return Predicate.isNotNullish(promptCacheBreakpoint) ? { prompt_cache_breakpoint: promptCacheBreakpoint } : undefined
3173 }
3174
3175 const makeItemIdMetadata = (itemId: string | undefined) => Predicate.isNotUndefined(itemId) ? { itemId } : {}
3176
3177 const makeEncryptedContentMetadata = (encryptedContent: string | null | undefined) =>
3178 Predicate.isNotNullish(encryptedContent) ? { encryptedContent } : undefined
3179
3180 const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError =>
3181 AiError.make({
3182 module: "OpenAiLanguageModel",
3183 method,
3184 reason: new AiError.UnsupportedSchemaError({
3185 description: error instanceof Error ? error.message : String(error)
3186 })
3187 })
3188
3189 const tryCodecTransform = <S extends Schema.Constraint>(schema: S, method: string) =>
3190 Effect.try({
3191 try: () => toCodecOpenAI(schema),
3192 catch: (error) => unsupportedSchemaError(error, method)
3193 })
3194
3195 const tryJsonSchema = <S extends Schema.Constraint>(schema: S, method: string) =>
3196 Effect.try({
3197 try: () => Tool.getJsonSchemaFromSchema(schema, { transformer: toCodecOpenAI }),
3198 catch: (error) => unsupportedSchemaError(error, method)
3199 })
3200
3201 const toolParametersError = (tool: Tool.Any, error: unknown, method: string): AiError.AiError =>
3202 unsupportedSchemaError(
3203 `Tool "${tool.name}" parameters: ${error instanceof Error ? error.message : String(error)}. ` +
3204 "For a tool without parameters, omit `parameters` or use `Tool.EmptyParams`",
3205 method
3206 )
3207
3208 const tryToolJsonSchema = <T extends Tool.Any>(tool: T, method: string) =>
3209 Effect.try({
3210 try: () => Tool.getJsonSchema(tool, { transformer: toCodecOpenAI }),
3211 catch: (error) => toolParametersError(tool, error, method)
3212 })
3213
3214 const prepareResponseFormat = Effect.fnUntraced(function*({ config, options }: {
3215 readonly config: typeof Config.Service
3216 readonly options: LanguageModel.ProviderOptions
3217 }): Effect.fn.Return<typeof OpenAiSchema.TextResponseFormatConfiguration.Encoded, AiError.AiError> {
3218 if (options.responseFormat.type === "json") {
3219 const name = options.responseFormat.objectName
3220 const schema = options.responseFormat.schema
3221 const jsonSchema = yield* tryJsonSchema(schema, "prepareResponseFormat")
3222 return {
3223 type: "json_schema",
3224 name,
3225 description: AST.resolveDescription(schema.ast) ?? "Response with a JSON object",
3226 schema: jsonSchema,
3227 strict: config.strictJsonSchema ?? true
3228 }
3229 }
3230 return { type: "text" }
3231 })
3232
3233 // Default new model names to reasoning without extending an allowlist.
3234 const nonReasoningModelPattern = /^(?:gpt-[34]|chatgpt-|chat-latest|gpt-\d+(?:\.\d+)?-chat)/
3235
3236 const resolveReasoningModel = (config: typeof Config.Service): boolean => {
3237 if (Predicate.isNotUndefined(config.reasoningModel)) {
3238 return config.reasoningModel
3239 }
3240 const model = config.model ?? ""
3241 const baseModel = model.startsWith("ft:") ? model.slice(3) : model
3242 return !nonReasoningModelPattern.test(baseModel)
3243 }
3244
3245 const getApprovalRequestIdMapping = (prompt: Prompt.Prompt): ReadonlyMap<string, string> => {
3246 const mapping = new Map<string, string>()
3247
3248 for (const message of prompt.content) {
3249 if (message.role !== "assistant") {
3250 continue
3251 }
3252
3253 for (const part of message.content) {
3254 if (part.type !== "tool-call") {
3255 continue
3256 }
3257
3258 const approvalRequestId = part.options.openai?.approvalRequestId
3259
3260 if (Predicate.isNotNullish(approvalRequestId)) {
3261 mapping.set(approvalRequestId, part.id)
3262 }
3263 }
3264 }
3265
3266 return mapping
3267 }
3268
3269 const normalizeMcpToolCall = Effect.fnUntraced(function*<Tools extends ReadonlyArray<Tool.Any>>({
3270 toolNameMapper,
3271 toolParams,
3272 method
3273 }: {
3274 readonly toolNameMapper: Tool.NameMapper<Tools>
3275 readonly toolParams: unknown
3276 readonly method: string
3277 }): Effect.fn.Return<{
3278 readonly toolName: string
3279 readonly params: unknown
3280 }, AiError.AiError> {
3281 const toolName = toolNameMapper.getCustomName("mcp")
3282
3283 if (typeof toolParams !== "string") {
3284 return { toolName, params: toolParams }
3285 }
3286
3287 const params = yield* Effect.try({
3288 try: () => Tool.unsafeSecureJsonParse(toolParams),
3289 catch: (cause) =>
3290 AiError.make({
3291 module: "OpenAiLanguageModel",
3292 method,
3293 reason: new AiError.ToolParameterValidationError({
3294 toolName,
3295 description: `Failed to securely JSON parse tool parameters: ${cause}`
3296 })
3297 })
3298 })
3299
3300 return { toolName, params }
3301 })
3302
3303 const getUsage = (usage: OpenAiSchema.ResponseUsage | null | undefined): Response.Usage => {
3304 if (Predicate.isNullish(usage)) {
3305 return {
3306 inputTokens: {
3307 uncached: undefined,
3308 total: undefined,
3309 cacheRead: undefined,
3310 cacheWrite: undefined
3311 },
3312 outputTokens: {
3313 total: undefined,
3314 text: undefined,
3315 reasoning: undefined
3316 }
3317 }
3318 }
3319
3320 const inputTokens = usage.input_tokens
3321 const outputTokens = usage.output_tokens
3322 const cachedTokens = getUsageTokenDetail(usage.input_tokens_details, "cached_tokens") ?? 0
3323 const cacheWriteTokens = getUsageTokenDetail(usage.input_tokens_details, "cache_write_tokens")
3324 const reasoningTokens = getUsageTokenDetail(usage.output_tokens_details, "reasoning_tokens") ?? 0
3325
3326 return {
3327 inputTokens: {
3328 uncached: inputTokens - cachedTokens,
3329 total: inputTokens,
3330 cacheRead: cachedTokens,
3331 cacheWrite: cacheWriteTokens
3332 },
3333 outputTokens: {
3334 total: outputTokens,
3335 text: outputTokens - reasoningTokens,
3336 reasoning: reasoningTokens
3337 }
3338 }
3339 }
3340
3341 type ServiceTier = "default" | "auto" | "flex" | "scale" | "priority" | "ultrafast" | null
3342
3343 const toFinishMetadata = (response: OpenAiSchema.Response): {
3344 readonly metadata: Response.FinishPartMetadata
3345 } | undefined => {
3346 let serviceTier: ServiceTier | undefined
3347 switch (response.service_tier) {
3348 case "default":
3349 case "auto":
3350 case "flex":
3351 case "scale":
3352 case "priority":
3353 case "ultrafast":
3354 serviceTier = response.service_tier
3355 break
3356 }
3357
3358 const promptCacheDiagnostics = response.prompt_cache_diagnostics
3359 if (serviceTier === undefined && promptCacheDiagnostics === undefined) {
3360 return undefined
3361 }
3362
3363 return {
3364 metadata: {
3365 openai: {
3366 ...(serviceTier === undefined ? undefined : { serviceTier }),
3367 ...(promptCacheDiagnostics === undefined ? undefined : { promptCacheDiagnostics })
3368 }
3369 }
3370 }
3371 }
3372
3373 const getUsageTokenDetail = (details: unknown, key: string): number | undefined =>
3374 Predicate.hasProperty(details, key) && typeof details[key] === "number" ? details[key] : undefined
3375
3376 const transformToolCallParams = Effect.fnUntraced(function*(
3377 options: LanguageModel.ProviderOptions,
3378 toolName: string,
3379 toolParams: unknown
3380 ): Effect.fn.Return<unknown, AiError.AiError> {
3381 const tool = options.tools.find((tool) => tool.name === toolName)
3382
3383 if (Predicate.isUndefined(tool)) {
3384 if (options.toolCallValidation === "deferred") {
3385 return toolParams
3386 }
3387 return yield* AiError.make({
3388 module: "OpenAiLanguageModel",
3389 method: "makeResponse",
3390 reason: new AiError.ToolNotFoundError({
3391 toolName,
3392 availableTools: options.tools.map((tool) => tool.name)
3393 })
3394 })
3395 }
3396
3397 if (Tool.isDynamic(tool) && tool.jsonSchema !== undefined) {
3398 return toolParams
3399 }
3400
3401 const { codec } = yield* tryCodecTransform(tool.parametersSchema, "makeResponse")
3402
3403 // Normalize valid parameters; leave invalid ones for Toolkit.
3404 return yield* (
3405 Schema.decodeEffect(codec)(toolParams) as Effect.Effect<unknown, Schema.SchemaError>
3406 ).pipe(
3407 Effect.flatMap((decoded) =>
3408 Schema.encodeUnknownEffect(tool.parametersSchema)(decoded) as Effect.Effect<unknown, Schema.SchemaError>
3409 ),
3410 Effect.orElseSucceed(() => toolParams)
3411 )
3412 })