@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 1,927 lines 66.5 KB
Raw
1 /**
2 * The `OpenRouterLanguageModel` module provides the OpenRouter implementation
3 * of Effect AI's `LanguageModel` service. It translates provider-neutral
4 * prompts, tools, files, structured output requests, reasoning metadata,
5 * cache-control hints, and provider options into OpenRouter chat completion
6 * requests, records GenAI telemetry around those calls, and converts normal or
7 * streaming results back into Effect AI response content and metadata.
8 *
9 * @stability unstable
10 * @since 4.0.0
11 */
12 /** @effect-diagnostics preferSchemaOverJson:skip-file */
13 import * as AiError from "effect/ai/AiError"
14 import { toCodecAnthropic } from "effect/ai/AnthropicStructuredOutput"
15 import * as IdGenerator from "effect/ai/IdGenerator"
16 import * as LanguageModel from "effect/ai/LanguageModel"
17 import * as AiModel from "effect/ai/Model"
18 import { toCodecOpenAI } from "effect/ai/OpenAiStructuredOutput"
19 import * as Prompt from "effect/ai/Prompt"
20 import type * as Response from "effect/ai/Response"
21 import { addGenAIAnnotations } from "effect/ai/Telemetry"
22 import * as Tool from "effect/ai/Tool"
23 import * as Arr from "effect/Array"
24 import * as Context from "effect/Context"
25 import * as DateTime from "effect/DateTime"
26 import * as Effect from "effect/Effect"
27 import * as Base64 from "effect/encoding/Base64"
28 import { dual } from "effect/Function"
29 import type * as HttpClientResponse from "effect/http/HttpClientResponse"
30 import * as Layer from "effect/Layer"
31 import * as Predicate from "effect/Predicate"
32 import * as Redactable from "effect/Redactable"
33 import type * as Schema from "effect/Schema"
34 import * as SchemaAST from "effect/SchemaAST"
35 import * as Stream from "effect/Stream"
36 import type { Span } from "effect/Tracer"
37 import type { DeepMutable, Mutable, Simplify } from "effect/Types"
38 import type * as Generated from "./Generated.ts"
39 import { ReasoningDetailsDuplicateTracker, resolveFinishReason } from "./internal/utilities.ts"
40 import { type ChatStreamingResponseChunkData, OpenRouterClient } from "./OpenRouterClient.ts"
41
42 // =============================================================================
43 // Configuration
44 // =============================================================================
45
46 /**
47 * Context service for OpenRouter language model configuration.
48 *
49 * **When to use**
50 *
51 * Use to provide scoped OpenRouter chat completion defaults or per-operation
52 * overrides for an OpenRouter language model service.
53 *
54 * @see {@link withConfigOverride} for scoping language model request overrides
55 *
56 * @stability unstable
57 * @category services
58 * @since 4.0.0
59 */
60 export class Config extends Context.Service<
61 Config,
62 Simplify<
63 & Partial<
64 Omit<
65 typeof Generated.ChatRequest.Encoded,
66 "messages" | "response_format" | "tools" | "tool_choice" | "stream" | "stream_options"
67 >
68 >
69 & {
70 /**
71 * Whether to use strict JSON schema validation for structured outputs.
72 *
73 * For schema-backed response formats, defaults to `true` when the selected
74 * schema transformer is the OpenAI transformer (`openai/`, `gpt-`, `o1-`,
75 * `o3-`, and `o4-` model prefixes). Other models, including Anthropic models,
76 * send `strict: null` by default, leaving strictness unspecified. Explicit
77 * `true` or `false` overrides either default. This does not affect tool
78 * strictness.
79 *
80 * **Gotchas**
81 *
82 * Transformer selection is not an endpoint-capability check. Support and
83 * enforcement depend on the selected model and provider. For incompatible
84 * endpoints, set `false` to opt out of the strict default. Strict mode may
85 * restrict supported JSON Schema features; see OpenRouter
86 * [structured output guidance](https://openrouter.ai/docs/guides/features/structured-outputs).
87 */
88 readonly strictJsonSchema?: boolean | undefined
89 }
90 >
91 >()("@effect/ai-openrouter/OpenRouterLanguageModel/Config") {}
92
93 // =============================================================================
94 // Provider Options / Metadata
95 // =============================================================================
96
97 /**
98 * OpenRouter assistant reasoning detail blocks preserved for multi-turn
99 * conversations.
100 *
101 * @stability unstable
102 * @category models
103 * @since 4.0.0
104 */
105 export type ReasoningDetails = Exclude<typeof Generated.ChatAssistantMessage.Encoded["reasoning_details"], undefined>
106
107 /**
108 * File annotations emitted on OpenRouter assistant messages and exposed in
109 * finish metadata.
110 *
111 * @stability unstable
112 * @category models
113 * @since 4.0.0
114 */
115 export type FileAnnotation = Extract<
116 NonNullable<typeof Generated.ChatAssistantMessage.fields.annotations.Type>[number],
117 { type: "file" }
118 >
119
120 declare module "effect/ai/Prompt" {
121 /**
122 * OpenRouter-specific options for system messages.
123 *
124 * **Details**
125 *
126 * These options are used when translating system instructions into
127 * OpenRouter chat messages.
128 *
129 * @stability unstable
130 * @category models
131 * @since 4.0.0
132 */
133 export interface SystemMessageOptions extends ProviderOptions {
134 /**
135 * Provider-specific options sent to OpenRouter for the system message.
136 */
137 readonly openrouter?: {
138 /**
139 * A breakpoint which marks the end of reusable content eligible for caching.
140 */
141 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
142 } | null
143 }
144
145 /**
146 * OpenRouter-specific options for user messages.
147 *
148 * **Details**
149 *
150 * These options are used when translating user content into OpenRouter chat
151 * messages.
152 *
153 * @stability unstable
154 * @category models
155 * @since 4.0.0
156 */
157 export interface UserMessageOptions extends ProviderOptions {
158 /**
159 * Provider-specific options sent to OpenRouter for the user message.
160 */
161 readonly openrouter?: {
162 /**
163 * A breakpoint which marks the end of reusable content eligible for caching.
164 */
165 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
166 } | null
167 }
168
169 /**
170 * OpenRouter-specific options for assistant messages.
171 *
172 * **Details**
173 *
174 * Preserves reasoning metadata when assistant messages are replayed in later
175 * OpenRouter requests.
176 *
177 * @stability unstable
178 * @category models
179 * @since 4.0.0
180 */
181 export interface AssistantMessageOptions extends ProviderOptions {
182 /**
183 * Provider-specific options sent to OpenRouter for the assistant message.
184 */
185 readonly openrouter?: {
186 /**
187 * A breakpoint which marks the end of reusable content eligible for caching.
188 */
189 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
190 /**
191 * Reasoning details associated with the assistant message.
192 */
193 readonly reasoningDetails?: ReasoningDetails | null
194 } | null
195 }
196
197 /**
198 * OpenRouter-specific options for tool messages.
199 *
200 * **Details**
201 *
202 * These options are used when converting tool results into OpenRouter chat
203 * messages.
204 *
205 * @stability unstable
206 * @category models
207 * @since 4.0.0
208 */
209 export interface ToolMessageOptions extends ProviderOptions {
210 /**
211 * Provider-specific options sent to OpenRouter for the tool message.
212 */
213 readonly openrouter?: {
214 /**
215 * A breakpoint which marks the end of reusable content eligible for caching.
216 */
217 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
218 } | null
219 }
220
221 /**
222 * OpenRouter-specific options for text prompt parts.
223 *
224 * **When to use**
225 *
226 * Use when you use these options to control how text content is sent to OpenRouter.
227 *
228 * @stability unstable
229 * @category models
230 * @since 4.0.0
231 */
232 export interface TextPartOptions extends ProviderOptions {
233 /**
234 * Provider-specific options sent to OpenRouter for the text part.
235 */
236 readonly openrouter?: {
237 /**
238 * A breakpoint which marks the end of reusable content eligible for caching.
239 */
240 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
241 } | null
242 }
243
244 /**
245 * OpenRouter-specific options for reasoning prompt parts.
246 *
247 * **Details**
248 *
249 * Preserves provider reasoning blocks so reasoning-aware conversations can
250 * continue across OpenRouter requests.
251 *
252 * @stability unstable
253 * @category models
254 * @since 4.0.0
255 */
256 export interface ReasoningPartOptions extends ProviderOptions {
257 /**
258 * Provider-specific options sent to OpenRouter for the reasoning part.
259 */
260 readonly openrouter?: {
261 /**
262 * A breakpoint which marks the end of reusable content eligible for caching.
263 */
264 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
265 /**
266 * Reasoning details associated with the reasoning part.
267 */
268 readonly reasoningDetails?: ReasoningDetails | null
269 } | null
270 }
271
272 /**
273 * OpenRouter-specific options for file prompt parts.
274 *
275 * **Details**
276 *
277 * Controls file naming and prompt caching for files sent to OpenRouter.
278 *
279 * @stability unstable
280 * @category models
281 * @since 4.0.0
282 */
283 export interface FilePartOptions extends ProviderOptions {
284 /**
285 * Provider-specific options sent to OpenRouter for the file part.
286 */
287 readonly openrouter?: {
288 /**
289 * The name to give to the file. Will be prioritized over the file name
290 * associated with the file part, if present.
291 */
292 readonly fileName?: string | null
293 /**
294 * A breakpoint which marks the end of reusable content eligible for caching.
295 */
296 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
297 } | null
298 }
299
300 /**
301 * OpenRouter-specific options for tool call prompt parts.
302 *
303 * **Details**
304 *
305 * Preserves reasoning details associated with tool calls when a conversation
306 * is sent back to OpenRouter.
307 *
308 * @stability unstable
309 * @category models
310 * @since 4.0.0
311 */
312 export interface ToolCallPartOptions extends ProviderOptions {
313 /**
314 * Provider-specific options sent to OpenRouter for the tool call part.
315 */
316 readonly openrouter?: {
317 /**
318 * Reasoning details associated with the tool call part.
319 */
320 readonly reasoningDetails?: ReasoningDetails | null
321 } | null
322 }
323
324 /**
325 * OpenRouter-specific options for tool result prompt parts.
326 *
327 * **Details**
328 *
329 * Controls prompt caching for tool results sent to OpenRouter.
330 *
331 * @stability unstable
332 * @category models
333 * @since 4.0.0
334 */
335 export interface ToolResultPartOptions extends ProviderOptions {
336 /**
337 * Provider-specific options sent to OpenRouter for the tool result part.
338 */
339 readonly openrouter?: {
340 /**
341 * A breakpoint which marks the end of reusable content eligible for caching.
342 */
343 readonly cacheControl?: typeof Generated.ChatContentCacheControl.Encoded | null
344 } | null
345 }
346 }
347
348 declare module "effect/ai/Response" {
349 /**
350 * OpenRouter metadata attached to completed reasoning response parts.
351 *
352 * **Details**
353 *
354 * Preserves provider reasoning details that can be sent back in later turns.
355 *
356 * @stability unstable
357 * @category models
358 * @since 4.0.0
359 */
360 export interface ReasoningPartMetadata extends ProviderMetadata {
361 /**
362 * Provider-specific metadata returned for the reasoning part.
363 */
364 readonly openrouter?: {
365 /**
366 * Reasoning details emitted by the underlying provider for this part.
367 */
368 readonly reasoningDetails?: ReasoningDetails | null
369 } | null
370 }
371
372 /**
373 * OpenRouter metadata emitted when a streamed reasoning part starts.
374 *
375 * **Details**
376 *
377 * Carries the first reasoning detail chunk when OpenRouter exposes one.
378 *
379 * @stability unstable
380 * @category models
381 * @since 4.0.0
382 */
383 export interface ReasoningStartPartMetadata extends ProviderMetadata {
384 /**
385 * Provider-specific metadata returned for the streamed reasoning start.
386 */
387 readonly openrouter?: {
388 /**
389 * Reasoning details emitted by the underlying provider for this part.
390 */
391 readonly reasoningDetails?: ReasoningDetails | null
392 } | null
393 }
394
395 /**
396 * OpenRouter metadata emitted for streamed reasoning deltas.
397 *
398 * **Details**
399 *
400 * Carries provider reasoning detail chunks as they arrive from OpenRouter.
401 *
402 * @stability unstable
403 * @category models
404 * @since 4.0.0
405 */
406 export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
407 /**
408 * Provider-specific metadata returned for the streamed reasoning delta.
409 */
410 readonly openrouter?: {
411 /**
412 * Reasoning details emitted by the underlying provider for this delta.
413 */
414 readonly reasoningDetails?: ReasoningDetails | null
415 } | null
416 }
417
418 /**
419 * OpenRouter metadata attached to tool-call response parts.
420 *
421 * **Details**
422 *
423 * Associates tool calls with provider reasoning details when the model emits
424 * reasoning and tool calls together.
425 *
426 * @stability unstable
427 * @category models
428 * @since 4.0.0
429 */
430 export interface ToolCallPartMetadata extends ProviderMetadata {
431 /**
432 * Provider-specific metadata returned for the tool call.
433 */
434 readonly openrouter?: {
435 /**
436 * Reasoning details associated with this tool call.
437 */
438 readonly reasoningDetails?: ReasoningDetails | null
439 } | null
440 }
441
442 /**
443 * OpenRouter metadata attached to URL source citations.
444 *
445 * **Details**
446 *
447 * Includes citation text and offsets returned by providers that support URL
448 * annotations.
449 *
450 * @stability unstable
451 * @category models
452 * @since 4.0.0
453 */
454 export interface UrlSourcePartMetadata extends ProviderMetadata {
455 /**
456 * Provider-specific citation metadata returned for the URL source.
457 */
458 readonly openrouter?: {
459 /**
460 * The cited source content returned by the provider.
461 */
462 readonly content?: string | null
463 /**
464 * The zero-based start index of the citation in the generated text.
465 */
466 readonly startIndex?: number | null
467 /**
468 * The zero-based end index of the citation in the generated text.
469 */
470 readonly endIndex?: number | null
471 } | null
472 }
473
474 /**
475 * OpenRouter metadata attached to finish response parts.
476 *
477 * **Details**
478 *
479 * Exposes provider response details that are not represented by the common
480 * Effect AI finish part fields.
481 *
482 * @stability unstable
483 * @category models
484 * @since 4.0.0
485 */
486 export interface FinishPartMetadata extends ProviderMetadata {
487 /**
488 * Provider-specific metadata returned when the OpenRouter response finishes.
489 */
490 readonly openrouter?: {
491 /**
492 * Provider fingerprint for the backend configuration that served the request.
493 */
494 readonly systemFingerprint?: string | null
495 /**
496 * Raw token usage reported by OpenRouter.
497 */
498 readonly usage?: typeof Generated.ChatUsage.Encoded | null
499 /**
500 * File annotations returned by the provider.
501 */
502 readonly annotations?: ReadonlyArray<FileAnnotation> | null
503 /**
504 * The OpenRouter provider that served the request, when reported.
505 */
506 readonly provider?: string | null
507 } | null
508 }
509 }
510
511 // =============================================================================
512 // Language Model
513 // =============================================================================
514
515 /**
516 * Creates an OpenRouter model descriptor that can be provided with
517 * `Effect.provide`.
518 *
519 * **When to use**
520 *
521 * Use when you want an OpenRouter language model value that carries provider
522 * and model metadata and can be supplied directly to an Effect program.
523 *
524 * **Details**
525 *
526 * The returned model requires `OpenRouterClient` and provides
527 * `LanguageModel.LanguageModel`.
528 *
529 * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
530 * @see {@link make} for constructing the language model service effectfully
531 * @see {@link withConfigOverride} for scoping OpenRouter request overrides
532 *
533 * @stability unstable
534 * @category constructors
535 * @since 4.0.0
536 */
537 export const model = (
538 model: string,
539 config?: Omit<typeof Config.Service, "model">
540 ): AiModel.Model<"openrouter", LanguageModel.LanguageModel, OpenRouterClient> =>
541 AiModel.make("openrouter", model, layer({ model, config }))
542
543 /**
544 * Creates an OpenRouter `LanguageModel` service from a model identifier and
545 * optional request defaults.
546 *
547 * **When to use**
548 *
549 * Use when you need to construct a `LanguageModel` value backed by
550 * `OpenRouterClient` inside an Effect.
551 *
552 * **Details**
553 *
554 * The returned effect requires `OpenRouterClient`. Request defaults from the
555 * `config` option are merged with any `Config` service in the context, with
556 * context values taking precedence. The service supports both `generateText`
557 * and `streamText`.
558 *
559 * **Gotchas**
560 *
561 * Provider-defined tools are not supported by this provider integration;
562 * requests that include them fail with an `InvalidUserInputError`.
563 *
564 * @see {@link layer} for providing the service as a `Layer`
565 * @see {@link model} for creating a model descriptor for `Effect.provide`
566 * @see {@link withConfigOverride} for scoping request defaults around operations
567 *
568 * @stability unstable
569 * @category constructors
570 * @since 4.0.0
571 */
572 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
573 readonly model: string
574 readonly config?: Omit<typeof Config.Service, "model"> | undefined
575 }): Effect.fn.Return<LanguageModel.LanguageModel, never, OpenRouterClient> {
576 const client = yield* OpenRouterClient
577 const codecTransformer = getCodecTransformer(model)
578
579 const makeConfig = Effect.contextWith((services: Context.Context<never>) =>
580 Effect.succeed({ model, ...providerConfig, ...Context.getOrUndefined(services, Config) })
581 )
582
583 const makeRequest = Effect.fnUntraced(
584 function*({ config, options }: {
585 readonly config: typeof Config.Service
586 readonly options: LanguageModel.ProviderOptions
587 }): Effect.fn.Return<typeof Generated.ChatRequest.Encoded, AiError.AiError> {
588 const messages = yield* prepareMessages({ options })
589 const { tools, toolChoice } = yield* prepareTools({ options, transformer: codecTransformer })
590 const responseFormat = yield* getResponseFormat({ config, options, transformer: codecTransformer })
591 const { strictJsonSchema: _sjs, ...apiConfig } = config
592 const request: typeof Generated.ChatRequest.Encoded = {
593 ...apiConfig,
594 messages,
595 ...(Predicate.isNotUndefined(responseFormat) ? { response_format: responseFormat } : undefined),
596 ...(Predicate.isNotUndefined(tools) ? { tools } : undefined),
597 ...(Predicate.isNotUndefined(toolChoice) ? { tool_choice: toolChoice } : undefined)
598 }
599 return request
600 }
601 )
602
603 return yield* LanguageModel.make({
604 codecTransformer: toCodecOpenAI,
605 generateText: Effect.fnUntraced(
606 function*(options) {
607 const config = yield* makeConfig
608 const request = yield* makeRequest({ config, options })
609 annotateRequest(options.span, request)
610 const [rawResponse, response] = yield* client.createChatCompletion(request)
611 annotateResponse(options.span, rawResponse)
612 return yield* makeResponse({ rawResponse, response })
613 }
614 ),
615 streamText: Effect.fnUntraced(
616 function*(options) {
617 const config = yield* makeConfig
618 const request = yield* makeRequest({ config, options })
619 annotateRequest(options.span, request)
620 const [response, stream] = yield* client.createChatCompletionStream(request)
621 return yield* makeStreamResponse({ response, stream })
622 },
623 (effect, options) =>
624 effect.pipe(
625 Stream.unwrap,
626 Stream.map((response) => {
627 annotateStreamResponse(options.span, response)
628 return response
629 })
630 )
631 )
632 })
633 })
634
635 /**
636 * Creates a layer for the OpenRouter language model.
637 *
638 * **When to use**
639 *
640 * Use when composing application layers and you want OpenRouter to satisfy
641 * `LanguageModel.LanguageModel` while supplying `OpenRouterClient` from another
642 * layer.
643 *
644 * @see {@link make} for constructing the language model service effectfully
645 * @see {@link model} for creating a model descriptor for `Effect.provide`
646 *
647 * @stability unstable
648 * @category layers
649 * @since 4.0.0
650 */
651 export const layer = (options: {
652 readonly model: string
653 readonly config?: Omit<typeof Config.Service, "model"> | undefined
654 }): Layer.Layer<LanguageModel.LanguageModel, never, OpenRouterClient> =>
655 Layer.effect(LanguageModel.LanguageModel, make(options))
656
657 /**
658 * Provides config overrides for OpenRouter language model operations.
659 *
660 * **When to use**
661 *
662 * Use to apply OpenRouter request configuration to one effect without changing
663 * the model's default configuration.
664 *
665 * **Details**
666 *
667 * The overrides are merged with any existing `Config` service for the duration
668 * of the supplied effect. Fields in `overrides` take precedence over existing
669 * config, and the helper supports both pipe form and
670 * `withConfigOverride(effect, overrides)`.
671 *
672 * @see {@link Config} for available OpenRouter request configuration fields
673 *
674 * @stability unstable
675 * @category configuration
676 * @since 4.0.0
677 */
678 export const withConfigOverride: {
679 (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
680 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
681 } = dual<
682 (
683 overrides: typeof Config.Service
684 ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
685 <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
686 >(2, (self, overrides) =>
687 Effect.flatMap(
688 Effect.serviceOption(Config),
689 (config) =>
690 Effect.provideService(self, Config, {
691 ...(config._tag === "Some" ? config.value : {}),
692 ...overrides
693 })
694 ))
695
696 // =============================================================================
697 // Prompt Conversion
698 // =============================================================================
699
700 const prepareMessages = Effect.fnUntraced(
701 function*({ options }: {
702 readonly options: LanguageModel.ProviderOptions
703 }): Effect.fn.Return<ReadonlyArray<typeof Generated.ChatMessages.Encoded>, AiError.AiError> {
704 const messages: Array<typeof Generated.ChatMessages.Encoded> = []
705
706 const reasoningDetailsTracker = new ReasoningDetailsDuplicateTracker()
707
708 for (const message of options.prompt.content) {
709 switch (message.role) {
710 case "system": {
711 const cache_control = getCacheControl(message)
712
713 messages.push({
714 role: "system",
715 content: [{
716 type: "text",
717 text: message.content,
718 ...(Predicate.isNotNull(cache_control) ? { cache_control } : undefined)
719 }]
720 })
721
722 break
723 }
724
725 case "user": {
726 const content: Array<typeof Generated.ChatContentItems.Encoded> = []
727
728 // Get the message-level cache control
729 const messageCacheControl = getCacheControl(message)
730
731 if (message.content.length === 1 && message.content[0].type === "text") {
732 messages.push({
733 role: "user",
734 content: Predicate.isNotNull(messageCacheControl)
735 ? [{ type: "text", text: message.content[0].text, cache_control: messageCacheControl }]
736 : message.content[0].text
737 })
738
739 break
740 }
741
742 // Find the index of the last text part in the message content
743 let lastTextPartIndex = -1
744 for (let i = message.content.length - 1; i >= 0; i--) {
745 if (message.content[i].type === "text") {
746 lastTextPartIndex = i
747 break
748 }
749 }
750
751 for (let index = 0; index < message.content.length; index++) {
752 const part = message.content[index]
753 const isLastTextPart = part.type === "text" && index === lastTextPartIndex
754 const partCacheControl = getCacheControl(part)
755
756 switch (part.type) {
757 case "text": {
758 const cache_control = Predicate.isNotNull(partCacheControl)
759 ? partCacheControl
760 : isLastTextPart
761 ? messageCacheControl
762 : null
763
764 content.push({
765 type: "text",
766 text: part.text,
767 ...(Predicate.isNotNull(cache_control) ? { cache_control } : undefined)
768 })
769
770 break
771 }
772
773 case "file": {
774 if (part.mediaType.startsWith("image/")) {
775 const mediaType = part.mediaType === "image/*" ? "image/jpeg" : part.mediaType
776
777 content.push({
778 type: "image_url",
779 image_url: {
780 url: part.data instanceof URL
781 ? part.data.toString()
782 : part.data instanceof Uint8Array
783 ? `data:${mediaType};base64,${Base64.encode(part.data)}`
784 : part.data
785 },
786 ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
787 })
788
789 break
790 }
791
792 if (part.mediaType.startsWith("audio/")) {
793 const format = audioFormats[part.mediaType.toLowerCase()]
794
795 if (Predicate.isUndefined(format)) {
796 return yield* AiError.make({
797 module: "OpenRouterLanguageModel",
798 method: "prepareMessages",
799 reason: new AiError.InvalidUserInputError({
800 description: `Detected unsupported media type for audio file: '${part.mediaType}' ` +
801 `- OpenRouter supports ${supportedAudioFormats} audio`
802 })
803 })
804 }
805
806 if (part.data instanceof URL) {
807 return yield* AiError.make({
808 module: "OpenRouterLanguageModel",
809 method: "prepareMessages",
810 reason: new AiError.InvalidUserInputError({
811 description: "Detected URL data for audio file - OpenRouter requires " +
812 "audio to be provided as base64-encoded data"
813 })
814 })
815 }
816
817 content.push({
818 type: "input_audio",
819 input_audio: {
820 data: part.data instanceof Uint8Array
821 ? Base64.encode(part.data)
822 : getBase64FromDataUrl(part.data),
823 format
824 },
825 ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
826 })
827
828 break
829 }
830
831 const options = part.options.openrouter
832 const fileName = options?.fileName ?? part.fileName ?? ""
833
834 content.push({
835 type: "file",
836 file: {
837 filename: fileName,
838 file_data: part.data instanceof URL
839 ? part.data.toString()
840 : part.data instanceof Uint8Array
841 ? `data:${part.mediaType};base64,${Base64.encode(part.data)}`
842 : part.data
843 },
844 ...(Predicate.isNotNull(partCacheControl) ? { cache_control: partCacheControl } : undefined)
845 } as any)
846
847 break
848 }
849 }
850 }
851
852 messages.push({ role: "user", content })
853
854 break
855 }
856
857 case "assistant": {
858 let reasoning = ""
859 const textParts: Array<Prompt.TextPart> = []
860 const toolCalls: Array<typeof Generated.ChatToolCall.Encoded> = []
861
862 for (const part of message.content) {
863 switch (part.type) {
864 case "text": {
865 if (part.text.length > 0) {
866 textParts.push(part)
867 }
868 break
869 }
870
871 case "reasoning": {
872 reasoning += part.text
873 break
874 }
875
876 case "tool-call": {
877 toolCalls.push({
878 type: "function",
879 id: part.id,
880 function: { name: part.name, arguments: JSON.stringify(part.params) }
881 })
882 break
883 }
884
885 default: {
886 break
887 }
888 }
889 }
890
891 const messageReasoningDetails = message.options.openrouter?.reasoningDetails
892
893 // Use message-level reasoning details if available, otherwise find from parts
894 // Priority: message-level > first tool call > first reasoning part
895 // This prevents duplicate thinking blocks when Claude makes parallel tool calls
896 const candidateReasoningDetails: ReasoningDetails | null = Predicate.isNotNullish(messageReasoningDetails)
897 && Array.isArray(messageReasoningDetails)
898 && messageReasoningDetails.length > 0
899 ? messageReasoningDetails
900 : findFirstReasoningDetails(message.content)
901
902 // Deduplicate reasoning details across all messages to prevent "Duplicate
903 // item found with id" errors in multi-turn conversations.
904 let reasoningDetails: ReasoningDetails | null = null
905 if (Predicate.isNotNull(candidateReasoningDetails) && candidateReasoningDetails.length > 0) {
906 const uniqueReasoningDetails: Mutable<ReasoningDetails> = []
907 for (const detail of candidateReasoningDetails) {
908 if (reasoningDetailsTracker.upsert(detail)) {
909 uniqueReasoningDetails.push(detail)
910 }
911 }
912 if (uniqueReasoningDetails.length > 0) {
913 reasoningDetails = uniqueReasoningDetails
914 }
915 }
916
917 // Tool calls cannot carry cache breakpoints; use the last text part.
918 const messageCacheControl = getCacheControl(message)
919 const content = textParts.map<typeof Generated.ChatContentText.Encoded>((part, i) => {
920 const cache_control = getCacheControl(part) ?? (i === textParts.length - 1 ? messageCacheControl : null)
921 return {
922 type: "text",
923 text: part.text,
924 ...(Predicate.isNotNull(cache_control) ? { cache_control } : undefined)
925 }
926 })
927
928 messages.push({
929 role: "assistant",
930 content: content.some((part) => Predicate.isNotNullish(part.cache_control))
931 ? content
932 : content.map((part) => part.text).join(""),
933 reasoning: reasoning.length > 0 ? reasoning : null,
934 ...(Predicate.isNotNull(reasoningDetails) ? { reasoning_details: reasoningDetails } : undefined),
935 ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : undefined)
936 })
937
938 break
939 }
940
941 case "tool": {
942 const results = message.content.filter((part) => part.type === "tool-result")
943 const messageCacheControl = getCacheControl(message)
944
945 for (let i = 0; i < results.length; i++) {
946 const part = results[i]
947 const text = Predicate.isNotUndefined(part.modelOutput)
948 ? Prompt.toolModelOutputToText(part.modelOutput)
949 : typeof part.result === "string"
950 ? part.result
951 : JSON.stringify(part.result)
952 const cache_control = getCacheControl(part) ?? (i === results.length - 1 ? messageCacheControl : null)
953
954 messages.push({
955 role: "tool",
956 tool_call_id: part.id,
957 content: Predicate.isNotNull(cache_control) && typeof text === "string" && text.length > 0
958 ? [{ type: "text", text, cache_control }]
959 : text
960 })
961 }
962
963 break
964 }
965 }
966 }
967
968 return messages
969 }
970 )
971
972 // =============================================================================
973 // HTTP Details
974 // =============================================================================
975
976 const buildHttpResponseDetails = (
977 response: HttpClientResponse.HttpClientResponse
978 ): typeof Response.HttpResponseDetails.Type => ({
979 status: response.status,
980 headers: Redactable.redact(response.headers) as Record<string, string>
981 })
982
983 // =============================================================================
984 // Response Conversion
985 // =============================================================================
986
987 const makeResponse = Effect.fnUntraced(
988 function*({ rawResponse, response }: {
989 readonly rawResponse: Generated.SendChatCompletionRequest200
990 readonly response: HttpClientResponse.HttpClientResponse
991 }): Effect.fn.Return<Array<Response.PartEncoded>, AiError.AiError, IdGenerator.IdGenerator> {
992 const idGenerator = yield* IdGenerator.IdGenerator
993
994 const parts: Array<Response.PartEncoded> = []
995 let hasToolCalls = false
996 let hasEncryptedReasoning = false
997
998 const createdAt = new Date(rawResponse.created * 1000)
999 parts.push({
1000 type: "response-metadata",
1001 id: rawResponse.id,
1002 modelId: rawResponse.model,
1003 timestamp: DateTime.formatIso(DateTime.fromDateUnsafe(createdAt))
1004 })
1005
1006 const choice = rawResponse.choices[0]
1007 if (Predicate.isUndefined(choice)) {
1008 return yield* AiError.make({
1009 module: "OpenRouterLanguageModel",
1010 method: "makeResponse",
1011 reason: new AiError.InvalidOutputError({
1012 description: "Received response with empty choices"
1013 })
1014 })
1015 }
1016
1017 const message = choice.message
1018 let finishReason = choice.finish_reason
1019
1020 const reasoningDetails = message.reasoning_details
1021 if (Predicate.isNotNullish(reasoningDetails) && reasoningDetails.length > 0) {
1022 for (const detail of reasoningDetails) {
1023 switch (detail.type) {
1024 case "reasoning.text": {
1025 if (Predicate.isNotNullish(detail.text) && detail.text.length > 0) {
1026 parts.push({
1027 type: "reasoning",
1028 text: detail.text,
1029 metadata: { openrouter: { reasoningDetails: [detail] } }
1030 })
1031 }
1032 break
1033 }
1034 case "reasoning.summary": {
1035 if (detail.summary.length > 0) {
1036 parts.push({
1037 type: "reasoning",
1038 text: detail.summary,
1039 metadata: { openrouter: { reasoningDetails: [detail] } }
1040 })
1041 }
1042 break
1043 }
1044 case "reasoning.encrypted": {
1045 if (detail.data.length > 0) {
1046 hasEncryptedReasoning = true
1047 parts.push({
1048 type: "reasoning",
1049 text: "[REDACTED]",
1050 metadata: { openrouter: { reasoningDetails: [detail] } }
1051 })
1052 }
1053 break
1054 }
1055 }
1056 }
1057 } else if (Predicate.isNotNullish(message.reasoning) && message.reasoning.length > 0) {
1058 // message.reasoning fallback only when reasoning_details absent/empty
1059 parts.push({
1060 type: "reasoning",
1061 text: message.reasoning
1062 })
1063 }
1064
1065 const content = message.content
1066 if (Predicate.isNotNullish(content)) {
1067 if (typeof content === "string") {
1068 if (content.length > 0) {
1069 parts.push({ type: "text", text: content })
1070 }
1071 } else {
1072 for (const item of content) {
1073 if (item.type === "text") {
1074 parts.push({ type: "text", text: item.text })
1075 }
1076 }
1077 }
1078 }
1079
1080 const toolCalls = message.tool_calls
1081 if (Predicate.isNotNullish(toolCalls) && toolCalls.length > 0) {
1082 hasToolCalls = true
1083 for (let index = 0; index < toolCalls.length; index++) {
1084 const toolCall = toolCalls[index]
1085 const toolName = toolCall.function.name
1086 const toolParams = toolCall.function.arguments ?? "{}"
1087 const params = yield* Effect.try({
1088 try: () => Tool.unsafeSecureJsonParse(toolParams),
1089 catch: (cause) =>
1090 AiError.make({
1091 module: "OpenRouterLanguageModel",
1092 method: "makeResponse",
1093 reason: new AiError.ToolParameterValidationError({
1094 toolName,
1095 description: `Failed to securely JSON parse tool parameters: ${cause}`
1096 })
1097 })
1098 })
1099 parts.push({
1100 type: "tool-call",
1101 id: toolCall.id,
1102 name: toolName,
1103 params,
1104 // Only attach reasoning_details to the first tool call to avoid
1105 // duplicating thinking blocks for parallel tool calls (Claude)
1106 ...(index === 0 && Predicate.isNotNullish(reasoningDetails) && reasoningDetails.length > 0
1107 ? { metadata: { openrouter: { reasoningDetails } } }
1108 : undefined)
1109 })
1110 }
1111 }
1112
1113 const images = message.images
1114 if (Predicate.isNotNullish(images)) {
1115 for (const image of images) {
1116 const url = image.image_url.url
1117 if (url.startsWith("data:")) {
1118 const mediaType = getMediaType(url, "image/jpeg")
1119 const data = getBase64FromDataUrl(url)
1120 parts.push({ type: "file", mediaType, data })
1121 } else {
1122 const id = yield* idGenerator.generateId()
1123 parts.push({ type: "source", sourceType: "url", id, url, title: "" })
1124 }
1125 }
1126 }
1127
1128 const annotations = choice.message.annotations
1129 if (Predicate.isNotNullish(annotations)) {
1130 for (const annotation of annotations) {
1131 if (annotation.type === "url_citation") {
1132 parts.push({
1133 type: "source",
1134 sourceType: "url",
1135 id: annotation.url_citation.url,
1136 url: annotation.url_citation.url,
1137 title: annotation.url_citation.title ?? "",
1138 metadata: {
1139 openrouter: {
1140 ...(Predicate.isNotUndefined(annotation.url_citation.content)
1141 ? { content: annotation.url_citation.content }
1142 : undefined),
1143 ...(Predicate.isNotUndefined(annotation.url_citation.start_index)
1144 ? { startIndex: annotation.url_citation.start_index }
1145 : undefined),
1146 ...(Predicate.isNotUndefined(annotation.url_citation.end_index)
1147 ? { endIndex: annotation.url_citation.end_index }
1148 : undefined)
1149 }
1150 }
1151 })
1152 }
1153 }
1154 }
1155
1156 // Extract file annotations to expose in provider metadata
1157 const fileAnnotations = annotations?.filter((annotation) => {
1158 return annotation.type === "file"
1159 })
1160
1161 // Fix for Gemini 3 thoughtSignature: when there are tool calls with encrypted
1162 // reasoning (thoughtSignature), the model returns 'stop' but expects continuation.
1163 // Override to 'tool-calls' so the SDK knows to continue the conversation.
1164 if (hasEncryptedReasoning && hasToolCalls && finishReason === "stop") {
1165 finishReason = "tool_calls"
1166 }
1167
1168 parts.push({
1169 type: "finish",
1170 reason: resolveFinishReason(finishReason),
1171 usage: getUsage(rawResponse.usage),
1172 response: buildHttpResponseDetails(response),
1173 metadata: {
1174 openrouter: {
1175 systemFingerprint: rawResponse.system_fingerprint ?? null,
1176 usage: rawResponse.usage ?? null,
1177 ...(Predicate.isNotUndefined(fileAnnotations) && fileAnnotations.length > 0
1178 ? { annotations: fileAnnotations }
1179 : undefined),
1180 ...(Predicate.hasProperty(rawResponse, "provider") && Predicate.isString(rawResponse.provider)
1181 ? { provider: rawResponse.provider }
1182 : undefined)
1183 }
1184 }
1185 })
1186
1187 return parts
1188 }
1189 )
1190
1191 const makeStreamResponse = Effect.fnUntraced(
1192 function*({ response, stream }: {
1193 readonly response: HttpClientResponse.HttpClientResponse
1194 readonly stream: Stream.Stream<ChatStreamingResponseChunkData, AiError.AiError>
1195 }): Effect.fn.Return<
1196 Stream.Stream<Response.StreamPartEncoded, AiError.AiError>,
1197 AiError.AiError,
1198 IdGenerator.IdGenerator
1199 > {
1200 const idGenerator = yield* IdGenerator.IdGenerator
1201
1202 let textStarted = false
1203 let reasoningStarted = false
1204 let responseMetadataEmitted = false
1205 let reasoningDetailsAttachedToToolCall = false
1206 let finishReason: Response.FinishReason = "other"
1207 let openRouterResponseId: string | undefined = undefined
1208 let activeReasoningId: string | undefined = undefined
1209 let activeTextId: string | undefined = undefined
1210
1211 let totalToolCalls = 0
1212 const activeToolCalls: Record<number, {
1213 readonly id: string
1214 readonly type: "function"
1215 readonly name: string
1216 params: string
1217 }> = {}
1218
1219 // Track reasoning details to preserve for multi-turn conversations
1220 const accumulatedReasoningDetails: DeepMutable<ReasoningDetails> = []
1221
1222 // Track file annotations to expose in provider metadata
1223 const accumulatedFileAnnotations: Array<FileAnnotation> = []
1224
1225 const usage: DeepMutable<Response.Usage> = {
1226 inputTokens: {
1227 total: undefined,
1228 uncached: undefined,
1229 cacheRead: undefined,
1230 cacheWrite: undefined
1231 },
1232 outputTokens: {
1233 total: undefined,
1234 text: undefined,
1235 reasoning: undefined
1236 }
1237 }
1238
1239 return stream.pipe(
1240 Stream.mapEffect(Effect.fnUntraced(function*(event) {
1241 const parts: Array<Response.StreamPartEncoded> = []
1242
1243 if (Predicate.isNotUndefined(event.error)) {
1244 finishReason = "error"
1245 parts.push({ type: "error", error: event.error })
1246 }
1247
1248 if (Predicate.isNotUndefined(event.id) && !responseMetadataEmitted) {
1249 const timestamp = yield* DateTime.now
1250 parts.push({
1251 type: "response-metadata",
1252 id: event.id,
1253 modelId: event.model,
1254 timestamp: DateTime.formatIso(timestamp)
1255 })
1256 responseMetadataEmitted = true
1257 }
1258
1259 if (Predicate.isNotUndefined(event.usage)) {
1260 const computed = getUsage(event.usage)
1261 usage.inputTokens = computed.inputTokens
1262 usage.outputTokens = computed.outputTokens
1263 }
1264
1265 const choice = event.choices[0]
1266 if (Predicate.isNotUndefined(choice)) {
1267 if (Predicate.isNotNullish(choice.finish_reason)) {
1268 finishReason = resolveFinishReason(choice.finish_reason)
1269 }
1270
1271 const delta = choice.delta
1272 if (Predicate.isNullish(delta)) {
1273 return parts
1274 }
1275
1276 const emitReasoning = Effect.fnUntraced(
1277 function*(delta: string, metadata?: Response.ReasoningDeltaPart["metadata"] | undefined) {
1278 if (!reasoningStarted) {
1279 activeReasoningId = openRouterResponseId ?? (yield* idGenerator.generateId())
1280 parts.push({
1281 type: "reasoning-start",
1282 id: activeReasoningId,
1283 metadata
1284 })
1285 reasoningStarted = true
1286 }
1287 parts.push({
1288 type: "reasoning-delta",
1289 id: activeReasoningId!,
1290 delta,
1291 metadata
1292 })
1293 }
1294 )
1295
1296 const reasoningDetails = delta.reasoning_details
1297 if (Predicate.isNotUndefined(reasoningDetails) && reasoningDetails.length > 0) {
1298 // Accumulate reasoning_details to preserve for multi-turn conversations
1299 // Merge consecutive reasoning.text items into a single entry
1300 for (const detail of reasoningDetails) {
1301 if (detail.type === "reasoning.text") {
1302 const lastDetail = accumulatedReasoningDetails[accumulatedReasoningDetails.length - 1]
1303 if (Predicate.isNotUndefined(lastDetail) && lastDetail.type === "reasoning.text") {
1304 // Merge with the previous text detail
1305 lastDetail.text = (lastDetail.text ?? "") + (detail.text ?? "")
1306 lastDetail.signature = lastDetail.signature ?? detail.signature ?? null
1307 lastDetail.format = lastDetail.format ?? detail.format ?? null
1308 } else {
1309 // Start a new text detail
1310 accumulatedReasoningDetails.push({ ...detail })
1311 }
1312 } else {
1313 // Non-text details (encrypted, summary) are pushed as-is
1314 accumulatedReasoningDetails.push(detail)
1315 }
1316 }
1317
1318 // Emit reasoning_details in providerMetadata for each delta chunk
1319 // so users can accumulate them on their end before sending back
1320 const metadata: Response.ReasoningDeltaPart["metadata"] = {
1321 openrouter: {
1322 reasoningDetails
1323 }
1324 }
1325 for (const detail of reasoningDetails) {
1326 switch (detail.type) {
1327 case "reasoning.text": {
1328 if (Predicate.isNotNullish(detail.text)) {
1329 yield* emitReasoning(detail.text, metadata)
1330 }
1331 break
1332 }
1333
1334 case "reasoning.summary": {
1335 if (Predicate.isNotNullish(detail.summary)) {
1336 yield* emitReasoning(detail.summary, metadata)
1337 }
1338 break
1339 }
1340
1341 case "reasoning.encrypted": {
1342 if (Predicate.isNotNullish(detail.data)) {
1343 yield* emitReasoning("[REDACTED]", metadata)
1344 }
1345 break
1346 }
1347 }
1348 }
1349 } else if (Predicate.isNotNullish(delta.reasoning)) {
1350 yield* emitReasoning(delta.reasoning)
1351 }
1352
1353 const content = delta.content
1354 if (Predicate.isNotNullish(content)) {
1355 // If reasoning was previously active and now we're starting text content,
1356 // we should end the reasoning first to maintain proper order
1357 if (reasoningStarted && !textStarted) {
1358 parts.push({
1359 type: "reasoning-end",
1360 id: activeReasoningId!,
1361 // Include accumulated reasoning_details so the we can update the
1362 // reasoning part's provider metadata with the correct signature.
1363 // The signature typically arrives in the last reasoning delta,
1364 // but reasoning-start only carries the first delta's metadata.
1365 metadata: accumulatedReasoningDetails.length > 0
1366 ? { openrouter: { reasoningDetails: accumulatedReasoningDetails } }
1367 : undefined
1368 })
1369 reasoningStarted = false
1370 }
1371
1372 if (!textStarted) {
1373 activeTextId = openRouterResponseId ?? (yield* idGenerator.generateId())
1374 parts.push({
1375 type: "text-start",
1376 id: activeTextId
1377 })
1378 textStarted = true
1379 }
1380
1381 parts.push({
1382 type: "text-delta",
1383 id: activeTextId!,
1384 delta: content
1385 })
1386 }
1387
1388 const annotations = delta.annotations
1389 if (Predicate.isNotNullish(annotations)) {
1390 for (const annotation of annotations) {
1391 if (annotation.type === "url_citation") {
1392 parts.push({
1393 type: "source",
1394 sourceType: "url",
1395 id: annotation.url_citation.url,
1396 url: annotation.url_citation.url,
1397 title: annotation.url_citation.title ?? "",
1398 metadata: {
1399 openrouter: {
1400 ...(Predicate.isNotUndefined(annotation.url_citation.content)
1401 ? { content: annotation.url_citation.content }
1402 : undefined),
1403 ...(Predicate.isNotUndefined(annotation.url_citation.start_index)
1404 ? { startIndex: annotation.url_citation.start_index }
1405 : undefined),
1406 ...(Predicate.isNotUndefined(annotation.url_citation.end_index)
1407 ? { endIndex: annotation.url_citation.end_index }
1408 : undefined)
1409 }
1410 }
1411 })
1412 } else if (annotation.type === "file") {
1413 accumulatedFileAnnotations.push(annotation)
1414 }
1415 }
1416 }
1417
1418 const toolCalls = delta.tool_calls
1419 if (Predicate.isNotNullish(toolCalls)) {
1420 for (const toolCall of toolCalls) {
1421 const index = toolCall.index ?? toolCalls.length - 1
1422 let activeToolCall = activeToolCalls[index]
1423 const argumentsDelta = toolCall.function?.arguments ?? ""
1424
1425 // Tool call start - OpenRouter returns all information except the
1426 // tool call parameters in the first chunk
1427 if (Predicate.isUndefined(activeToolCall)) {
1428 if (toolCall.type !== "function") {
1429 return yield* AiError.make({
1430 module: "OpenRouterLanguageModel",
1431 method: "makeStreamResponse",
1432 reason: new AiError.InvalidOutputError({
1433 description: "Received tool call delta that was not of type: 'function'"
1434 })
1435 })
1436 }
1437
1438 if (Predicate.isNullish(toolCall.id)) {
1439 return yield* AiError.make({
1440 module: "OpenRouterLanguageModel",
1441 method: "makeStreamResponse",
1442 reason: new AiError.InvalidOutputError({
1443 description: "Received tool call delta without a tool call identifier"
1444 })
1445 })
1446 }
1447
1448 if (Predicate.isNullish(toolCall.function?.name)) {
1449 return yield* AiError.make({
1450 module: "OpenRouterLanguageModel",
1451 method: "makeStreamResponse",
1452 reason: new AiError.InvalidOutputError({
1453 description: "Received tool call delta without a tool call name"
1454 })
1455 })
1456 }
1457
1458 activeToolCall = {
1459 id: toolCall.id,
1460 type: "function",
1461 name: toolCall.function.name,
1462 params: argumentsDelta
1463 }
1464
1465 activeToolCalls[index] = activeToolCall
1466
1467 parts.push({
1468 type: "tool-params-start",
1469 id: activeToolCall.id,
1470 name: activeToolCall.name
1471 })
1472 } else {
1473 activeToolCall.params += argumentsDelta
1474 }
1475
1476 // Emit a tool call delta part if parameters were also sent
1477 if (argumentsDelta.length > 0) {
1478 parts.push({
1479 type: "tool-params-delta",
1480 id: activeToolCall.id,
1481 delta: argumentsDelta
1482 })
1483 }
1484
1485 // Check if the tool call is complete
1486 // @effect-diagnostics-next-line tryCatchInEffectGen:off
1487 try {
1488 const params = Tool.unsafeSecureJsonParse(activeToolCall.params)
1489
1490 parts.push({
1491 type: "tool-params-end",
1492 id: activeToolCall.id
1493 })
1494
1495 parts.push({
1496 type: "tool-call",
1497 id: activeToolCall.id,
1498 name: activeToolCall.name,
1499 params,
1500 // Only attach reasoning_details to the first tool call to avoid
1501 // duplicating thinking blocks for parallel tool calls (Claude)
1502 metadata: reasoningDetailsAttachedToToolCall ? undefined : {
1503 openrouter: { reasoningDetails: accumulatedReasoningDetails }
1504 }
1505 })
1506
1507 reasoningDetailsAttachedToToolCall = true
1508
1509 // Increment the total tool calls emitted by the stream and
1510 // remove the active tool call
1511 totalToolCalls += 1
1512 delete activeToolCalls[toolCall.index]
1513 } catch {
1514 // Tool call incomplete, continue parsing
1515 continue
1516 }
1517 }
1518 }
1519
1520 const images = delta.images
1521 if (Predicate.isNotNullish(images)) {
1522 for (const image of images) {
1523 parts.push({
1524 type: "file",
1525 mediaType: getMediaType(image.image_url.url, "image/jpeg"),
1526 data: getBase64FromDataUrl(image.image_url.url)
1527 })
1528 }
1529 }
1530 }
1531
1532 // Usage is only emitted by the last part of the stream, so we need to
1533 // handle flushing any remaining text / reasoning / tool calls
1534 if (Predicate.isNotUndefined(event.usage)) {
1535 // Fix for Gemini 3 thoughtSignature: when there are tool calls with encrypted
1536 // reasoning (thoughtSignature), the model returns 'stop' but expects continuation.
1537 // Override to 'tool-calls' so the SDK knows to continue the conversation.
1538 const hasEncryptedReasoning = accumulatedReasoningDetails.some(
1539 (detail) => detail.type === "reasoning.encrypted" && detail.data.length > 0
1540 )
1541 if (totalToolCalls > 0 && hasEncryptedReasoning && finishReason === "stop") {
1542 finishReason = "tool-calls"
1543 }
1544
1545 // Forward any unsent tool calls if finish reason is 'tool-calls'
1546 if (finishReason === "tool-calls") {
1547 for (const toolCall of Object.values(activeToolCalls)) {
1548 // Coerce invalid tool call parameters to an empty object
1549 let params: unknown
1550 // @effect-diagnostics-next-line tryCatchInEffectGen:off
1551 try {
1552 params = Tool.unsafeSecureJsonParse(toolCall.params)
1553 } catch {
1554 params = {}
1555 }
1556
1557 // Only attach reasoning_details to the first tool call to avoid
1558 // duplicating thinking blocks for parallel tool calls (Claude)
1559 parts.push({
1560 type: "tool-call",
1561 id: toolCall.id,
1562 name: toolCall.name,
1563 params,
1564 metadata: reasoningDetailsAttachedToToolCall ? undefined : {
1565 openrouter: { reasoningDetails: accumulatedReasoningDetails }
1566 }
1567 })
1568
1569 reasoningDetailsAttachedToToolCall = true
1570 }
1571 }
1572
1573 // End reasoning first if it was started, to maintain proper order
1574 if (reasoningStarted) {
1575 parts.push({
1576 type: "reasoning-end",
1577 id: activeReasoningId!,
1578 // Include accumulated reasoning_details so that we can update the
1579 // reasoning part's provider metadata with the correct signature,
1580 metadata: accumulatedReasoningDetails.length > 0
1581 ? { openrouter: { reasoningDetails: accumulatedReasoningDetails } }
1582 : undefined
1583 })
1584 }
1585
1586 if (textStarted) {
1587 parts.push({ type: "text-end", id: activeTextId! })
1588 }
1589
1590 const metadata: Response.FinishPart["metadata"] = {
1591 openrouter: {
1592 ...(Predicate.isNotNullish(event.system_fingerprint)
1593 ? { systemFingerprint: event.system_fingerprint }
1594 : undefined),
1595 ...(Predicate.isNotUndefined(event.usage) ? { usage: event.usage } : undefined),
1596 ...(Predicate.hasProperty(event, "provider") && Predicate.isString(event.provider)
1597 ? { provider: event.provider }
1598 : undefined),
1599 ...(accumulatedFileAnnotations.length > 0 ? { annotations: accumulatedFileAnnotations } : undefined)
1600 }
1601 }
1602
1603 parts.push({
1604 type: "finish",
1605 reason: finishReason,
1606 usage,
1607 response: buildHttpResponseDetails(response),
1608 metadata
1609 })
1610 }
1611
1612 return parts
1613 })),
1614 Stream.flattenIterable
1615 )
1616 }
1617 )
1618
1619 // =============================================================================
1620 // Tool Conversion
1621 // =============================================================================
1622
1623 const prepareTools = Effect.fnUntraced(
1624 function*({ options, transformer }: {
1625 readonly options: LanguageModel.ProviderOptions
1626 readonly transformer: LanguageModel.CodecTransformer
1627 }): Effect.fn.Return<{
1628 readonly tools: ReadonlyArray<typeof Generated.ChatFunctionTool.Encoded> | undefined
1629 readonly toolChoice: typeof Generated.ChatToolChoice.Encoded | undefined
1630 }, AiError.AiError> {
1631 if (options.tools.length === 0) {
1632 return { tools: undefined, toolChoice: undefined }
1633 }
1634
1635 const hasProviderDefinedTools = options.tools.some((tool) => Tool.isProviderDefined(tool))
1636 if (hasProviderDefinedTools) {
1637 return yield* AiError.make({
1638 module: "OpenRouterLanguageModel",
1639 method: "prepareTools",
1640 reason: new AiError.InvalidUserInputError({
1641 description: "Provider-defined tools are unsupported by the OpenRouter " +
1642 "provider integration at this time"
1643 })
1644 })
1645 }
1646
1647 let tools: Array<Extract<typeof Generated.ChatFunctionTool.Encoded, { readonly type: "function" }>> = []
1648 let toolChoice: typeof Generated.ChatToolChoice.Encoded | undefined = undefined
1649
1650 for (const tool of options.tools) {
1651 const description = Tool.getDescription(tool)
1652 const parameters = yield* tryToolJsonSchema(tool, "prepareTools", transformer)
1653 const strict = Tool.getStrictMode(tool) ?? null
1654
1655 tools.push({
1656 type: "function",
1657 function: {
1658 name: tool.name,
1659 parameters,
1660 strict,
1661 ...(Predicate.isNotUndefined(description) ? { description } : undefined)
1662 }
1663 })
1664 }
1665
1666 if (options.toolChoice === "none") {
1667 toolChoice = "none"
1668 } else if (options.toolChoice === "auto") {
1669 toolChoice = "auto"
1670 } else if (options.toolChoice === "required") {
1671 toolChoice = "required"
1672 } else if ("tool" in options.toolChoice) {
1673 toolChoice = { type: "function", function: { name: options.toolChoice.tool } }
1674 } else {
1675 const allowedTools = new Set(options.toolChoice.oneOf)
1676 tools = tools.filter((tool) => allowedTools.has(tool.function.name))
1677 toolChoice = options.toolChoice.mode === "required" ? "required" : "auto"
1678 }
1679
1680 return { tools, toolChoice }
1681 }
1682 )
1683
1684 // =============================================================================
1685 // Telemetry
1686 // =============================================================================
1687
1688 const annotateRequest = (
1689 span: Span,
1690 request: typeof Generated.ChatRequest.Encoded
1691 ): void => {
1692 addGenAIAnnotations(span, {
1693 provider: { name: "openrouter" },
1694 operation: { name: "chat" },
1695 request: {
1696 model: request.model,
1697 temperature: request.temperature,
1698 topP: request.top_p,
1699 maxTokens: request.max_tokens,
1700 stopSequences: Arr.ensure(request.stop).filter(
1701 Predicate.isNotNullish
1702 )
1703 }
1704 })
1705 }
1706
1707 const annotateResponse = (span: Span, response: Generated.SendChatCompletionRequest200): void => {
1708 addGenAIAnnotations(span, {
1709 response: {
1710 id: response.id,
1711 model: response.model,
1712 finishReasons: response.choices.map((choice) => choice.finish_reason).filter(Predicate.isNotNullish)
1713 },
1714 usage: {
1715 inputTokens: response.usage?.prompt_tokens,
1716 outputTokens: response.usage?.completion_tokens
1717 }
1718 })
1719 }
1720
1721 const annotateStreamResponse = (span: Span, part: Response.StreamPartEncoded) => {
1722 if (part.type === "response-metadata") {
1723 addGenAIAnnotations(span, {
1724 response: {
1725 id: part.id,
1726 model: part.modelId
1727 }
1728 })
1729 }
1730 if (part.type === "finish") {
1731 addGenAIAnnotations(span, {
1732 response: {
1733 finishReasons: [part.reason]
1734 },
1735 usage: {
1736 inputTokens: part.usage.inputTokens.total,
1737 outputTokens: part.usage.outputTokens.total
1738 }
1739 })
1740 }
1741 }
1742
1743 // =============================================================================
1744 // Internal Utilities
1745 // =============================================================================
1746
1747 const getCacheControl = (
1748 part:
1749 | Prompt.SystemMessage
1750 | Prompt.UserMessage
1751 | Prompt.AssistantMessage
1752 | Prompt.ToolMessage
1753 | Prompt.TextPart
1754 | Prompt.ReasoningPart
1755 | Prompt.FilePart
1756 | Prompt.ToolResultPart
1757 ): typeof Generated.ChatContentCacheControl.Encoded | null => part.options.openrouter?.cacheControl ?? null
1758
1759 const findFirstReasoningDetails = (content: ReadonlyArray<Prompt.AssistantMessagePart>): ReasoningDetails | null => {
1760 for (const part of content) {
1761 // First try tool calls since they have complete accumulated reasoning details
1762 if (part.type === "tool-call") {
1763 const details = part.options.openrouter?.reasoningDetails
1764 if (Predicate.isNotNullish(details) && Array.isArray(details) && details.length > 0) {
1765 return details as ReasoningDetails
1766 }
1767 }
1768
1769 // Fallback to reasoning parts which have delta reasoning details
1770 if (part.type === "reasoning") {
1771 const details = part.options.openrouter?.reasoningDetails
1772 if (Predicate.isNotNullish(details) && Array.isArray(details) && details.length > 0) {
1773 return details as ReasoningDetails
1774 }
1775 }
1776 }
1777
1778 return null
1779 }
1780
1781 const getCodecTransformer = (model: string): LanguageModel.CodecTransformer => {
1782 if (model.startsWith("anthropic/") || model.startsWith("claude-")) {
1783 return toCodecAnthropic
1784 }
1785 if (
1786 model.startsWith("openai/") ||
1787 model.startsWith("gpt-") ||
1788 model.startsWith("o1-") ||
1789 model.startsWith("o3-") ||
1790 model.startsWith("o4-")
1791 ) {
1792 return toCodecOpenAI
1793 }
1794 return LanguageModel.defaultCodecTransformer
1795 }
1796
1797 const unsupportedSchemaError = (error: unknown, method: string): AiError.AiError =>
1798 AiError.make({
1799 module: "OpenRouterLanguageModel",
1800 method,
1801 reason: new AiError.UnsupportedSchemaError({
1802 description: error instanceof Error ? error.message : String(error)
1803 })
1804 })
1805
1806 const tryJsonSchema = <S extends Schema.Constraint>(
1807 schema: S,
1808 method: string,
1809 transformer: LanguageModel.CodecTransformer
1810 ) =>
1811 Effect.try({
1812 try: () => Tool.getJsonSchemaFromSchema(schema, { transformer }),
1813 catch: (error) => unsupportedSchemaError(error, method)
1814 })
1815
1816 const toolParametersError = (tool: Tool.Any, error: unknown, method: string): AiError.AiError =>
1817 unsupportedSchemaError(
1818 `Tool "${tool.name}" parameters: ${error instanceof Error ? error.message : String(error)}. ` +
1819 "For a tool without parameters, omit `parameters` or use `Tool.EmptyParams`",
1820 method
1821 )
1822
1823 const tryToolJsonSchema = <T extends Tool.Any>(tool: T, method: string, transformer: LanguageModel.CodecTransformer) =>
1824 Effect.try({
1825 try: () => Tool.getJsonSchema(tool, { transformer }),
1826 catch: (error) => toolParametersError(tool, error, method)
1827 }).pipe(Effect.filterOrFail(
1828 // A raw JSON Schema given to a dynamic tool is sent unchanged
1829 (jsonSchema) =>
1830 jsonSchema.type === "object" || Array.isArray(jsonSchema.anyOf) ||
1831 (Tool.isDynamic(tool) && tool.jsonSchema !== undefined),
1832 (jsonSchema) =>
1833 toolParametersError(
1834 tool,
1835 `expected a JSON Schema with type "object" or "anyOf", received ${JSON.stringify(jsonSchema)}`,
1836 method
1837 )
1838 ))
1839
1840 const getResponseFormat = Effect.fnUntraced(function*({ config, options, transformer }: {
1841 readonly config: typeof Config.Service
1842 readonly options: LanguageModel.ProviderOptions
1843 readonly transformer: LanguageModel.CodecTransformer
1844 }): Effect.fn.Return<typeof Generated.ChatFormatJsonSchemaConfig.Encoded | undefined, AiError.AiError> {
1845 if (options.responseFormat.type === "json") {
1846 const description = SchemaAST.resolveDescription(options.responseFormat.schema.ast)
1847 const jsonSchema = yield* tryJsonSchema(options.responseFormat.schema, "getResponseFormat", transformer)
1848 return {
1849 type: "json_schema",
1850 json_schema: {
1851 name: options.responseFormat.objectName,
1852 schema: jsonSchema,
1853 strict: config.strictJsonSchema ?? (transformer === toCodecOpenAI ? true : null),
1854 ...(Predicate.isNotUndefined(description) ? { description } : undefined)
1855 }
1856 }
1857 }
1858 return undefined
1859 })
1860
1861 /**
1862 * Maps audio media types to the formats supported by OpenRouter.
1863 *
1864 * @see https://openrouter.ai/docs/guides/overview/multimodal/audio
1865 */
1866 const audioFormats: Record<string, string> = {
1867 "audio/aac": "aac",
1868 "audio/aiff": "aiff",
1869 "audio/x-aiff": "aiff",
1870 "audio/flac": "flac",
1871 "audio/x-flac": "flac",
1872 "audio/l16": "pcm16",
1873 "audio/l24": "pcm24",
1874 "audio/m4a": "m4a",
1875 "audio/x-m4a": "m4a",
1876 "audio/mp4": "m4a",
1877 "audio/mp3": "mp3",
1878 "audio/mpeg": "mp3",
1879 "audio/ogg": "ogg",
1880 "audio/wav": "wav",
1881 "audio/wave": "wav",
1882 "audio/x-wav": "wav"
1883 }
1884
1885 const supportedAudioFormats = Array.from(new Set(Object.values(audioFormats))).join(", ")
1886
1887 const getMediaType = (dataUrl: string, defaultMediaType: string): string => {
1888 const match = dataUrl.match(/^data:([^;]+)/)
1889 return match ? (match[1] ?? defaultMediaType) : defaultMediaType
1890 }
1891
1892 const getBase64FromDataUrl = (dataUrl: string): string => {
1893 const match = dataUrl.match(/^data:[^;]*;base64,(.+)$/)
1894 return match ? match[1]! : dataUrl
1895 }
1896
1897 const getUsage = (usage: Generated.ChatUsage | undefined): Response.Usage => {
1898 if (Predicate.isUndefined(usage)) {
1899 return {
1900 inputTokens: { uncached: undefined, total: 0, cacheRead: undefined, cacheWrite: undefined },
1901 outputTokens: { total: 0, text: undefined, reasoning: undefined }
1902 }
1903 }
1904 const promptTokens = usage.prompt_tokens
1905 const completionTokens = usage.completion_tokens
1906 const cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? 0
1907 const cacheWriteTokens = usage.prompt_tokens_details?.cache_write_tokens ?? 0
1908 const reasoningTokens = usage.completion_tokens_details?.reasoning_tokens ?? 0
1909 // Some providers report cached or reasoning tokens separately from their parent counts.
1910 // Treat details exceeding the parent as disjoint to avoid negative remainders.
1911 // Otherwise, retain subset accounting.
1912 const inputTotal = cacheReadTokens > promptTokens ? promptTokens + cacheReadTokens : promptTokens
1913 const outputTotal = reasoningTokens > completionTokens ? completionTokens + reasoningTokens : completionTokens
1914 return {
1915 inputTokens: {
1916 uncached: inputTotal - cacheReadTokens,
1917 total: inputTotal,
1918 cacheRead: cacheReadTokens,
1919 cacheWrite: cacheWriteTokens
1920 },
1921 outputTokens: {
1922 total: outputTotal,
1923 text: outputTotal - reasoningTokens,
1924 reasoning: reasoningTokens
1925 }
1926 }
1927 }