fix(core): trigger compaction at 85% of the input window

Co-authored-by: nexxeln <95541290+nexxeln@users.noreply.github.com>

packages/ai/AGENTS.md

@@ -10,7 +10,7 @@
 
 ## Conventions
 
-Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `Message.media(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, and `LLM.generateObject`. Use `LLMRequest.update(...)` when deriving canonical request data; do not add a duplicate `LLM.updateRequest(...)` path. Two ways to construct the same thing is one too many.
+Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `Message.media(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, and `LLM.generateObject`. `LLM.generate`/`LLM.stream` and Promise `ai.llm.generate`/`ai.llm.stream` accept ergonomic input or an `LLMRequest`; both paths use the same canonical request. Core still builds, logs, replays, and updates that durable `LLMRequest` boundary. Use `LLMRequest.update(...)` when deriving canonical request data; do not add a duplicate `LLM.updateRequest(...)` path.
 
 Modality namespaces mirror `LLM` exactly: `Image.request`, `Image.generate`, `Image.stream` (later `Video`, `Speech`, `Transcription`). Common request fields (`images`, `mask`, `n`, `size`, `aspectRatio`, `seed`, `format`) lower natively or fail with a typed `AIError`; provider-native controls always live under `providerOptions`, never under a modality-specific `options` key.
 
@@ -96,13 +96,13 @@ When a provider supports multiple physical transports, selection remains executi
 
 ### Media Routes
 
-Media does not fit the SSE-frames-to-event-state-machine LLM route. `MediaRoute.make(...)` (`src/route/media.ts`) composes a `MediaProtocol` kind with `Endpoint` and `Auth` and owns the transport plumbing: `http` option merging, URL/query rendering, auth headers, JSON vs multipart encoding, and handing the response back to the protocol. `MediaProtocol.inline` (`src/route/media-protocol.ts`) is `body.from(request)` plus `response.decode(response, context)`; use `MediaProtocol.decodeJson` / `text` / `bytes` so decode failures retain the raw body and HTTP context. `Generation` (`src/generation.ts`) is the provider-neutral handle for a queued generation over a `GenerationRoute` (`status`, `result`, `cancel`, `pollHint`). Image protocol files follow the same section order as LLM protocols and declare unsupported common fields once through `MediaInput.rejectUnsupported`.
+Media does not fit the SSE-frames-to-event-state-machine LLM route. `MediaRoute.inline(...)` / `queued(...)` / `stream(...)` (`src/route/media.ts`) compose a `MediaProtocol` kind with `Endpoint` and `Auth` and own the transport plumbing: `http` option merging, URL/query rendering, auth headers, JSON vs multipart encoding, and handing the response back to the protocol. `MediaProtocol.inline` (`src/route/media-protocol.ts`) is `body.from(request)` plus `response.decode(response, context)`; each protocol declares `const route = MediaProtocol.identity({ id, name, provider })` once and decodes through `route.decodeJson` / `route.text` / `route.decodeStarted` so decode failures retain the raw body and HTTP context, raising `route.unsupported(operation, message)` for requests it cannot lower, and passes `route` as the first argument to `MediaProtocol.inline` / `queued` / `stream`. `Generation` (`src/generation.ts`) is the provider-neutral handle for a queued generation over a `GenerationRoute` (`status`, `result`, `cancel`). Image protocol files follow the same section order as LLM protocols and declare unsupported common fields once through the protocol's `unsupported` list.
 
-`MediaProtocol.queued` is the submit-then-poll kind every video route uses: `start` (body + decode into `{ token, snapshot }`), `status`, `result`, and optional `cancel`, each addressed by a route-owned `token` whose `Schema.Codec` makes it serializable. `MediaRoute.inline` and `MediaRoute.queued` compose the two kinds with `Endpoint` and `Auth`; the queued route decodes the token once at the boundary (`start` output or `resume` input) and closes over it in a token-free `GenerationRoute` (`status`/`result`/`cancel` are plain Effects), so `Generation` never sees the token's shape and only carries the encoded JSON for persistence. Polls reuse the route's auth and deployment headers plus the request's `http` overlay after `start`, and resolve relative paths against the route base URL (provider-issued absolute URLs such as fal's `status_url` pass through). `result` is always its own GET even when the provider returns output inside the status document, so `Generation.await` behaves the same after `start` and after `resume`. `PollContext.auth` carries only what `Auth` added so protocols can hand download credentials to output assets as transient `Media.Asset.headers` (Veo) — never part of `source` or JSON. Status strings map through a per-protocol `STATUS` table via `MediaProtocol.status`; terminal generations without output fail through `output.ended` / `output.contentPolicy` with the provider document on `reason.body`. `GenerationAwaitOptions` (`AwaitOptions` in `src/generation.ts`, `{ poll?: Poll }`) is the one options type for `await`, `events`, `Video.generate`, and `Video.stream`.
+`MediaProtocol.queued` is the submit-then-poll kind every video route uses: `start` (body + decode into `{ token, snapshot }`), `status`, `result`, and optional `cancel`, each addressed by a route-owned `token` whose `Schema.Codec` makes it serializable. `MediaRoute.inline` and `MediaRoute.queued` compose the two kinds with `Endpoint` and `Auth`; the queued route decodes the token once at the boundary (`start` output or `resume` input) and closes over it in a token-free `GenerationRoute` (`status`/`result`/`cancel` are plain Effects), so `Generation` never sees the token's shape and only carries the encoded JSON for persistence. Polls reuse the route's auth and deployment headers plus the request's `http` overlay after `start`, and resolve relative paths against the route base URL (provider-issued absolute URLs such as fal's `status_url` pass through). `result` is always its own GET even when the provider returns output inside the status document, so `Generation.await` behaves the same after `start` and after `resume`. `PollContext.auth` carries only what `Auth` added or changed so protocols can hand download credentials to output assets as transient `Media.Asset.headers` (Veo) — never part of `source` or JSON. Status strings map through a per-protocol `STATUS` table via `MediaProtocol.status`; terminal generations without output fail through `output.ended` / `output.contentPolicy` with the provider document on `reason.body`. `GenerationAwaitOptions` (`AwaitOptions` in `src/generation.ts`, `{ poll?: Poll }`) is the one options type for `await`, `events`, `Video.generate`, and `Video.stream`.
 
-`MediaProtocol.stream` is the incremental kind every speech route uses, with the same discipline as LLM protocols. `MediaRoute.stream` submits the caller's request as `MediaProtocol.Addressed<Request>` (`{ ...request, mode }`, `mode: "generate" | "stream"`), so one provider stays one protocol: `body.from`, the endpoint path, and `frames` read `request.mode` to pick the body, path, and framing. `frames(bytes, context)` returns frames — `Framing.sse`, `Framing.lines`, `Framing.document` (a single-document response shaped like a streamed record), or the raw `bytes` for chunked audio. `initial()` is fresh per-response parser state; `step` folds each frame into it and emits modality events; `finish(state, context)` runs once after the last frame with the request, body, and observed `http` (header-only usage lives there) and emits exactly one terminal event or fails with `MediaProtocol.incomplete`. Keep parser state to real accumulators and derive anything the request or body determines in `finish`. `generate` runs the same stream and folds it with the modality's `collect`. Request-derived URL parameters go on the body's `query` (array values repeat the parameter), applied before route and caller `http.query`. Decode frames with `MediaProtocol.decodeFrame` and raise stream-time failures with `MediaProtocol.frameError` (the frame stays on `reason.body`); protocols never thread HTTP context, because the route fills `reason.http` on stream errors that lack it. Speech protocols share `protocols/utils/speech-stream.ts` for deltas, timestamps, voice ids, PCM and container descriptions, and the terminal asset.
+`MediaProtocol.stream` is the incremental kind every speech route uses, with the same discipline as LLM protocols. `MediaRoute.stream` submits the caller's request as `MediaProtocol.Addressed<Request>` (`{ ...request, mode }`, `mode: "generate" | "stream"`), so one provider stays one protocol: `body.from`, the endpoint path, and `frames` read `request.mode` to pick the body, path, and framing. `frames(bytes, context)` returns frames — `Framing.sse`, `Framing.lines`, `Framing.document` (a single-document response shaped like a streamed record), or the raw `bytes` for chunked audio. `initial()` is fresh per-response parser state; `step` folds each frame into it and emits modality events; `finish(state, context)` runs once after the last frame with the request, body, and observed `http` (header-only usage lives there) and emits exactly one terminal event or fails with `route.incomplete()`. Keep parser state to real accumulators and derive anything the request or body determines in `finish`. `generate` runs the same stream and folds it with the modality's `collect`. Request-derived URL parameters go on the body's `query` (array values repeat the parameter), applied before route and caller `http.query`. Decode frames with `route.decodeFrame` and raise stream-time failures with `route.frameError` (the frame stays on `reason.body`); protocols never thread HTTP context, because the route fills `reason.http` on stream errors that lack it. Speech protocols share `protocols/utils/speech-stream.ts` for deltas, timestamps, voice ids, PCM and container descriptions, and the terminal asset.
 
-Transcription uses all three kinds (OpenAI and Gemini stream, Deepgram is inline, AssemblyAI is queued): every route carries its `kind` and `TranscriptionClient` dispatches on it. `ImageRoute` is the same union; both clients dispatch through `MediaRoute.dispatch` and models compose through `composeAnyRoute`, and fal queue protocols come from `protocols/utils/fal-queue.ts`. Bodies are `json`, `multipart`, or `binary` (a raw upload), and a queued protocol that must upload media before submitting implements `start.prepare` (`MediaProtocol.Prepare`; AssemblyAI `/v2/upload`).
+Every modality route is the inline | stream | queued union (transcription uses all three: OpenAI and Gemini stream, Deepgram is inline, AssemblyAI is queued), every client is `MediaClient.make(Service, { modality, responseEvents })` (`src/media-client.ts`), which dispatches on the route's `kind`, and every model composes through `composeRoute`. fal queue protocols come from `protocols/utils/fal-queue.ts`, bodies are `json`, `multipart`, or `binary` (a raw upload), and a queued protocol that must upload media before submitting implements `start.prepare` (`MediaProtocol.Prepare`; AssemblyAI `/v2/upload`).
 
 ### URL Construction
 
@@ -275,6 +275,7 @@ Use this order for every protocol module:
 ### Rules
 
 - Keep protocol files focused on the protocol. Move provider-specific projection, signing, media normalization, or other bulky transformations into `src/protocols/utils/*`.
+- Send `tool.inputSchema` as given. `prepareRequest` applies the tool schema rules (`ToolSchemaProjection.tools`) once per request, including tools in namespaces. A protocol whose API needs a model family's rules for every model declares `sanitizer` instead of transforming schemas itself.
 - Use `Effect.fn("Provider.fromRequest")` for request body construction entrypoints. Use `Effect.fn(...)` for event handlers that yield effects; keep purely synchronous handlers as plain functions returning a `StepResult` that the dispatcher lifts via `Effect.succeed(...)`.
 - Parser state owns terminal information. The state machine records finish reason, usage, and pending tool calls; emit one terminal `finish` event (or `provider-error`) for each completed response. If a provider splits reason and usage across events, merge them in parser state before flushing.
 - Emit exactly one terminal `finish` event for a completed response, normally after a matching `step-finish`. Use `stream.terminal` to stop reading when the provider has a completion sentinel; use `stream.onHalt` when the final event must be flushed after the framed stream ends.

packages/ai/README.md

@@ -9,15 +9,13 @@ import { OpenAI } from "@opencode/ai/providers"
 
 const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
 
-const request = LLM.request({
-  model: openai.responses("gpt-4o-mini"), // `.chat(...)` selects the Chat Completions API instead
-  system: "You are concise.",
-  prompt: "Say hello in one short sentence.",
-  generation: { maxTokens: 40 },
-})
-
 const program = Effect.gen(function* () {
-  const response = yield* LLM.generate(request)
+  const response = yield* LLM.generate({
+    model: openai.responses("gpt-4o-mini"), // `.chat(...)` selects the Chat Completions API instead
+    system: "You are concise.",
+    prompt: "Say hello in one short sentence.",
+    generation: { maxTokens: 40 },
+  })
   console.log(response.text)
 })
 
@@ -25,7 +23,8 @@ const program = Effect.gen(function* () {
 await Effect.runPromise(program.pipe(Effect.provide(AIClient.layer)))
 ```
 
-Run `LLM.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses,
+Run `LLM.stream(...)` instead of `generate` when you want incremental `LLMEvent`s. Both accept input or a prebuilt
+`LLM.request(...)`. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses,
 Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
 
 The same configured facade names image, video, speech, and transcription models. `Image.generate` resolves the
@@ -72,10 +71,11 @@ helpers; `ai.file` and `ai.write` load `node:fs/promises` on first use, so no Ef
 import { AI } from "@opencode/ai/promise"
 
 const ai = AI.make()
-const text = await ai.llm.generate({ model: openai.responses("gpt-4o-mini"), prompt: "Say hello." })
+const input = { model: openai.responses("gpt-4o-mini"), prompt: "Say hello." }
+const text = await ai.llm.generate(input)
 const generated = await ai.image.generate({ model: openai.image("gpt-image-2"), prompt: "A lighthouse" })
 await ai.write(generated.image, "./lighthouse.png") // also ai.file(path), ai.bytes(asset), ai.base64(asset), ai.materialize(asset)
-for await (const event of ai.llm.stream({ model: openai.responses("gpt-4o-mini"), prompt: "Stream hello." })) {
+for await (const event of ai.llm.stream(ai.llm.request(input))) {
   // LLMEvent
 }
 await ai.dispose()
@@ -936,7 +936,7 @@ const transcript = await generation.await({ poll: { interval: 3_000 } })
 ## Public API
 
 - **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
-- **`LLM.generate` / `LLM.stream`** — re-exported from `LLMClient` for one-import use.
+- **`LLM.generate` / `LLM.stream`** — run direct input or an `LLMRequest` through `LLMClient` for one-import use.
 - **`Message.user(...)` / `Message.assistant(...)` / `Message.tool(...)`** — message constructors from the canonical schema model.
 - **`LanguageModel.make(...)` / `ToolCallPart.make(...)` / `ToolResultPart.make(...)` / `ToolDefinition.make(...)`** — model and tool-related constructors from the canonical schema model.
 - **`LLMEvent.is.*`** — typed guards (`is.textDelta`, `is.toolCall`, `is.finish`, …) for filtering streams.

packages/ai/docs/media-design.md

@@ -140,7 +140,7 @@ portability matrix.
 
 Editing is not a separate function; `images`/`mask` on the request select the edit path in the route (OpenAI `/images/edits`, Gemini multimodal parts, xAI `/images/edits`). Routes that cannot honor `mask` fail with `Unsupported`.
 
-`ImageRoute` is the inline | stream | queued union, dispatched on `route.kind`. `Image.stream` on a streaming route emits `image-partial` previews before each `image`; on a queued route it emits `generation-queued` / `generation-progress` observations, then the result's `image` and `finish` events.
+`ImageRoute` is the inline | stream | queued union, dispatched on `route.kind`, like every modality route. `Image.stream` on a streaming route emits `image-partial` previews before each `image`; on a queued route it emits `generation-queued` / `generation-progress` observations, then the result's `image` and `finish` events.
 
 #### Video
 
@@ -215,7 +215,7 @@ const request = Speech.request({
 })
 
 const response = yield* Speech.generate(request)   // SpeechResponse: audio: Media.Asset, timestamps?, usage?, providerMetadata?
-yield* Speech.stream(request)                      // Stream<SpeechEvent>: audio-delta { chunk } | timestamps { items } | finish { audio, usage? }
+yield* Speech.stream(request)                      // Stream<SpeechEvent>: generation-queued | generation-progress | audio-delta { chunk } | timestamps { items } | finish { audio, usage? }
 ```
 
 Execution is `MediaProtocol.stream` for every provider: one request whose body is framed and folded by a `step`
@@ -337,12 +337,11 @@ with the realtime work in phase 5. ElevenLabs Scribe is not implemented yet.
 ```ts
 class Generation<Response> {
   readonly id: string
-  readonly route: GenerationRoute<Response>        // token-free: { status, result, cancel?: Effect; pollHint? } closed over the decoded token
+  readonly route: GenerationRoute<Response>        // token-free: { status, result, cancel?: Effect } closed over the decoded token
   readonly token: unknown                          // route-owned serializable JSON
   readonly status: "queued" | "running" | "completed" | "failed" | "cancelled" | "expired"
   readonly progress?: number                       // 0..1, normalized
   readonly position?: number
-  readonly expiresAt?: number
   refresh(): Effect<Generation<Response>, AIError>
   result(): Effect<Response, AIError>
   await(options?: GenerationAwaitOptions): Effect<Response, AIError>
@@ -351,7 +350,7 @@ class Generation<Response> {
 }
 
 GenerationAwaitOptions = { poll?: Poll }
-Poll = { interval?: Duration; timeout?: Duration; schedule?: Schedule }   // route may override from provider hints (`openai-poll-after-ms`)
+Poll = { interval?: Duration; timeout?: Duration }
 ```
 
 `Generation` is not video-specific. Image routes on BFL, fal, and Replicate are queued; `Image.start` exists for them. A route declares itself `inline` or `queued`; `generate` on a queued route is `start` then `await`.
@@ -390,7 +389,8 @@ for await (const event of generation.events({ poll: { interval: 10_000 } })) {
 const video = await generation.await({ poll: { interval: 10_000 }, signal })
 const resumed = await ai.video.resume(model, JSON.parse(saved)) // persist provider + model ID with the token
 
-const text = await ai.llm.generate({ model, prompt })
+const request = ai.llm.request({ model, prompt })
+const text = await ai.llm.generate(request)
 for await (const event of ai.llm.stream(request)) { … }
 
 await ai.dispose()
@@ -420,14 +420,14 @@ Existing facades gain per-modality selectors; the modality routes each facade pr
 
 New facades follow the existing one-file-per-provider rule. The facade selector is the public path for media models; modality-specific package entrypoints (for example `@opencode/ai/providers/openai/images`) are deferred until Core has a modality-aware model resolver.
 
-`ImageModel<Options>` gives typed `providerOptions` per model; `VideoModel`, `SpeechModel`, and `TranscriptionModel` follow the same generic. They share an internal `MediaModel` base class (ids, route, `http` overlays) that is not part of the public exports; `Generation` and the promise client work with the concrete modality models.
+`ImageModel<Options>` gives typed `providerOptions` per model; `VideoModel`, `SpeechModel`, and `TranscriptionModel` follow the same generic. As with `LanguageModel`, the route type does not carry `Options`, so `ImageModel<OpenAIImageOptions>` is an `ImageModel` and client methods take plain `ImageRequestFor`. They share an internal `MediaModel` base class (ids, route, `http` overlays) that is not part of the public exports; `Generation` and the promise client work with the concrete modality models.
 
 ### Routes and protocols
 
 Media does not fit the LLM four-axis route (SSE frames → event state machine) except for streaming TTS/STT. Reuse `Endpoint`, `Auth`, `Framing`, `RequestExecutor`, and add media protocol kinds:
 
 - `MediaProtocol.inline` — `body.from(request)` (JSON, multipart, or query), `response.decode(response)` (JSON, or binary body → `Media.Asset`).
-- `MediaProtocol.queued` — `start` (body + decode to `{ token, snapshot }`), `status`, `result`, optional `cancel`, `pollHint`, and a `token` codec. `result` is always a separate GET (against the status document for Veo/xAI/Runway, fal's `response_url` otherwise) so `await` after `start` and after `resume` share one path. `PollContext.auth` hands the auth headers the route sent to the protocol for output URLs that need them (Veo downloads); they become transient `Media.Asset.headers`, never part of `source`. There is no separate `download` step: `Media.Asset.bytes()` downloads through the executor with those headers. `MediaRoute.inline(...)` / `MediaRoute.queued(...)` compose each kind with endpoint and auth; the queued route decodes the token once and hands `Generation` a token-free `{ status, result, cancel? }`.
+- `MediaProtocol.queued` — `start` (body + decode to `{ token, snapshot }`), `status`, `result`, optional `cancel`, and a `token` codec. `result` is always a separate GET (against the status document for Veo/xAI/Runway, fal's `response_url` otherwise) so `await` after `start` and after `resume` share one path. `PollContext.auth` hands the auth headers the route sent to the protocol for output URLs that need them (Veo downloads); they become transient `Media.Asset.headers`, never part of `source`. There is no separate `download` step: `Media.Asset.bytes()` downloads through the executor with those headers. `MediaRoute.inline(...)` / `MediaRoute.queued(...)` compose each kind with endpoint and auth; the queued route decodes the token once and hands `Generation` a token-free `{ status, result, cancel? }`.
 - `MediaProtocol.stream` — `body.from(request)` over the request plus its `mode`, `frames` (a function that picks the framing for the call: `Framing.sse`, `lines`, `document`, or the raw bytes), fresh per-response `initial()` state, `step` emitting modality events, and `finish(state, context)` — with the observed response for header-only usage — emitting exactly one terminal event or failing as an incomplete stream. The route fills `reason.http` on stream errors. `MediaRoute.stream(...)` exposes `stream` and `generate` (the same stream folded by the modality's `collect`).
 
 `MediaRoute.inline` / `MediaRoute.queued` / `MediaRoute.stream` compose one protocol kind with endpoint/auth and tag the route with its `kind`; `ImageModel`/`VideoModel`/`SpeechModel`/`TranscriptionModel` share the `MediaModel` base (`src/media-model.ts`).

packages/ai/src/experimental/evaluation.ts

@@ -214,7 +214,7 @@ export function request(input: EvaluationRequest | EvaluationRequestInput) {
   return new EvaluationRequest({
     ...input,
     model: input.model as unknown as EvaluationModel,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+    http: HttpOptions.make(input.http),
   })
 }
 

packages/ai/src/generation.ts

@@ -11,7 +11,6 @@ export interface Snapshot {
   /** Normalized 0..1 when the provider reports progress. */
   readonly progress?: number
   readonly position?: number
-  readonly expiresAt?: number
 }
 
 /**
@@ -22,15 +21,11 @@ export interface Route<Response> {
   readonly status: Effect.Effect<Snapshot, AIError>
   readonly result: Effect.Effect<Response, AIError>
   readonly cancel?: Effect.Effect<void, AIError>
-  /** Provider polling hint (e.g. `openai-poll-after-ms`) that overrides the default interval for the next poll. */
-  readonly pollHint?: (snapshot: Snapshot) => Duration.Duration | undefined
 }
 
 export interface Poll {
   readonly interval?: Duration.Input
   readonly timeout?: Duration.Input
-  /** Full override of the polling schedule; `interval` and `pollHint` are ignored when supplied. */
-  readonly schedule?: Schedule.Schedule<unknown, Snapshot>
 }
 
 export interface AwaitOptions {
@@ -63,7 +58,6 @@ export class Generation<Response> {
   readonly status: Status
   readonly progress?: number
   readonly position?: number
-  readonly expiresAt?: number
 
   constructor(
     readonly route: Route<Response>,
@@ -75,7 +69,6 @@ export class Generation<Response> {
     this.status = snapshot.status
     this.progress = snapshot.progress
     this.position = snapshot.position
-    this.expiresAt = snapshot.expiresAt
   }
 
   get snapshot(): Snapshot {
@@ -84,7 +77,6 @@ export class Generation<Response> {
       status: this.status,
       progress: this.progress,
       position: this.position,
-      expiresAt: this.expiresAt,
     }
   }
 
@@ -168,15 +160,8 @@ export class Generation<Response> {
     )
   }
 
-  private schedule(poll: Poll | undefined): Schedule.Schedule<unknown, Generation<Response>> {
-    if (poll?.schedule) return poll.schedule.pipe(Schedule.setInputType<Generation<Response>>())
-    const interval = poll?.interval ?? DEFAULT_POLL_INTERVAL
-    const pollHint = this.route.pollHint
-    const spaced = Schedule.spaced(interval).pipe(Schedule.setInputType<Generation<Response>>())
-    if (!pollHint) return spaced
-    return spaced.pipe(
-      Schedule.modifyDelay((metadata) => Effect.succeed(pollHint(metadata.input.snapshot) ?? interval)),
-    )
+  private schedule(poll: Poll | undefined) {
+    return Schedule.spaced(poll?.interval ?? DEFAULT_POLL_INTERVAL)
   }
 }
 

packages/ai/src/image-client.ts

@@ -1,99 +1,30 @@
-import { Context, Effect, Layer, Stream } from "effect"
-import type { AwaitOptions, Generation } from "./generation.js"
-import { RequestExecutor } from "./route/executor.js"
-import { MediaRoute } from "./route/media.js"
-import type { AIError } from "./schema/index.js"
+import { Context } from "effect"
+import { MediaClient } from "./media-client.js"
 import {
-  responseEvents,
+  ImageOutputEvent,
+  ImageFinishEvent,
   type ImageEvent,
-  type ImageModel,
-  type ImageOptions,
   type ImageRequestFor,
   type ImageResponse,
 } from "./image.js"
 
-export interface Interface {
-  readonly generate: <Options extends ImageOptions>(
-    request: ImageRequestFor<Options>,
-    options?: AwaitOptions,
-  ) => Effect.Effect<ImageResponse, AIError>
-  readonly stream: <Options extends ImageOptions>(
-    request: ImageRequestFor<Options>,
-    options?: AwaitOptions,
-  ) => Stream.Stream<ImageEvent, AIError>
-  readonly start: <Options extends ImageOptions>(
-    request: ImageRequestFor<Options>,
-  ) => Effect.Effect<Generation<ImageResponse>, AIError>
-  readonly resume: <Options extends ImageOptions>(
-    model: ImageModel<Options>,
-    token: unknown,
-  ) => Effect.Effect<Generation<ImageResponse>, AIError>
-}
+export type Interface = MediaClient.Interface<ImageRequestFor, ImageEvent, ImageResponse>
 
 export class ImageClientService extends Context.Service<ImageClientService, Interface>()("@opencode/ImageClient") {}
 export const Service = ImageClientService
 export type Service = ImageClientService
 
-export const generate = <Options extends ImageOptions>(
-  request: ImageRequestFor<Options>,
-  options?: AwaitOptions,
-): Effect.Effect<ImageResponse, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.generate(request, options)
-  })
-
-export const stream = <Options extends ImageOptions>(
-  request: ImageRequestFor<Options>,
-  options?: AwaitOptions,
-): Stream.Stream<ImageEvent, AIError, Service> =>
-  Stream.unwrap(
-    Effect.gen(function* () {
-      const client = yield* Service
-      return client.stream(request, options)
-    }),
-  )
-
-export const start = <Options extends ImageOptions>(
-  request: ImageRequestFor<Options>,
-): Effect.Effect<Generation<ImageResponse>, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.start(request)
-  })
-
-export const resume = <Options extends ImageOptions>(
-  model: ImageModel<Options>,
-  token: unknown,
-): Effect.Effect<Generation<ImageResponse>, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.resume(model, token)
-  })
-
-export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const executor = yield* RequestExecutor.Service
-    const dispatch = MediaRoute.dispatch<ImageEvent, ImageResponse>({
-      modality: "image",
-      execute: executor.execute,
-      responseEvents,
-    })
-    return Service.of({
-      start: (request) => dispatch.start(request.model.route, request),
-      resume: (model, token) => dispatch.resume(model.route, model, token),
-      generate: (request, options) => dispatch.generate(request.model.route, request, options),
-      stream: (request, options) => dispatch.stream(request.model.route, request, options),
-    })
-  }),
-)
-
 export const ImageClient = {
   Service,
-  layer,
-  generate,
-  stream,
-  start,
-  resume,
+  ...MediaClient.make(Service, {
+    modality: "image",
+    responseEvents: (response: ImageResponse) => [
+      ...response.images.map((image, index) => ImageOutputEvent.make({ index, image })),
+      ImageFinishEvent.make({
+        usage: response.usage,
+        notices: response.notices,
+        providerMetadata: response.providerMetadata,
+      }),
+    ],
+  }),
 } as const

packages/ai/src/image.ts

@@ -1,85 +1,48 @@
 import { Effect, Schema, Stream } from "effect"
 import { Generation, ProgressEvent, QueuedEvent, type AwaitOptions } from "./generation.js"
 import { Media } from "./media.js"
-import { MediaModel, composeAnyRoute, tryRequest } from "./media-model.js"
+import { MediaModel, composeRoute, tryRequest } from "./media-model.js"
 import { MediaRoute } from "./route/media.js"
-import type { MediaProtocol } from "./route/media-protocol.js"
-import { AIError, HttpOptions, MediaUsage, ProviderMetadata } from "./schema/index.js"
+import { AIError, HttpOptions, MediaUsage, ProviderMetadata, type OpenString } from "./schema/index.js"
 import { ImageClient, Service } from "./image-client.js"
 
 // ---------------------------------------------------------------------------
 // Model
 // ---------------------------------------------------------------------------
 
-export type ImageOptions = Record<string, unknown>
+export type ImageOptions = MediaModel.Options
 
-export type ImageRoute<Options extends ImageOptions = ImageOptions> = MediaRoute.AnyRoute<
-  ImageRequestFor<Options>,
-  ImageEvent,
-  ImageResponse
->
+export type ImageRoute = MediaRoute.AnyRoute<ImageRequestFor, ImageEvent, ImageResponse>
 
-export class ImageModel<Options extends ImageOptions = ImageOptions> extends MediaModel<ImageRoute<Options>, Options> {
+export class ImageModel<Options extends ImageOptions = ImageOptions> extends MediaModel<ImageRoute, Options> {
   declare protected readonly _ImageModel: void
 
-  static make<Options extends ImageOptions = ImageOptions>(input: MediaModel.Input<ImageRoute<Options>>) {
-    return new ImageModel<Options>(input)
-  }
-
   /** The number of type arguments selects the kind: `<Options>`, `<Options, Frame, State>`, or `<Options, Token>`. */
   static fromRoute<Options extends ImageOptions>(
-    route: ImageModel.InlineRouteInput<Options>,
+    route: MediaModel.InlineRouteInput<ImageRequestFor<Options>, ImageResponse>,
     input: MediaRoute.ModelInput,
   ): ImageModel<Options>
   static fromRoute<Options extends ImageOptions, Frame, State>(
-    route: ImageModel.StreamRouteInput<Options, Frame, State>,
+    route: MediaModel.StreamRouteInput<ImageRequestFor<Options>, ImageEvent, Frame, State>,
     input: MediaRoute.ModelInput,
   ): ImageModel<Options>
   static fromRoute<Options extends ImageOptions, Token>(
-    route: ImageModel.QueuedRouteInput<Options, Token>,
+    route: MediaModel.QueuedRouteInput<ImageRequestFor<Options>, ImageResponse, Token>,
     input: MediaRoute.ModelInput,
   ): ImageModel<Options>
   static fromRoute<Options extends ImageOptions, Frame, State, Token>(
-    route: ImageModel.RouteInput<Options, Frame, State, Token>,
+    route: MediaModel.AnyRouteInput<ImageRequestFor<Options>, ImageEvent, ImageResponse, Frame, State, Token>,
     input: MediaRoute.ModelInput,
   ) {
     return new ImageModel<Options>({
       id: input.id,
-      provider: route.provider,
+      provider: route.protocol.provider,
       http: input.http,
-      route: composeAnyRoute(route, input, collectResponse),
+      route: composeRoute(route, input, collectResponse) as ImageRoute,
     })
   }
 }
 
-export namespace ImageModel {
-  export type InlineRouteInput<Options extends ImageOptions = ImageOptions> = MediaModel.RouteInput<
-    ImageRequestFor<Options>,
-    MediaProtocol.Inline<ImageRequestFor<Options>, ImageResponse>
-  >
-
-  export type StreamRouteInput<
-    Options extends ImageOptions = ImageOptions,
-    Frame = unknown,
-    State = unknown,
-  > = MediaModel.RouteInput<
-    MediaProtocol.Addressed<ImageRequestFor<Options>>,
-    MediaProtocol.Streamed<ImageRequestFor<Options>, ImageEvent, Frame, State>
-  >
-
-  export type QueuedRouteInput<Options extends ImageOptions = ImageOptions, Token = unknown> = MediaModel.RouteInput<
-    ImageRequestFor<Options>,
-    MediaProtocol.Queued<ImageRequestFor<Options>, ImageResponse, Token>
-  >
-
-  export type RouteInput<
-    Options extends ImageOptions = ImageOptions,
-    Frame = unknown,
-    State = unknown,
-    Token = unknown,
-  > = MediaModel.AnyRouteInput<ImageRequestFor<Options>, ImageEvent, ImageResponse, Frame, State, Token>
-}
-
 export const ImageModelSchema = Schema.declare((value): value is ImageModel => value instanceof ImageModel, {
   expected: "Image.Model",
 })
@@ -97,7 +60,7 @@ export const ImageSize = Schema.declare<ImageSize>(
 export type ImageAspectRatio = Media.AspectRatio
 export const ImageAspectRatio = Media.AspectRatio
 
-export type ImageFormat = "png" | "jpeg" | "webp" | (string & {})
+export type ImageFormat = OpenString<"png" | "jpeg" | "webp">
 
 export class ImageRequest extends Schema.Class<ImageRequest>("Image.Request")({
   model: ImageModelSchema,
@@ -190,15 +153,6 @@ export const ImageEvent = Object.assign(imageEventTagged, {
 })
 export type ImageEvent = Schema.Schema.Type<typeof imageEventTagged>
 
-export const responseEvents = (response: ImageResponse): ReadonlyArray<ImageEvent> => [
-  ...response.images.map((image, index) => ImageOutputEvent.make({ index, image })),
-  ImageFinishEvent.make({
-    usage: response.usage,
-    notices: response.notices,
-    providerMetadata: response.providerMetadata,
-  }),
-]
-
 const collectResponse = (events: ReadonlyArray<ImageEvent>): Effect.Effect<ImageResponse> => {
   const finish = events.find(ImageEvent.is.finish)
   // Every image protocol's `finish` emits the terminal event or fails, so a completed stream always has one.
@@ -225,43 +179,38 @@ export function request(input: ImageRequest | ImageRequestInput) {
   if (input instanceof ImageRequest) return input
   return new ImageRequest({
     ...input,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+    http: HttpOptions.make(input.http),
   })
 }
 
 const requestEffect = (input: ImageRequest | ImageRequestInput) => tryRequest(() => request(input))
 
 export function generate<const Model extends ImageModel>(
-  input: ImageRequestInput<Model>,
+  input: ImageRequest | ImageRequestInput<Model>,
   options?: AwaitOptions,
 ): Effect.Effect<ImageResponse, AIError, Service>
-export function generate(input: ImageRequest, options?: AwaitOptions): Effect.Effect<ImageResponse, AIError, Service>
 export function generate(input: ImageRequest | ImageRequestInput, options?: AwaitOptions) {
   return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.generate(request, options)))
 }
 
 export function stream<const Model extends ImageModel>(
-  input: ImageRequestInput<Model>,
+  input: ImageRequest | ImageRequestInput<Model>,
   options?: AwaitOptions,
 ): Stream.Stream<ImageEvent, AIError, Service>
-export function stream(input: ImageRequest, options?: AwaitOptions): Stream.Stream<ImageEvent, AIError, Service>
 export function stream(input: ImageRequest | ImageRequestInput, options?: AwaitOptions) {
   return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => ImageClient.stream(request, options))))
 }
 
 /** Inline and streaming routes fail with `UnsupportedOperation`. */
 export function start<const Model extends ImageModel>(
-  input: ImageRequestInput<Model>,
+  input: ImageRequest | ImageRequestInput<Model>,
 ): Effect.Effect<Generation<ImageResponse>, AIError, Service>
-export function start(input: ImageRequest): Effect.Effect<Generation<ImageResponse>, AIError, Service>
 export function start(input: ImageRequest | ImageRequestInput) {
   return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.start(request)))
 }
 
-export const resume = <Options extends ImageOptions>(
-  model: ImageModel<Options>,
-  token: unknown,
-): Effect.Effect<Generation<ImageResponse>, AIError, Service> => ImageClient.resume(model, token)
+export const resume = (model: ImageModel, token: unknown): Effect.Effect<Generation<ImageResponse>, AIError, Service> =>
+  ImageClient.resume(model, token)
 
 export const Image = {
   request,

packages/ai/src/llm.ts

@@ -1,5 +1,6 @@
-import { Effect, JsonSchema, Schema } from "effect"
-import { LLMClient, Service } from "./route/client.js"
+import { Effect, JsonSchema, Schema, Stream } from "effect"
+import { tryRequest } from "./media-model.js"
+import { LLMClient, Service, type StreamOptions } from "./route/client.js"
 import {
   GenerationOptions,
   HttpOptions,
@@ -35,9 +36,26 @@ export type RequestInput<SelectedLanguageModel extends LanguageModel = LanguageM
   readonly http?: HttpOptions.Input
 }
 
-export const generate = LLMClient.generate
+export function generate<const Model extends LanguageModel>(
+  input: RequestInput<Model>,
+  options?: StreamOptions,
+): Effect.Effect<LLMResponse, AIError, Service>
+export function generate(input: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, AIError, Service>
+export function generate(input: RequestInput | LLMRequest, options?: StreamOptions) {
+  return requestEffect(input).pipe(Effect.flatMap((request) => LLMClient.generate(request, options)))
+}
 
-export const stream = LLMClient.stream
+export function stream<const Model extends LanguageModel>(
+  input: RequestInput<Model>,
+  options?: StreamOptions,
+): Stream.Stream<LLMEvent, AIError, Service>
+export function stream(input: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, AIError, Service>
+export function stream(input: RequestInput | LLMRequest, options?: StreamOptions) {
+  return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => LLMClient.stream(request, options))))
+}
+
+const requestEffect = (input: RequestInput | LLMRequest) =>
+  input instanceof LLMRequest ? Effect.succeed(input) : tryRequest(() => request(input))
 
 export const request = <const SelectedLanguageModel extends LanguageModel>(
   input: RequestInput<SelectedLanguageModel>,
@@ -61,7 +79,7 @@ export const request = <const SelectedLanguageModel extends LanguageModel>(
     toolChoice: requestToolChoice ? ToolChoice.make(requestToolChoice) : undefined,
     generation: requestGeneration === undefined ? undefined : GenerationOptions.make(requestGeneration),
     providerOptions: requestProviderOptions,
-    http: requestHttp === undefined ? undefined : HttpOptions.make(requestHttp),
+    http: HttpOptions.make(requestHttp),
   })
 }
 

packages/ai/src/media-client.ts

@@ -0,0 +1,77 @@
+import { type Context, Effect, Layer, Stream } from "effect"
+import { resultEvents, type AwaitOptions, type Generation, type Observation } from "./generation.js"
+import { RequestExecutor } from "./route/executor.js"
+import type { MediaRoute } from "./route/media.js"
+import { AIError, UnsupportedOperationError } from "./schema/index.js"
+
+/** A media request whose model carries the route that executes it. */
+export interface RoutedRequest<Self extends MediaRoute.MediaRequest, Event, Response> extends MediaRoute.MediaRequest {
+  readonly model: MediaRoute.MediaRequest["model"] & { readonly route: MediaRoute.AnyRoute<Self, Event, Response> }
+}
+
+/** `start` and `resume` fail with `UnsupportedOperation` on inline and stream routes. */
+export interface Interface<Req extends RoutedRequest<Req, Event, Response>, Event, Response> {
+  readonly generate: (request: Req, options?: AwaitOptions) => Effect.Effect<Response, AIError>
+  readonly stream: (request: Req, options?: AwaitOptions) => Stream.Stream<Event | Observation, AIError>
+  readonly start: (request: Req) => Effect.Effect<Generation<Response>, AIError>
+  readonly resume: (model: Req["model"], token: unknown) => Effect.Effect<Generation<Response>, AIError>
+}
+
+/** One modality's layer and service accessors, dispatching each request on its route's `kind`. */
+export const make = <Self, Req extends RoutedRequest<Req, Event, Response>, Event, Response>(
+  service: Context.Service<Self, Interface<Req, Event, Response>>,
+  input: {
+    readonly modality: string
+    /** A completed response expanded into the streaming event shape. */
+    readonly responseEvents: (response: Response) => ReadonlyArray<Event>
+  },
+) => ({
+  layer: Layer.effect(
+    service,
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const notQueued = (route: MediaRoute.AnyRoute<Req, Event, Response>, operation: string) =>
+        new AIError({
+          reason: new UnsupportedOperationError({
+            operation: `${input.modality}.${operation}`,
+            provider: route.provider,
+            route: route.id,
+            message: `${route.provider}/${route.id} is not a queued route; use generate or stream`,
+          }),
+        })
+      const start = (request: Req) => {
+        const route = request.model.route
+        if (route.kind !== "queued") return Effect.fail(notQueued(route, "start"))
+        return route.start(request, executor.execute)
+      }
+      return service.of({
+        start,
+        resume: (model, token) => {
+          if (model.route.kind !== "queued") return Effect.fail(notQueued(model.route, "resume"))
+          return model.route.resume(model, token, executor.execute)
+        },
+        generate: (request, options) => {
+          const route = request.model.route
+          if (route.kind !== "queued") return route.generate(request, executor.execute)
+          return start(request).pipe(Effect.flatMap((generation) => generation.await(options)))
+        },
+        stream: (request, options) => {
+          const route = request.model.route
+          if (route.kind === "stream") return route.stream(request, executor.execute)
+          if (route.kind === "queued")
+            return Stream.unwrap(
+              start(request).pipe(Effect.map((generation) => resultEvents(generation, input.responseEvents, options))),
+            )
+          return Stream.fromIterableEffect(Effect.map(route.generate(request, executor.execute), input.responseEvents))
+        },
+      })
+    }),
+  ),
+  generate: (request: Req, options?: AwaitOptions) => service.use((client) => client.generate(request, options)),
+  stream: (request: Req, options?: AwaitOptions) =>
+    Stream.unwrap(service.useSync((client) => client.stream(request, options))),
+  start: (request: Req) => service.use((client) => client.start(request)),
+  resume: (model: Req["model"], token: unknown) => service.use((client) => client.resume(model, token)),
+})
+
+export * as MediaClient from "./media-client.js"

packages/ai/src/media-model.ts

@@ -6,11 +6,13 @@ import { AIError, HttpOptions, InvalidRequestError, ModelID, ProviderID } from "
 
 /**
  * What every media model carries: ids, the configured route, and deployment `http` overlays. Modality classes
- * (`ImageModel`, `VideoModel`, `SpeechModel`) extend it with their route type and a nominal marker so one cannot stand
- * in for the other in requests.
+ * (`ImageModel`, `VideoModel`, `SpeechModel`, `TranscriptionModel`) extend it with their route type and a nominal
+ * marker so one cannot stand in for the other in requests.
  */
 export class MediaModel<Route, Options> {
-  declare protected readonly _Options: (options: Options) => Options
+  // As with `LanguageModel`, the route type is erased over `Options`; `fromRoute` and the constructor trust that the
+  // route accepts every request this model's `Options` admit.
+  declare protected readonly _Options: Options
   readonly id: ModelID
   readonly provider: ProviderID
   readonly route: Route
@@ -25,6 +27,8 @@ export class MediaModel<Route, Options> {
 }
 
 export namespace MediaModel {
+  export type Options = Record<string, unknown>
+
   export interface Input<Route> {
     readonly id: string | ModelID
     readonly provider: string | ProviderID
@@ -34,8 +38,6 @@ export namespace MediaModel {
 
   /** A protocol plus its canonical start path; `ModelInput.baseURL` overrides `baseURL` per deployment. */
   export interface RouteInput<Request extends MediaRoute.MediaRequest, Protocol> {
-    readonly id: string
-    readonly provider: string | ProviderID
     readonly protocol: Protocol
     readonly path: Endpoint.EndpointPart<MediaProtocol.Body, Request>
     readonly baseURL?: string
@@ -43,50 +45,56 @@ export namespace MediaModel {
     readonly headers?: Record<string, string>
   }
 
+  export type InlineRouteInput<Request extends MediaRoute.MediaRequest, Response> = RouteInput<
+    Request,
+    MediaProtocol.Inline<Request, Response>
+  >
+
+  export type StreamRouteInput<Request extends MediaRoute.MediaRequest, Event, Frame, State> = RouteInput<
+    MediaProtocol.Addressed<Request>,
+    MediaProtocol.Streamed<Request, Event, Frame, State>
+  >
+
+  export type QueuedRouteInput<Request extends MediaRoute.MediaRequest, Response, Token> = RouteInput<
+    Request,
+    MediaProtocol.Queued<Request, Response, Token>
+  >
+
   export type AnyRouteInput<Request extends MediaRoute.MediaRequest, Event, Response, Frame, State, Token> =
-    | RouteInput<Request, MediaProtocol.Inline<Request, Response>>
-    | RouteInput<MediaProtocol.Addressed<Request>, MediaProtocol.Streamed<Request, Event, Frame, State>>
-    | RouteInput<Request, MediaProtocol.Queued<Request, Response, Token>>
+    | InlineRouteInput<Request, Response>
+    | StreamRouteInput<Request, Event, Frame, State>
+    | QueuedRouteInput<Request, Response, Token>
 }
 
 /** Compose a protocol route input with one deployment through `MediaRoute.inline`, `queued`, or `stream`. */
-export const composeRoute = <Request extends MediaRoute.MediaRequest, Protocol, Route>(
-  compose: (input: MediaRoute.Composition<Request> & { readonly protocol: Protocol }) => Route,
-  route: MediaModel.RouteInput<Request, Protocol>,
-  input: MediaRoute.ModelInput,
-): Route =>
-  compose({
-    id: route.id,
-    provider: route.provider,
-    protocol: route.protocol,
-    endpoint: Endpoint.path(route.path, { baseURL: input.baseURL ?? route.baseURL }),
-    auth: input.auth,
-    headers:
-      route.headers === undefined && input.headers === undefined ? undefined : { ...route.headers, ...input.headers },
-  })
-
-export const composeAnyRoute = <Request extends MediaRoute.MediaRequest, Event, Response, Frame, State, Token>(
+export const composeRoute = <Request extends MediaRoute.MediaRequest, Event, Response, Frame, State, Token>(
   route: MediaModel.AnyRouteInput<Request, Event, Response, Frame, State, Token>,
   input: MediaRoute.ModelInput,
   collect: (events: ReadonlyArray<Event>) => Effect.Effect<Response, AIError>,
 ): MediaRoute.AnyRoute<Request, Event, Response> => {
-  if (isStreamInput(route))
-    return composeRoute((composition) => MediaRoute.stream({ ...composition, collect }), route, input)
-  if (isQueuedInput(route)) return composeRoute(MediaRoute.queued, route, input)
-  return composeRoute(MediaRoute.inline, route, input)
+  if (isStreamInput(route)) return MediaRoute.stream({ ...composition(route, input), collect })
+  if (isQueuedInput(route)) return MediaRoute.queued(composition(route, input))
+  return MediaRoute.inline(composition(route, input))
 }
 
+const composition = <Request extends MediaRoute.MediaRequest, Protocol>(
+  route: MediaModel.RouteInput<Request, Protocol>,
+  input: MediaRoute.ModelInput,
+): MediaRoute.Composition<Request> & { readonly protocol: Protocol } => ({
+  protocol: route.protocol,
+  endpoint: Endpoint.path(route.path, { baseURL: input.baseURL ?? route.baseURL }),
+  auth: input.auth,
+  headers:
+    route.headers === undefined && input.headers === undefined ? undefined : { ...route.headers, ...input.headers },
+})
+
 const isStreamInput = <Request extends MediaRoute.MediaRequest, Event, Response, Frame, State, Token>(
   route: MediaModel.AnyRouteInput<Request, Event, Response, Frame, State, Token>,
-): route is MediaModel.RouteInput<
-  MediaProtocol.Addressed<Request>,
-  MediaProtocol.Streamed<Request, Event, Frame, State>
-> => route.protocol.kind === "stream"
+): route is MediaModel.StreamRouteInput<Request, Event, Frame, State> => route.protocol.kind === "stream"
 
 const isQueuedInput = <Request extends MediaRoute.MediaRequest, Event, Response, Frame, State, Token>(
   route: MediaModel.AnyRouteInput<Request, Event, Response, Frame, State, Token>,
-): route is MediaModel.RouteInput<Request, MediaProtocol.Queued<Request, Response, Token>> =>
-  route.protocol.kind === "queued"
+): route is MediaModel.QueuedRouteInput<Request, Response, Token> => route.protocol.kind === "queued"
 
 /** Lift a synchronous Schema-class constructor into a typed `InvalidRequest` failure. */
 export const tryRequest = <A>(make: () => A): Effect.Effect<A, AIError> =>

packages/ai/src/promise.ts

@@ -1,23 +1,22 @@
 import { Effect, Layer, ManagedRuntime, Stream } from "effect"
 import { AIClient } from "./ai-client.js"
 import type { AwaitOptions, Event, Generation, Snapshot } from "./generation.js"
-import { Image, ImageModel, ImageRequest, type ImageOptions, type ImageRequestInput } from "./image.js"
+import { Image, type ImageModel, type ImageRequest, type ImageRequestInput } from "./image.js"
 import { LLM } from "./index.js"
 import { Media } from "./media.js"
 import { tryRequest } from "./media-model.js"
 import { RequestExecutor } from "./route/executor.js"
 import { AIError, InvalidRequestError, LanguageModel, LLMRequest } from "./schema/index.js"
 import type { RequestInput } from "./llm.js"
-import { Speech, SpeechModel, SpeechRequest, type SpeechRequestInput } from "./speech.js"
+import { Speech, type SpeechModel, type SpeechRequest, type SpeechRequestInput } from "./speech.js"
 import {
   Transcription,
-  TranscriptionModel,
-  TranscriptionRequest,
-  type TranscriptionOptions,
+  type TranscriptionModel,
+  type TranscriptionRequest,
   type TranscriptionRequestInput,
 } from "./transcription.js"
 import { fileMediaType } from "./utils/media-type.js"
-import { Video, VideoModel, VideoRequest, type VideoOptions, type VideoRequestInput } from "./video.js"
+import { Video, type VideoModel, type VideoRequest, type VideoRequestInput } from "./video.js"
 
 /**
  * Promise-first entrypoint for scripts and non-Effect callers. One `ManagedRuntime` hosts the LLM, image, video, speech,
@@ -93,17 +92,8 @@ export const make = (options: Options = {}) => {
     cancel: (options) => run(generation.cancel(), options),
   })
 
-  // The typed `generate`/`stream` overloads take a concrete input or a request, not the union; normalize once here.
   const llmRequest = (input: RequestInput | LLMRequest) =>
     input instanceof LLMRequest ? Effect.succeed(input) : tryRequest(() => LLM.request(input))
-  const imageRequest = (input: ImageRequestInput | ImageRequest) =>
-    input instanceof ImageRequest ? input : Image.request(input)
-  const videoRequest = (input: VideoRequestInput | VideoRequest) =>
-    input instanceof VideoRequest ? input : Video.request(input)
-  const speechRequest = (input: SpeechRequestInput | SpeechRequest) =>
-    input instanceof SpeechRequest ? input : Speech.request(input)
-  const transcriptionRequest = (input: TranscriptionRequestInput | TranscriptionRequest) =>
-    input instanceof TranscriptionRequest ? input : Transcription.request(input)
 
   return {
     run,
@@ -155,61 +145,58 @@ export const make = (options: Options = {}) => {
       generate: <const Model extends ImageModel>(
         input: ImageRequestInput<Model> | ImageRequest,
         options?: AwaitOptions & RunOptions,
-      ) => run(Image.generate(imageRequest(input), { poll: options?.poll }), options),
+      ) => run(Image.generate(input, { poll: options?.poll }), options),
       stream: <const Model extends ImageModel>(
         input: ImageRequestInput<Model> | ImageRequest,
         options?: AwaitOptions & RunOptions,
-      ) => iterate(Image.stream(imageRequest(input), { poll: options?.poll }), options),
+      ) => iterate(Image.stream(input, { poll: options?.poll }), options),
       start: <const Model extends ImageModel>(input: ImageRequestInput<Model> | ImageRequest, options?: RunOptions) =>
-        run(Image.start(imageRequest(input)), options).then(handle),
-      resume: <Options extends ImageOptions>(model: ImageModel<Options>, token: unknown, options?: RunOptions) =>
+        run(Image.start(input), options).then(handle),
+      resume: (model: ImageModel, token: unknown, options?: RunOptions) =>
         run(Image.resume(model, token), options).then(handle),
     },
     video: {
       request: Video.request,
       start: <const Model extends VideoModel>(input: VideoRequestInput<Model> | VideoRequest, options?: RunOptions) =>
-        run(Video.start(videoRequest(input)), options).then(handle),
+        run(Video.start(input), options).then(handle),
       generate: <const Model extends VideoModel>(
         input: VideoRequestInput<Model> | VideoRequest,
         options?: AwaitOptions & RunOptions,
-      ) => run(Video.generate(videoRequest(input), { poll: options?.poll }), options),
-      resume: <Options extends VideoOptions>(model: VideoModel<Options>, token: unknown, options?: RunOptions) =>
+      ) => run(Video.generate(input, { poll: options?.poll }), options),
+      resume: (model: VideoModel, token: unknown, options?: RunOptions) =>
         run(Video.resume(model, token), options).then(handle),
       stream: <const Model extends VideoModel>(
         input: VideoRequestInput<Model> | VideoRequest,
         options?: AwaitOptions & RunOptions,
-      ) => iterate(Video.stream(videoRequest(input), { poll: options?.poll }), options),
+      ) => iterate(Video.stream(input, { poll: options?.poll }), options),
     },
     speech: {
       request: Speech.request,
       generate: <const Model extends SpeechModel>(
         input: SpeechRequestInput<Model> | SpeechRequest,
         options?: RunOptions,
-      ) => run(Speech.generate(speechRequest(input)), options),
+      ) => run(Speech.generate(input), options),
       stream: <const Model extends SpeechModel>(
         input: SpeechRequestInput<Model> | SpeechRequest,
         options?: RunOptions,
-      ) => iterate(Speech.stream(speechRequest(input)), options),
+      ) => iterate(Speech.stream(input), options),
     },
     transcription: {
       request: Transcription.request,
       generate: <const Model extends TranscriptionModel>(
         input: TranscriptionRequestInput<Model> | TranscriptionRequest,
         options?: AwaitOptions & RunOptions,
-      ) => run(Transcription.generate(transcriptionRequest(input), { poll: options?.poll }), options),
+      ) => run(Transcription.generate(input, { poll: options?.poll }), options),
       stream: <const Model extends TranscriptionModel>(
         input: TranscriptionRequestInput<Model> | TranscriptionRequest,
         options?: AwaitOptions & RunOptions,
-      ) => iterate(Transcription.stream(transcriptionRequest(input), { poll: options?.poll }), options),
+      ) => iterate(Transcription.stream(input, { poll: options?.poll }), options),
       start: <const Model extends TranscriptionModel>(
         input: TranscriptionRequestInput<Model> | TranscriptionRequest,
         options?: RunOptions,
-      ) => run(Transcription.start(transcriptionRequest(input)), options).then(handle),
-      resume: <Options extends TranscriptionOptions>(
-        model: TranscriptionModel<Options>,
-        token: unknown,
-        options?: RunOptions,
-      ) => run(Transcription.resume(model, token), options).then(handle),
+      ) => run(Transcription.start(input), options).then(handle),
+      resume: (model: TranscriptionModel, token: unknown, options?: RunOptions) =>
+        run(Transcription.resume(model, token), options).then(handle),
     },
     dispose: () => runtime.dispose(),
   }

packages/ai/src/protocols/alibaba-chat.ts

@@ -70,7 +70,11 @@ export const protocol = Protocol.make({
       return {
         ...(yield* OpenAIChat.protocol.body.from(req)),
         enable_thinking: opts.enableThinking,
-        thinking_budget: opts.thinkingBudget,
+        // Alibaba also rejects an explicit budget that is not below `max_completion_tokens`.
+        thinking_budget:
+          opts.thinkingBudget === undefined
+            ? undefined
+            : ProviderShared.fitThinkingBudget(opts.thinkingBudget, req.generation?.maxTokens),
         preserve_thinking: opts.preserveThinking,
         clear_thinking: opts.clearThinking,
         thinking: opts.thinking,

packages/ai/src/protocols/alibaba-messages.ts

@@ -26,18 +26,21 @@ export const protocol = Protocol.make({
     from: Effect.fn("AlibabaMessages.fromRequest")(function* (req) {
       const opts = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Options))(req.providerOptions ?? {})
       // Model Studio accepts enabled thinking without Anthropic's mandatory token budget.
+      const body = yield* AnthropicMessages.protocol.body.from(
+        LLMRequest.update(req, {
+          providerOptions: { ...req.providerOptions, thinking: undefined },
+        }),
+      )
+      const budget = opts.thinking?.budgetTokens ?? opts.thinking?.budget_tokens
       return {
-        ...(yield* AnthropicMessages.protocol.body.from(
-          LLMRequest.update(req, {
-            providerOptions: { ...req.providerOptions, thinking: undefined },
-          }),
-        )),
+        ...body,
         thinking:
           opts.thinking === undefined
             ? undefined
             : {
                 type: opts.thinking.type,
-                budget_tokens: opts.thinking.budgetTokens ?? opts.thinking.budget_tokens,
+                budget_tokens:
+                  budget === undefined ? undefined : ProviderShared.fitThinkingBudget(budget, body.max_tokens),
               },
       }
     }),

packages/ai/src/protocols/anthropic-messages.ts

@@ -18,7 +18,6 @@ import {
   type CacheHint,
   type FinishReasonDetails,
   type FinishReason,
-  type JsonSchema,
   type MediaPart,
   type ProviderMetadata,
   type ProviderOptions,
@@ -31,13 +30,13 @@ import { classifyProviderFailure } from "../provider-error.js"
 import { effortUpdate, resolveEffortUpdates } from "../effort-updates.js"
 import * as Cache from "./utils/cache.js"
 import { Lifecycle } from "./utils/lifecycle.js"
-import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "anthropic-messages"
 export const DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
 export const PATH = "/messages"
 export const DEFAULT_MAX_TOKENS = 32_000
+const MIN_THINKING_BUDGET = 1_024
 const DEFAULT_EFFORT = "high"
 
 const SSE_EVENTS = new Set([
@@ -524,10 +523,10 @@ const redactedDataFromMetadata = (metadata: ProviderMetadata | undefined, key: s
   return typeof provider.redactedData === "string" ? provider.redactedData : undefined
 }
 
-const lowerTool = (breakpoints: Cache.Breakpoints, tool: ToolDefinition, inputSchema: JsonSchema): AnthropicTool => ({
+const lowerTool = (breakpoints: Cache.Breakpoints, tool: ToolDefinition): AnthropicTool => ({
   name: tool.name,
   description: tool.description,
-  input_schema: inputSchema,
+  input_schema: tool.inputSchema,
   cache_control: cacheControl(breakpoints, tool.cache),
 })
 
@@ -1027,6 +1026,15 @@ const applyThinkingBindingDefault = (model: LLMRequest["model"], thinking: Anthr
   }
 }
 
+// Anthropic also requires an explicit thinking budget below `max_tokens` and at or above its minimum.
+const fitThinking = (thinking: AnthropicThinking | undefined, maxTokens: number) =>
+  thinking?.type === "enabled"
+    ? {
+        ...thinking,
+        budget_tokens: ProviderShared.fitThinkingBudget(thinking.budget_tokens, maxTokens, MIN_THINKING_BUDGET),
+      }
+    : thinking
+
 const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (request: LLMRequest) {
   const options = yield* decodeOptions(request.providerOptions ?? {})
   const management = options.contextManagement
@@ -1039,12 +1047,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
   // over-mark we keep their tool hints and shed the message-tail ones first.
   const breakpoints = Cache.newBreakpoints(ANTHROPIC_BREAKPOINT_CAP)
   const flattened = ProviderShared.flattenToolRequest(updates.request)
-  const tools =
-    flattened.tools.length === 0
-      ? undefined
-      : flattened.tools.map((tool) =>
-          lowerTool(breakpoints, tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model)),
-        )
+  const tools = flattened.tools.length === 0 ? undefined : flattened.tools.map((tool) => lowerTool(breakpoints, tool))
   // Anthropic rejects tool_choice when tools are absent; "none" is only meaningful with tools present.
   const toolChoice = tools === undefined || !request.toolChoice ? undefined : yield* lowerToolChoice(request.toolChoice)
   const systemParts = request.system.filter((part) => part.text.length > 0)
@@ -1064,6 +1067,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
   }
   const output_config =
     updates.effort === undefined && format === undefined ? undefined : { effort: updates.effort, format }
+  const maxTokens = generation?.maxTokens ?? DEFAULT_MAX_TOKENS
   const body = {
     model: request.model.id,
     system,
@@ -1071,12 +1075,12 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
     tools,
     tool_choice: toolChoice,
     stream: true as const,
-    max_tokens: generation?.maxTokens ?? DEFAULT_MAX_TOKENS,
+    max_tokens: maxTokens,
     temperature: generation?.temperature,
     top_p: generation?.topP,
     top_k: generation?.topK,
     stop_sequences: generation?.stop,
-    thinking: applyThinkingBindingDefault(request.model, options.thinking),
+    thinking: applyThinkingBindingDefault(request.model, fitThinking(options.thinking, maxTokens)),
     output_config,
     // top-level passthrough per SDK MessageCreateParamsBase:4638,4643,4649,4654,4670
     cache_control: options.cache_control ?? options.cacheControl,

packages/ai/src/protocols/assemblyai-transcription.ts

@@ -4,14 +4,12 @@ import type { Status } from "../generation.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { TranscriptionModel, TranscriptionResponse, type TranscriptionRequestFor } from "../transcription.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "assemblyai-transcription"
-const NAME = "AssemblyAI"
-const PROVIDER = ProviderID.make("assemblyai")
+const route = MediaProtocol.identity({ id: "assemblyai-transcription", name: "AssemblyAI", provider: "assemblyai" })
 export const DEFAULT_BASE_URL = "https://api.assemblyai.com"
 export const PATH = "/v2/transcript"
 export const UPLOAD_PATH = "/v2/upload"
@@ -33,7 +31,7 @@ export type AssemblyAITranscriptionOptions = {
     readonly fallback_language?: string
     readonly code_switching?: boolean
   }
-  readonly speech_models?: ReadonlyArray<"universal-3-5-pro" | "universal-2" | (string & {})>
+  readonly speech_models?: ReadonlyArray<OpenString<"universal-3-5-pro" | "universal-2">>
 } & Record<string, unknown>
 
 export type Request = TranscriptionRequestFor<AssemblyAITranscriptionOptions>
@@ -90,12 +88,12 @@ const STATUS = {
 // 5. Request body construction
 // ---------------------------------------------------------------------------
 
-const decodeUpload = MediaProtocol.decodeJson(ADAPTER, NAME, Upload)
+const decodeUpload = route.decodeJson(Upload)
 
 /** `/v2/transcript` only takes a URL, so inline audio is uploaded to `/v2/upload` first. */
 const prepare = Effect.fn("AssemblyAITranscription.prepare")(function* (request: Request, send: MediaProtocol.Send) {
   if (request.audio.source.type !== "bytes" && request.audio.source.type !== "base64") return request
-  const audio = yield* MediaInput.inlineBytes(ADAPTER, request.audio)
+  const audio = yield* MediaInput.inlineBytes(route.id, request.audio)
   const uploaded = yield* send(UPLOAD_PATH, MediaProtocol.binary(audio, "application/octet-stream")).pipe(
     Effect.flatMap(decodeUpload),
   )
@@ -103,7 +101,7 @@ const prepare = Effect.fn("AssemblyAITranscription.prepare")(function* (request:
 })
 
 const fromRequest = Effect.fn("AssemblyAITranscription.fromRequest")(function* (request: Request) {
-  const audio = yield* ProviderShared.mediaReference(request.audio, PROVIDER, NAME)
+  const audio = yield* ProviderShared.mediaReference(request.audio, route.provider, route.name)
   return MediaProtocol.json(
     mergeJsonRecords(
       {
@@ -126,7 +124,7 @@ const fromRequest = Effect.fn("AssemblyAITranscription.fromRequest")(function* (
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeTranscript = MediaProtocol.decodeJson(ADAPTER, NAME, Transcript)
+const decodeTranscript = route.decodeJson(Transcript)
 
 const decodeStart = Effect.fn("AssemblyAITranscription.decodeStart")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -156,9 +154,9 @@ const decodeResult = Effect.fn("AssemblyAITranscription.decodeResult")(function*
   const status = yield* MediaProtocol.status(STATUS, transcript.status, output)
   const error = transcript.error ?? undefined
   if (status === "failed")
-    return yield* output.ended("failed", `${NAME} transcription failed${error === undefined ? "" : `: ${error}`}`)
+    return yield* output.ended("failed", `${route.name} transcription failed${error === undefined ? "" : `: ${error}`}`)
   if (status !== "completed")
-    return yield* output.invalid(`${NAME} transcript ${context.token.transcriptID} has not finished`)
+    return yield* output.invalid(`${route.name} transcript ${context.token.transcriptID} has not finished`)
   const duration = transcript.audio_duration ?? undefined
   return new TranscriptionResponse({
     text: transcript.text ?? "",
@@ -190,9 +188,7 @@ const decodeResult = Effect.fn("AssemblyAITranscription.decodeResult")(function*
 
 const transcriptPath = (token: Token) => `${PATH}/${token.transcriptID}`
 
-export const protocol = MediaProtocol.queued<Request, TranscriptionResponse, Token>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.queued<Request, TranscriptionResponse, Token>(route, {
   token: Token,
   start: { prepare, body: { from: fromRequest }, decode: decodeStart },
   status: { path: transcriptPath, decode: decodeStatus },
@@ -201,7 +197,7 @@ export const protocol = MediaProtocol.queued<Request, TranscriptionResponse, Tok
 
 export const model = (input: MediaRoute.ModelInput) =>
   TranscriptionModel.fromRoute<AssemblyAITranscriptionOptions, Token>(
-    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
     input,
   )
 

packages/ai/src/protocols/bedrock-converse.ts

@@ -9,7 +9,6 @@ import {
   type CacheHint,
   type FinishReason,
   type FinishReasonDetails,
-  type JsonSchema,
   type LLMRequest,
   type LanguageModel,
   type ProviderMetadata,
@@ -26,7 +25,6 @@ import { BedrockCache } from "./utils/bedrock-cache.js"
 import { BedrockMedia } from "./utils/bedrock-media.js"
 import { Lifecycle } from "./utils/lifecycle.js"
 import { MistralToolID } from "./utils/mistral-tool-id.js"
-import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 import { concatBytes } from "../utils/bytes.js"
 
@@ -221,22 +219,18 @@ type BedrockEvent = Schema.Schema.Type<typeof BedrockEvent>
 // =============================================================================
 // Request Lowering
 // =============================================================================
-const lowerToolSpec = (tool: ToolDefinition, inputSchema: JsonSchema): BedrockToolSpec => ({
+const lowerToolSpec = (tool: ToolDefinition): BedrockToolSpec => ({
   toolSpec: {
     name: tool.name,
     ...(tool.description.trim().length > 0 ? { description: tool.description } : {}),
-    inputSchema: { json: inputSchema },
+    inputSchema: { json: tool.inputSchema },
   },
 })
 
-const lowerTools = (
-  model: LanguageModel,
-  breakpoints: BedrockCache.Breakpoints,
-  tools: ReadonlyArray<ToolDefinition>,
-): BedrockTool[] => {
+const lowerTools = (breakpoints: BedrockCache.Breakpoints, tools: ReadonlyArray<ToolDefinition>): BedrockTool[] => {
   const result: BedrockTool[] = []
   for (const tool of tools) {
-    result.push(lowerToolSpec(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, model)))
+    result.push(lowerToolSpec(tool))
     const cachePoint = BedrockCache.block(breakpoints, tool.cache)
     if (cachePoint) result.push(cachePoint)
   }
@@ -430,17 +424,50 @@ const lowerSystem = (breakpoints: BedrockCache.Breakpoints, system: ReadonlyArra
   return content.length === 0 ? undefined : content
 }
 
+// Nova 2 rejects `maxTokens` at high reasoning effort, where its output can exceed the field's maximum. Other models
+// that take `reasoningConfig`, such as Grok on Bedrock, accept it.
+const isNova2 = (model: LanguageModel) => /\bamazon\.nova-2-/.test(model.id)
+const isHighReasoningEffort = Schema.is(
+  Schema.Struct({
+    additionalModelRequestFields: Schema.Struct({
+      reasoningConfig: Schema.Struct({ maxReasoningEffort: Schema.Literal("high") }),
+    }),
+  }),
+)
+
+const Options = Schema.Struct({
+  thinking: Schema.optional(Schema.Struct({ type: Schema.Literal("enabled"), budgetTokens: Schema.Number })),
+})
+export type OptionsInput = typeof Options.Type
+const decodeOptions = ProviderShared.validateWith(Schema.decodeUnknownEffect(Options))
+// Claude on Bedrock requires the thinking budget below `maxTokens`, with a minimum of 1,024.
+const MIN_THINKING_BUDGET = 1_024
+
 const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request: LLMRequest) {
   const toolChoice = request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined
   const flattened = ProviderShared.flattenToolRequest(request)
   const generation = request.generation
+  const options = yield* decodeOptions(request.providerOptions ?? {})
+  const maxTokens =
+    isNova2(request.model) && isHighReasoningEffort(request.http?.body) ? undefined : generation?.maxTokens
+  const thinking =
+    options.thinking === undefined
+      ? undefined
+      : {
+          type: "enabled",
+          budget_tokens: ProviderShared.fitThinkingBudget(
+            options.thinking.budgetTokens,
+            maxTokens,
+            MIN_THINKING_BUDGET,
+          ),
+        }
   // Bedrock-Claude shares Anthropic's 4-breakpoint cap. Spend the budget in
   // tools → system → messages order to favour the highest-impact prefixes.
   const breakpoints = BedrockCache.breakpoints(request.model.id)
   const toolConfig = (() => {
     if (flattened.tools.length === 0) return undefined
     return {
-      tools: lowerTools(request.model, breakpoints, flattened.tools),
+      tools: lowerTools(breakpoints, flattened.tools),
       // Converse has no native "none". Keep definitions stable for prompt
       // caching and omit only the unsupported choice.
       toolChoice,
@@ -455,14 +482,14 @@ const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request:
   }
   const inferenceConfig = (() => {
     if (
-      generation?.maxTokens === undefined &&
+      maxTokens === undefined &&
       generation?.temperature === undefined &&
       generation?.topP === undefined &&
       (generation?.stop === undefined || generation.stop.length === 0)
     )
       return undefined
     return {
-      maxTokens: generation?.maxTokens,
+      maxTokens,
       temperature: generation?.temperature,
       topP: generation?.topP,
       stopSequences: generation?.stop,
@@ -474,9 +501,15 @@ const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request:
     system,
     inferenceConfig,
     toolConfig,
-    // Converse's base inferenceConfig has no topK; Anthropic/Nova accept it
-    // as a model-specific field, so it goes through additionalModelRequestFields.
-    additionalModelRequestFields: generation?.topK === undefined ? undefined : { top_k: generation.topK },
+    // Converse's base inferenceConfig has no topK or thinking; Anthropic/Nova accept them
+    // as model-specific fields, so they go through additionalModelRequestFields.
+    additionalModelRequestFields:
+      generation?.topK === undefined && thinking === undefined
+        ? undefined
+        : {
+            ...(generation?.topK === undefined ? {} : { top_k: generation.topK }),
+            ...(thinking === undefined ? {} : { thinking }),
+          },
   }
 })
 

packages/ai/src/protocols/bfl-images.ts

@@ -5,13 +5,11 @@ import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords } from "../schema/index.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "bfl-images"
-const NAME = "Black Forest Labs"
-const PROVIDER = ProviderID.make("black-forest-labs")
+const route = MediaProtocol.identity({ id: "bfl-images", name: "Black Forest Labs", provider: "black-forest-labs" })
 export const DEFAULT_BASE_URL = "https://api.bfl.ai"
 
 // ---------------------------------------------------------------------------
@@ -94,33 +92,26 @@ const capabilities = (model: string): Capabilities => {
   return { sizing: "dimensions", imageField: "input_image", maxImages: 8, mask: false }
 }
 
-const unsupported = (model: string, field: string, message: string) =>
-  ProviderShared.unsupportedOperation({
-    operation: `media.${field}`,
-    provider: PROVIDER,
-    route: ADAPTER,
-    message: `${model} ${message}`,
-  })
-
 const validate = (request: Request, model: Capabilities) => {
   const id = request.model.id
   const images = request.images?.length ?? 0
   if (request.n !== undefined && request.n > 1)
-    return Effect.fail(unsupported(id, "n", "generates one image per request; call it once per image"))
+    return Effect.fail(route.unsupported("media.n", `${id} generates one image per request; call it once per image`))
   if (request.size !== undefined && model.sizing !== "dimensions")
-    return Effect.fail(unsupported(id, "size", "does not take size (width and height)"))
+    return Effect.fail(route.unsupported("media.size", `${id} does not take size (width and height)`))
   if (request.aspectRatio !== undefined && model.sizing !== "aspectRatio")
-    return Effect.fail(unsupported(id, "aspectRatio", "does not take aspectRatio"))
-  if (images > model.maxImages) return Effect.fail(unsupported(id, "images", `takes at most ${model.maxImages} images`))
+    return Effect.fail(route.unsupported("media.aspectRatio", `${id} does not take aspectRatio`))
+  if (images > model.maxImages)
+    return Effect.fail(route.unsupported("media.images", `${id} takes at most ${model.maxImages} images`))
   if (request.mask !== undefined && !model.mask)
-    return Effect.fail(unsupported(id, "mask", "does not inpaint; use flux-pro-1.0-fill"))
+    return Effect.fail(route.unsupported("media.mask", `${id} does not inpaint; use flux-pro-1.0-fill`))
   return Effect.void
 }
 
 const imageInput = (asset: Media.Asset) => {
   const value = asset.inline()?.base64 ?? ProviderShared.mediaUrl(asset)
   if (value === undefined)
-    return Effect.fail(ProviderShared.invalidRequest(`${NAME} accepts inline images or https URLs`))
+    return Effect.fail(ProviderShared.invalidRequest(`${route.name} accepts inline images or https URLs`))
   return Effect.succeed(value)
 }
 
@@ -153,12 +144,12 @@ const fromRequest = Effect.fn("BlackForestLabsImages.fromRequest")(function* (re
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeStart = MediaProtocol.decodeStarted(ADAPTER, NAME, StartResponse, (value) => ({
+const decodeStart = route.decodeStarted(StartResponse, (value) => ({
   token: { id: value.id, pollingURL: value.polling_url },
   snapshot: { id: value.id, status: "queued" },
 }))
 
-const decodeDocument = MediaProtocol.decodeJson(ADAPTER, NAME, Result)
+const decodeDocument = route.decodeJson(Result)
 
 const decodeStatus = Effect.fn("BlackForestLabsImages.decodeStatus")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -175,11 +166,11 @@ const decodeResult = Effect.fn("BlackForestLabsImages.decodeResult")(function* (
   const output = yield* decodeDocument(response)
   const document = output.value
   const status = yield* MediaProtocol.status(STATUS, document.status, output)
-  if (isModerated(document.status)) return yield* output.contentPolicy(`${NAME} moderated the generation`)
+  if (isModerated(document.status)) return yield* output.contentPolicy(`${route.name} moderated the generation`)
   if (status === "failed" || status === "expired")
-    return yield* output.ended(status, `${NAME} generation ${context.token.id} ended with ${document.status}`)
+    return yield* output.ended(status, `${route.name} generation ${context.token.id} ended with ${document.status}`)
   if (status !== "completed" || document.result === undefined || document.result === null)
-    return yield* output.invalid(`${NAME} generation ${context.token.id} has no result`)
+    return yield* output.invalid(`${route.name} generation ${context.token.id} has no result`)
   const { sample, seed, prompt, ...rest } = document.result
   return new ImageResponse({
     // `sample` is a signed URL that expires 10 minutes after the result is ready, so it is downloaded now.
@@ -196,9 +187,7 @@ const decodeResult = Effect.fn("BlackForestLabsImages.decodeResult")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.queued<Request, ImageResponse, Token>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.queued<Request, ImageResponse, Token>(route, {
   token: Token,
   start: { body: { from: fromRequest }, decode: decodeStart },
   status: { path: (token) => token.pollingURL, decode: decodeStatus },
@@ -207,13 +196,7 @@ export const protocol = MediaProtocol.queued<Request, ImageResponse, Token>({
 
 export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<BlackForestLabsImageOptions, Token>(
-    {
-      id: ADAPTER,
-      provider: PROVIDER,
-      protocol,
-      baseURL: DEFAULT_BASE_URL,
-      path: ({ request }) => `/v1/${request.model.id}`,
-    },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: ({ request }) => `/v1/${request.model.id}` },
     input,
   )
 

packages/ai/src/protocols/cartesia-speech.ts

@@ -3,14 +3,12 @@ import { classifyProviderFailure } from "../provider-error.js"
 import { Framing } from "../route/framing.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { AIError, ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { AIError, mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { SpeechModel, type SpeechEvent, type SpeechRequestFor } from "../speech.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 import { SpeechStream } from "./utils/speech-stream.js"
 
-const ADAPTER = "cartesia-speech"
-const NAME = "Cartesia"
-const PROVIDER = ProviderID.make("cartesia")
+const route = MediaProtocol.identity({ id: "cartesia-speech", name: "Cartesia", provider: "cartesia" })
 export const DEFAULT_BASE_URL = "https://api.cartesia.ai"
 export const API_VERSION = "2026-08-14"
 export const BYTES_PATH = "/tts/bytes"
@@ -22,8 +20,6 @@ const DEFAULT_BIT_RATE = 128000
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type CartesiaSpeechString<Known extends string> = Known | (string & {})
-
 export type CartesiaEncoding = SpeechStream.PcmEncoding
 
 export type CartesiaSpeechOptions = {
@@ -32,7 +28,7 @@ export type CartesiaSpeechOptions = {
   readonly encoding?: CartesiaEncoding
   readonly generation_config?: {
     readonly volume?: number
-    readonly emotion?: CartesiaSpeechString<"neutral" | "calm" | "angry" | "content" | "sad" | "scared">
+    readonly emotion?: OpenString<"neutral" | "calm" | "angry" | "content" | "sad" | "scared">
   }
   readonly pronunciation_dict_id?: string
 } & Record<string, unknown>
@@ -60,7 +56,7 @@ const SseEvent = Schema.Struct({
   error_code: optionalNull(Schema.String),
 })
 
-const decodeEvent = MediaProtocol.decodeFrame(ADAPTER, NAME, SseEvent)
+const decodeEvent = route.decodeFrame(SseEvent)
 
 // ---------------------------------------------------------------------------
 // 4. Parser state
@@ -84,16 +80,14 @@ const outputFormat = Effect.fn("CartesiaSpeech.outputFormat")(function* (request
   const format = request.format ?? (sse ? "pcm" : "mp3")
   const container = CONTAINERS[format]
   if (container === undefined)
-    return yield* SpeechStream.unsupportedFormat(
-      PROVIDER,
-      ADAPTER,
-      `${NAME} supports the pcm, wav, and mp3 formats, not "${format}"`,
+    return yield* route.unsupported(
+      "media.format",
+      `${route.name} supports the pcm, wav, and mp3 formats, not "${format}"`,
     )
   if (sse && container !== "raw")
-    return yield* SpeechStream.unsupportedFormat(
-      PROVIDER,
-      ADAPTER,
-      `${NAME} streams and timestamps only raw PCM; request format "pcm" instead of "${format}"`,
+    return yield* route.unsupported(
+      "media.format",
+      `${route.name} streams and timestamps only raw PCM; request format "pcm" instead of "${format}"`,
     )
   const sampleRate = request.providerOptions?.sampleRate ?? DEFAULT_SAMPLE_RATE
   if (container === "mp3")
@@ -104,7 +98,7 @@ const outputFormat = Effect.fn("CartesiaSpeech.outputFormat")(function* (request
 const fromRequest = Effect.fn("CartesiaSpeech.fromRequest")(function* (request: MediaProtocol.Addressed<Request>) {
   const voice = SpeechStream.voiceID(request.voice)
   if (voice === undefined)
-    return yield* ProviderShared.invalidRequest(`${NAME} requires a voice id; pass it as \`voice\``)
+    return yield* ProviderShared.invalidRequest(`${route.name} requires a voice id; pass it as \`voice\``)
   const { sampleRate: _sampleRate, bitRate: _bitRate, encoding: _encoding, ...native } = request.providerOptions ?? {}
   return MediaProtocol.json(
     mergeJsonRecords(
@@ -138,7 +132,7 @@ const onEvent = Effect.fn("CartesiaSpeech.onEvent")(function* (state: State, fra
   if (event.type === "error")
     return yield* new AIError({
       reason: classifyProviderFailure({
-        message: `${NAME} stream failed${event.title === undefined ? "" : ` (${event.title})`}: ${event.message ?? "unknown error"}`,
+        message: `${route.name} stream failed${event.title === undefined ? "" : ` (${event.title})`}: ${event.message ?? "unknown error"}`,
         status: event.status_code,
         rawBody: frame,
       }),
@@ -150,10 +144,10 @@ const finish = Effect.fn("CartesiaSpeech.finish")(function* (
   state: State,
   context: MediaProtocol.ResponseContext<Request>,
 ) {
-  if (usesSse(context.request) && !state.done) return yield* MediaProtocol.incomplete(ADAPTER)
+  if (usesSse(context.request) && !state.done) return yield* route.incomplete()
   const format = yield* outputFormat(context.request)
   return yield* SpeechStream.finish(
-    ADAPTER,
+    route,
     state,
     format.container === "raw"
       ? SpeechStream.pcm(format.encoding, format.sample_rate)
@@ -165,9 +159,7 @@ const finish = Effect.fn("CartesiaSpeech.finish")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint8Array, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint8Array, State>(route, {
   unsupported: ["instructions"],
   body: { from: fromRequest },
   frames: (bytes, context) => (usesSse(context.request) ? Framing.sse.frame(bytes) : bytes),
@@ -179,8 +171,6 @@ export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint
 export const model = (input: MediaRoute.ModelInput) =>
   SpeechModel.fromRoute<CartesiaSpeechOptions, string | Uint8Array, State>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       headers: { "Cartesia-Version": API_VERSION },

packages/ai/src/protocols/deepgram-speech.ts

@@ -1,14 +1,12 @@
 import { Effect } from "effect"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { SpeechModel, type SpeechEvent, type SpeechRequestFor } from "../speech.js"
 import { MediaInput } from "./utils/media-input.js"
 import { SpeechStream } from "./utils/speech-stream.js"
 
-const ADAPTER = "deepgram-speech"
-const NAME = "Deepgram"
-const PROVIDER = ProviderID.make("deepgram")
+const route = MediaProtocol.identity({ id: "deepgram-speech", name: "Deepgram", provider: "deepgram" })
 export const DEFAULT_BASE_URL = "https://api.deepgram.com"
 export const PATH = "/v1/speak"
 
@@ -16,13 +14,11 @@ export const PATH = "/v1/speak"
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type DeepgramSpeechString<Known extends string> = Known | (string & {})
-
-export type DeepgramEncoding = DeepgramSpeechString<"linear16" | "mulaw" | "alaw" | "mp3" | "opus" | "flac" | "aac">
+export type DeepgramEncoding = OpenString<"linear16" | "mulaw" | "alaw" | "mp3" | "opus" | "flac" | "aac">
 
 export type DeepgramSpeechOptions = {
   readonly encoding?: DeepgramEncoding
-  readonly container?: DeepgramSpeechString<"wav" | "ogg" | "none">
+  readonly container?: OpenString<"wav" | "ogg" | "none">
   readonly sampleRate?: number
   readonly bitRate?: number
   readonly mip_opt_out?: boolean
@@ -60,7 +56,7 @@ const audioFormat = (request: Request) => {
 
 const queryParameters = (request: Request) => {
   const { encoding: _encoding, container: _container, sampleRate, bitRate, ...native } = request.providerOptions ?? {}
-  return MediaInput.query(ADAPTER, {
+  return MediaInput.query(route.id, {
     ...native,
     model: request.model.id,
     ...audioFormat(request),
@@ -76,10 +72,9 @@ const fromRequest = Effect.fn("DeepgramSpeech.fromRequest")(function* (request:
     FORMATS[request.format] === undefined &&
     request.providerOptions?.encoding === undefined
   )
-    return yield* SpeechStream.unsupportedFormat(
-      PROVIDER,
-      ADAPTER,
-      `${NAME} has no encoding for format "${request.format}"; pass providerOptions.encoding`,
+    return yield* route.unsupported(
+      "media.format",
+      `${route.name} has no encoding for format "${request.format}"; pass providerOptions.encoding`,
     )
   return MediaProtocol.json(
     mergeJsonRecords({ text: request.text }, request.http?.body) ?? {},
@@ -104,7 +99,7 @@ const finish = (state: State, context: MediaProtocol.ResponseContext<Request>) =
   const encoding = HEADERLESS_ENCODINGS[format.encoding ?? ""]
   const requestID = headers["dg-request-id"]
   const modelName = headers["dg-model-name"]
-  return SpeechStream.finish(ADAPTER, state, {
+  return SpeechStream.finish(route, state, {
     ...(format.container === "none" && encoding !== undefined
       ? SpeechStream.pcm(encoding, SpeechStream.sampleRate(mediaType), mediaType)
       : // Deepgram's default encoding is MP3; WAV is a container around any encoding.
@@ -121,9 +116,7 @@ const finish = (state: State, context: MediaProtocol.ResponseContext<Request>) =
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, SpeechEvent, Uint8Array, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, SpeechEvent, Uint8Array, State>(route, {
   unsupported: ["voice", "language", "instructions", "timestamps"],
   body: { from: fromRequest },
   frames: (bytes) => bytes,
@@ -134,7 +127,7 @@ export const protocol = MediaProtocol.stream<Request, SpeechEvent, Uint8Array, S
 
 export const model = (input: MediaRoute.ModelInput) =>
   SpeechModel.fromRoute<DeepgramSpeechOptions, Uint8Array, State>(
-    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
     input,
   )
 

packages/ai/src/protocols/deepgram-transcription.ts

@@ -2,14 +2,12 @@ import { Effect, Schema } from "effect"
 import type { HttpClientResponse } from "effect/unstable/http"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { TranscriptionModel, TranscriptionResponse, type TranscriptionRequestFor } from "../transcription.js"
 import { ProviderShared } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "deepgram-transcription"
-const NAME = "Deepgram"
-const PROVIDER = ProviderID.make("deepgram")
+const route = MediaProtocol.identity({ id: "deepgram-transcription", name: "Deepgram", provider: "deepgram" })
 export const DEFAULT_BASE_URL = "https://api.deepgram.com"
 export const PATH = "/v1/listen"
 
@@ -24,7 +22,7 @@ export type DeepgramTranscriptionOptions = {
   readonly utterances?: boolean
   readonly detect_language?: boolean | ReadonlyArray<string>
   readonly keyterm?: ReadonlyArray<string>
-  readonly diarize_model?: "latest" | "v1" | "v2" | (string & {})
+  readonly diarize_model?: OpenString<"latest" | "v1" | "v2">
   readonly filler_words?: boolean
   readonly numerals?: boolean
   readonly mip_opt_out?: boolean
@@ -79,7 +77,7 @@ const ListenResponse = Schema.Struct({
 
 const query = (request: Request) =>
   MediaInput.query(
-    ADAPTER,
+    route.id,
     mergeJsonRecords(
       {
         model: request.model.id,
@@ -100,8 +98,10 @@ const fromRequest = Effect.fn("DeepgramTranscription.fromRequest")(function* (re
   if (url !== undefined)
     return MediaProtocol.json(mergeJsonRecords({ url }, request.http?.body) ?? {}, yield* query(request))
   if (request.http?.body !== undefined)
-    return yield* ProviderShared.invalidRequest(`${NAME} sends inline audio as the raw body, so http.body cannot apply`)
-  const audio = yield* MediaInput.inlineBytes(ADAPTER, request.audio)
+    return yield* ProviderShared.invalidRequest(
+      `${route.name} sends inline audio as the raw body, so http.body cannot apply`,
+    )
+  const audio = yield* MediaInput.inlineBytes(route.id, request.audio)
   return MediaProtocol.binary(audio, request.audio.mediaType, yield* query(request))
 })
 
@@ -109,7 +109,7 @@ const fromRequest = Effect.fn("DeepgramTranscription.fromRequest")(function* (re
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeListen = MediaProtocol.decodeJson(ADAPTER, NAME, ListenResponse)
+const decodeListen = route.decodeJson(ListenResponse)
 
 const speaker = (value: number | undefined) => (value === undefined ? undefined : String(value))
 
@@ -131,7 +131,7 @@ const decodeResponse = Effect.fn("DeepgramTranscription.decodeResponse")(functio
   const output = yield* decodeListen(response)
   const channel = output.value.results.channels[0]
   const alternative = channel?.alternatives?.[0]
-  if (alternative === undefined) return yield* output.invalid(`${NAME} returned no transcript`)
+  if (alternative === undefined) return yield* output.invalid(`${route.name} returned no transcript`)
   const duration = output.value.metadata?.duration
   const requestID = output.value.metadata?.request_id
   return new TranscriptionResponse({
@@ -171,19 +171,14 @@ const decodeResponse = Effect.fn("DeepgramTranscription.decodeResponse")(functio
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.inline<Request, TranscriptionResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.inline<Request, TranscriptionResponse>(route, {
   unsupported: ["prompt", "speakers"],
   body: { from: fromRequest },
   response: { decode: decodeResponse },
 })
 
 export const model = (input: MediaRoute.ModelInput) =>
-  TranscriptionModel.fromRoute<DeepgramTranscriptionOptions>(
-    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
-    input,
-  )
+  TranscriptionModel.fromRoute<DeepgramTranscriptionOptions>({ protocol, baseURL: DEFAULT_BASE_URL, path: PATH }, input)
 
 export const DeepgramTranscription = {
   protocol,

packages/ai/src/protocols/elevenlabs-speech.ts

@@ -2,14 +2,12 @@ import { Effect, Schema } from "effect"
 import { Framing } from "../route/framing.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { SpeechModel, type SpeechEvent, type SpeechRequestFor } from "../speech.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 import { SpeechStream } from "./utils/speech-stream.js"
 
-const ADAPTER = "elevenlabs-speech"
-const NAME = "ElevenLabs"
-const PROVIDER = ProviderID.make("elevenlabs")
+const route = MediaProtocol.identity({ id: "elevenlabs-speech", name: "ElevenLabs", provider: "elevenlabs" })
 export const DEFAULT_BASE_URL = "https://api.elevenlabs.io"
 export const PATH = "/v1/text-to-speech"
 
@@ -17,9 +15,7 @@ export const PATH = "/v1/text-to-speech"
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type ElevenLabsSpeechString<Known extends string> = Known | (string & {})
-
-export type ElevenLabsOutputFormat = ElevenLabsSpeechString<
+export type ElevenLabsOutputFormat = OpenString<
   | "mp3_22050_32"
   | "mp3_24000_48"
   | "mp3_44100_32"
@@ -59,7 +55,7 @@ export type ElevenLabsSpeechOptions = {
     readonly use_speaker_boost?: boolean
   }
   readonly seed?: number
-  readonly apply_text_normalization?: ElevenLabsSpeechString<"auto" | "on" | "off">
+  readonly apply_text_normalization?: OpenString<"auto" | "on" | "off">
 } & Record<string, unknown>
 
 export type Request = SpeechRequestFor<ElevenLabsSpeechOptions>
@@ -79,7 +75,7 @@ const TimestampedAudio = Schema.Struct({
   alignment: optionalNull(Alignment),
 })
 
-const decodeRecord = MediaProtocol.decodeFrame(ADAPTER, NAME, TimestampedAudio)
+const decodeRecord = route.decodeFrame(TimestampedAudio)
 
 // ---------------------------------------------------------------------------
 // 4. Parser state
@@ -102,23 +98,21 @@ const OUTPUT_FORMATS: Readonly<Record<string, string>> = {
 const outputFormat = Effect.fn("ElevenLabsSpeech.outputFormat")(function* (request: MediaProtocol.Addressed<Request>) {
   const format = request.providerOptions?.outputFormat ?? OUTPUT_FORMATS[request.format ?? "mp3"]
   if (format === undefined)
-    return yield* SpeechStream.unsupportedFormat(
-      PROVIDER,
-      ADAPTER,
-      `${NAME} has no default output format for "${request.format}"; pass providerOptions.outputFormat`,
+    return yield* route.unsupported(
+      "media.format",
+      `${route.name} has no default output format for "${request.format}"; pass providerOptions.outputFormat`,
     )
   if (request.mode === "stream" && format.startsWith("wav_"))
-    return yield* SpeechStream.unsupportedFormat(
-      PROVIDER,
-      ADAPTER,
-      `${NAME} streams mp3, pcm, opus, ulaw, and alaw but not "${format}"; use generate for WAV`,
+    return yield* route.unsupported(
+      "media.format",
+      `${route.name} streams mp3, pcm, opus, ulaw, and alaw but not "${format}"; use generate for WAV`,
     )
   return format
 })
 
 const fromRequest = Effect.fn("ElevenLabsSpeech.fromRequest")(function* (request: MediaProtocol.Addressed<Request>) {
   if (request.voice === undefined)
-    return yield* ProviderShared.invalidRequest(`${NAME} requires a voice id; pass it as \`voice\``)
+    return yield* ProviderShared.invalidRequest(`${route.name} requires a voice id; pass it as \`voice\``)
   const { outputFormat: _outputFormat, ...native } = request.providerOptions ?? {}
   return MediaProtocol.json(
     mergeJsonRecords(
@@ -180,7 +174,7 @@ const finish = Effect.fn("ElevenLabsSpeech.finish")(function* (
   context: MediaProtocol.ResponseContext<Request>,
 ) {
   const requestID = context.http.headers["request-id"]
-  return yield* SpeechStream.finish(ADAPTER, state, {
+  return yield* SpeechStream.finish(route, state, {
     ...describeOutput(yield* outputFormat(context.request)),
     // `character-cost` is billed credits, not a character count (3 for 20 characters on `eleven_flash_v2_5`).
     usage: SpeechStream.headerUsage("credits", context.http.headers["character-cost"]),
@@ -192,9 +186,7 @@ const finish = Effect.fn("ElevenLabsSpeech.finish")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint8Array, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint8Array, State>(route, {
   unsupported: ["instructions"],
   body: { from: fromRequest },
   frames: (bytes, context) => {
@@ -208,7 +200,7 @@ export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint
 
 export const model = (input: MediaRoute.ModelInput) =>
   SpeechModel.fromRoute<ElevenLabsSpeechOptions, string | Uint8Array, State>(
-    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: ({ request }) => path(request) },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: ({ request }) => path(request) },
     input,
   )
 

packages/ai/src/protocols/fal-images.ts

@@ -4,28 +4,21 @@ import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 import { FalQueue } from "./utils/fal-queue.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "fal-images"
-const NAME = "fal Images"
-const PROVIDER = ProviderID.make("fal")
+const route = MediaProtocol.identity({ id: "fal-images", name: "fal Images", provider: "fal" })
 
 // ---------------------------------------------------------------------------
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
 export type FalImageOptions = {
-  readonly image_size?:
-    | "square_hd"
-    | "square"
-    | "portrait_4_3"
-    | "portrait_16_9"
-    | "landscape_4_3"
-    | "landscape_16_9"
-    | (string & {})
+  readonly image_size?: OpenString<
+    "square_hd" | "square" | "portrait_4_3" | "portrait_16_9" | "landscape_4_3" | "landscape_16_9"
+  >
   readonly enable_safety_checker?: boolean
 } & Record<string, unknown>
 
@@ -61,25 +54,19 @@ const sizing = (model: string) => {
   return undefined
 }
 
-const unsupported = (model: string, field: string, message: string) =>
-  ProviderShared.unsupportedOperation({
-    operation: `media.${field}`,
-    provider: PROVIDER,
-    route: ADAPTER,
-    message: `${model} ${message}`,
-  })
-
 const validate = (request: Request) => {
   const id = request.model.id
   const field = sizing(id)
   if (request.size !== undefined && request.aspectRatio !== undefined)
-    return Effect.fail(ProviderShared.invalidRequest(`${NAME} accepts either size or aspectRatio, not both`))
+    return Effect.fail(ProviderShared.invalidRequest(`${route.name} accepts either size or aspectRatio, not both`))
   if (request.size !== undefined && field === "aspect_ratio")
-    return Effect.fail(unsupported(id, "size", "sizes by aspectRatio"))
+    return Effect.fail(route.unsupported("media.size", `${id} sizes by aspectRatio`))
   if (request.aspectRatio !== undefined && field === "image_size")
-    return Effect.fail(unsupported(id, "aspectRatio", "sizes by size (image_size)"))
+    return Effect.fail(route.unsupported("media.aspectRatio", `${id} sizes by size (image_size)`))
   if ((request.images?.length ?? 0) > 1 && !isEdit(id))
-    return Effect.fail(unsupported(id, "images", "takes one image_url; use an /edit endpoint for several images"))
+    return Effect.fail(
+      route.unsupported("media.images", `${id} takes one image_url; use an /edit endpoint for several images`),
+    )
   return Effect.void
 }
 
@@ -88,7 +75,7 @@ const isEdit = (model: string) => model.endsWith("/edit")
 
 const fromRequest = Effect.fn("FalImages.fromRequest")(function* (request: Request) {
   yield* validate(request)
-  const images = yield* Effect.forEach(request.images ?? [], (image) => FalQueue.mediaUrl(image, NAME))
+  const images = yield* Effect.forEach(request.images ?? [], (image) => FalQueue.mediaUrl(image, route.name))
   const edit = isEdit(request.model.id)
   return MediaProtocol.json(
     mergeJsonRecords(
@@ -101,7 +88,7 @@ const fromRequest = Effect.fn("FalImages.fromRequest")(function* (request: Reque
         output_format: request.format,
         image_urls: edit && images.length > 0 ? images : undefined,
         image_url: edit ? undefined : images[0],
-        mask_url: request.mask === undefined ? undefined : yield* FalQueue.mediaUrl(request.mask, NAME),
+        mask_url: request.mask === undefined ? undefined : yield* FalQueue.mediaUrl(request.mask, route.name),
       },
       request.providerOptions,
       request.http?.body,
@@ -113,7 +100,7 @@ const fromRequest = Effect.fn("FalImages.fromRequest")(function* (request: Reque
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeQueueResult = MediaProtocol.decodeJson(ADAPTER, NAME, QueueResult)
+const decodeQueueResult = route.decodeJson(QueueResult)
 
 const decodeResult = Effect.fn("FalImages.decodeResult")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -121,7 +108,7 @@ const decodeResult = Effect.fn("FalImages.decodeResult")(function* (
 ) {
   const output = yield* decodeQueueResult(response)
   const { images, seed, has_nsfw_concepts, ...rest } = output.value
-  if (images.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  if (images.length === 0) return yield* output.invalid(`${route.name} returned no images`)
   // With the safety checker on, flagged images come back blacked out rather than omitted.
   const flagged = (has_nsfw_concepts ?? []).flatMap((value, index) => (value ? [index] : []))
   return new ImageResponse({
@@ -134,7 +121,10 @@ const decodeResult = Effect.fn("FalImages.decodeResult")(function* (
     notices:
       flagged.length === 0
         ? undefined
-        : flagged.map((index) => ({ type: "moderated" as const, message: `${NAME} flagged image ${index} as NSFW` })),
+        : flagged.map((index) => ({
+            type: "moderated" as const,
+            message: `${route.name} flagged image ${index} as NSFW`,
+          })),
     providerMetadata: { fal: { requestId: context.token.requestID, seed: seed ?? undefined, ...rest } },
   })
 })
@@ -143,22 +133,14 @@ const decodeResult = Effect.fn("FalImages.decodeResult")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = FalQueue.protocol<Request, ImageResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = FalQueue.protocol<Request, ImageResponse>(route, {
   from: fromRequest,
   decodeResult,
 })
 
 export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<FalImageOptions, FalQueue.Token>(
-    {
-      id: ADAPTER,
-      provider: PROVIDER,
-      protocol,
-      baseURL: FalQueue.DEFAULT_BASE_URL,
-      path: ({ request }) => `/${request.model.id}`,
-    },
+    { protocol, baseURL: FalQueue.DEFAULT_BASE_URL, path: ({ request }) => `/${request.model.id}` },
     input,
   )
 

packages/ai/src/protocols/fal-video.ts

@@ -3,28 +3,24 @@ import type { HttpClientResponse } from "effect/unstable/http"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { VideoModel, VideoResponse, type VideoRequestFor } from "../video.js"
-import { ProviderShared, optionalNull } from "./shared.js"
+import { optionalNull } from "./shared.js"
 import { FalQueue } from "./utils/fal-queue.js"
 
-const ADAPTER = "fal-video"
-const NAME = "fal Video"
-const PROVIDER = ProviderID.make("fal")
+const route = MediaProtocol.identity({ id: "fal-video", name: "fal Video", provider: "fal" })
 
 // ---------------------------------------------------------------------------
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type FalVideoString<Known extends string> = Known | (string & {})
-
 /**
  * Provider-native input. fal video endpoints are model-specific: `duration` is a string enum whose values differ per
  * model (`"8s"` for Veo, `"5"` for Kling), and last-frame fields are named per model (`end_image_url`,
  * `last_frame_url`, `tail_image_url`), so those pass through here instead of lowering from common fields.
  */
 export type FalVideoOptions = {
-  readonly duration?: FalVideoString<"4s" | "6s" | "8s" | "5" | "10">
+  readonly duration?: OpenString<"4s" | "6s" | "8s" | "5" | "10">
 } & Record<string, unknown>
 
 export type Request = VideoRequestFor<FalVideoOptions>
@@ -52,15 +48,13 @@ const QueueResult = Schema.StructWithRest(
 
 const fromRequest = Effect.fn("FalVideo.fromRequest")(function* (request: Request) {
   if (request.frames?.last !== undefined)
-    return yield* ProviderShared.unsupportedOperation({
-      operation: "video.frames.last",
-      provider: PROVIDER,
-      route: ADAPTER,
-      message: `${NAME} names the last frame per model; pass it through providerOptions (e.g. end_image_url) instead of frames.last`,
-    })
+    return yield* route.unsupported(
+      "video.frames.last",
+      `${route.name} names the last frame per model; pass it through providerOptions (e.g. end_image_url) instead of frames.last`,
+    )
   const imageUrl =
-    request.frames?.first === undefined ? undefined : yield* FalQueue.mediaUrl(request.frames.first, NAME)
-  const videoUrl = request.video === undefined ? undefined : yield* FalQueue.mediaUrl(request.video, NAME)
+    request.frames?.first === undefined ? undefined : yield* FalQueue.mediaUrl(request.frames.first, route.name)
+  const videoUrl = request.video === undefined ? undefined : yield* FalQueue.mediaUrl(request.video, route.name)
   return MediaProtocol.json(
     mergeJsonRecords(
       {
@@ -83,7 +77,7 @@ const fromRequest = Effect.fn("FalVideo.fromRequest")(function* (request: Reques
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeQueueResult = MediaProtocol.decodeJson(ADAPTER, NAME, QueueResult)
+const decodeQueueResult = route.decodeJson(QueueResult)
 
 const decodeResult = Effect.fn("FalVideo.decodeResult")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -109,9 +103,7 @@ const decodeResult = Effect.fn("FalVideo.decodeResult")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = FalQueue.protocol<Request, VideoResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = FalQueue.protocol<Request, VideoResponse>(route, {
   unsupported: ["n", "durationSeconds", "references"],
   from: fromRequest,
   decodeResult,
@@ -119,13 +111,7 @@ export const protocol = FalQueue.protocol<Request, VideoResponse>({
 
 export const model = (input: MediaRoute.ModelInput) =>
   VideoModel.fromRoute<FalVideoOptions, FalQueue.Token>(
-    {
-      id: ADAPTER,
-      provider: PROVIDER,
-      protocol,
-      baseURL: FalQueue.DEFAULT_BASE_URL,
-      path: ({ request }) => `/${request.model.id}`,
-    },
+    { protocol, baseURL: FalQueue.DEFAULT_BASE_URL, path: ({ request }) => `/${request.model.id}` },
     input,
   )
 

packages/ai/src/protocols/gemini.ts

@@ -11,7 +11,6 @@ import {
   Usage,
   type FinishReason,
   type LLMRequest,
-  type LanguageModel,
   type MediaPart,
   type ProviderMetadata,
   type ProviderOptions,
@@ -24,11 +23,12 @@ import { Media } from "../media.js"
 import { JsonObject, knownString, lenient, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { GeminiGenerateContent } from "./utils/gemini-generate-content.js"
 import { Lifecycle } from "./utils/lifecycle.js"
-import { ToolSchemaProjection } from "./utils/tool-schema.js"
 
 const ADAPTER = "gemini"
 // Google documents this sentinel for replaying Gemini 3 function calls after their original signature was lost.
 const SKIP_THOUGHT_SIGNATURE_VALIDATOR = "skip_thought_signature_validator"
+// Gemini 2.5 rejects a budget under the model's minimum: 512 on Flash-Lite, the highest, and 128 on Pro.
+const MIN_THINKING_BUDGET = 512
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
 
 // Gemini 3 rejects replayed function calls without a thought signature. Google's SDKs avoid that in normal chats by
@@ -268,12 +268,11 @@ interface ParserState {
 // =============================================================================
 // Request Lowering
 // =============================================================================
-// Tool schemas go in `parametersJsonSchema`, which accepts standard JSON Schema. Gemini's schema
-// rules are this API's default, including for tuned endpoints whose IDs do not name Gemini.
-const lowerTool = (tool: ToolDefinition, model: LanguageModel) => ({
+// Tool schemas go in `parametersJsonSchema`, which accepts standard JSON Schema.
+const lowerTool = (tool: ToolDefinition) => ({
   name: tool.name,
   description: tool.description,
-  parametersJsonSchema: ToolSchemaProjection.modelCompatibility(tool.inputSchema, model, "gemini"),
+  parametersJsonSchema: tool.inputSchema,
 })
 
 const lowerToolConfig = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
@@ -452,10 +451,22 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
     presencePenalty: generation?.presencePenalty,
     seed: generation?.seed,
     stopSequences: generation?.stop,
+    // Gemini accepts a budget above `maxOutputTokens`, but thinking then leaves the answer empty.
     thinkingConfig:
       options.thinkingConfig === undefined
         ? undefined
-        : { ...options.thinkingConfig, includeThoughts: options.thinkingConfig.includeThoughts ?? true },
+        : {
+            ...options.thinkingConfig,
+            includeThoughts: options.thinkingConfig.includeThoughts ?? true,
+            thinkingBudget:
+              options.thinkingConfig.thinkingBudget === undefined
+                ? undefined
+                : ProviderShared.fitThinkingBudget(
+                    options.thinkingConfig.thinkingBudget,
+                    generation?.maxTokens,
+                    MIN_THINKING_BUDGET,
+                  ),
+          },
   }
 
   return {
@@ -468,7 +479,7 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
     tools: hasTools
       ? [
           {
-            functionDeclarations: flattened.tools.map((tool) => lowerTool(tool, request.model)),
+            functionDeclarations: flattened.tools.map(lowerTool),
           },
         ]
       : undefined,
@@ -804,6 +815,8 @@ export const protocol = Protocol.make({
     schema: GeminiBody,
     from: fromRequest,
   },
+  // Gemini's schema rules are this API's default, including for tuned endpoints whose IDs do not name Gemini.
+  sanitizer: "gemini",
   stream: {
     event: Protocol.jsonEvent(GeminiEvent),
     initial: (request) => ({

packages/ai/src/protocols/google-images.ts

@@ -3,26 +3,22 @@ import type { HttpClientResponse } from "effect/unstable/http"
 import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { ProviderShared } from "./shared.js"
 import { GeminiGenerateContent } from "./utils/gemini-generate-content.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "google-images"
-const NAME = "Google Images"
-const PROVIDER = ProviderID.make("google")
+const route = MediaProtocol.identity({ id: "google-images", name: "Google Images", provider: "google" })
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
 
 // ---------------------------------------------------------------------------
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type GoogleImageString<Known extends string> = Known | (string & {})
-
 /** Provider-native options. Common fields (`aspectRatio`, `seed`, `images`) live on the request. */
 export type GoogleImageOptions = {
-  readonly imageSize?: GoogleImageString<"1K" | "2K" | "4K">
-  readonly thinkingLevel?: GoogleImageString<"MINIMAL" | "LOW" | "MEDIUM" | "HIGH">
+  readonly imageSize?: OpenString<"1K" | "2K" | "4K">
+  readonly thinkingLevel?: OpenString<"MINIMAL" | "LOW" | "MEDIUM" | "HIGH">
   readonly includeThoughts?: boolean
 } & Record<string, unknown>
 
@@ -104,13 +100,13 @@ const generationConfig = (request: Request) => {
 
 const fromRequest = Effect.fn("GoogleImages.fromRequest")(function* (request: Request) {
   if (request.n !== undefined && request.n > 1)
-    return yield* ProviderShared.unsupportedOperation({
-      operation: "image.n",
-      provider: PROVIDER,
-      route: ADAPTER,
-      message: `${NAME} generates one image per request; call it once per image instead of n=${request.n}`,
-    })
-  const parts = yield* Effect.forEach(request.images ?? [], (image) => GeminiGenerateContent.mediaPart(NAME, image))
+    return yield* route.unsupported(
+      "image.n",
+      `${route.name} generates one image per request; call it once per image instead of n=${request.n}`,
+    )
+  const parts = yield* Effect.forEach(request.images ?? [], (image) =>
+    GeminiGenerateContent.mediaPart(route.name, image),
+  )
   return MediaProtocol.json(
     mergeJsonRecords(
       {
@@ -126,10 +122,12 @@ const fromRequest = Effect.fn("GoogleImages.fromRequest")(function* (request: Re
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
+const decodeDocument = route.decodeJson(GoogleImageResponse)
+
 const decodeResponse = Effect.fn("GoogleImages.decodeResponse")(function* (
   response: HttpClientResponse.HttpClientResponse,
 ) {
-  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, GoogleImageResponse)(response)
+  const output = yield* decodeDocument(response)
   const decoded = output.value
   const candidates = decoded.candidates ?? []
   const candidateMetadata = candidates.map((candidate, candidateIndex) => ({
@@ -169,7 +167,7 @@ const decodeResponse = Effect.fn("GoogleImages.decodeResponse")(function* (
   const images = yield* Effect.forEach(encoded, (item) =>
     MediaInput.decodedAsset(
       output.invalid,
-      `${NAME} candidate ${item.candidateIndex} part ${item.partIndex}`,
+      `${route.name} candidate ${item.candidateIndex} part ${item.partIndex}`,
       item.inlineData.data,
       item.inlineData.mimeType,
       {
@@ -192,7 +190,7 @@ const decodeResponse = Effect.fn("GoogleImages.decodeResponse")(function* (
       candidate.finishReason === undefined ? [] : [candidate.finishReason],
     )
     return yield* output.invalid(
-      `${NAME} returned no final images${
+      `${route.name} returned no final images${
         finishReasons.length === 0 ? "" : ` (finish reasons: ${finishReasons.join(", ")})`
       }; inspect body for prompt feedback and candidate details`,
     )
@@ -204,7 +202,7 @@ const decodeResponse = Effect.fn("GoogleImages.decodeResponse")(function* (
       : [
           {
             type: "filtered" as const,
-            message: `${NAME} reported prompt feedback`,
+            message: `${route.name} reported prompt feedback`,
             providerMetadata: { google: { promptFeedback: decoded.promptFeedback } },
           },
         ]),
@@ -214,7 +212,7 @@ const decodeResponse = Effect.fn("GoogleImages.decodeResponse")(function* (
         : [
             {
               type: "filtered" as const,
-              message: `${NAME} candidate ${candidate.index ?? index} finished with ${candidate.finishReason}${
+              message: `${route.name} candidate ${candidate.index ?? index} finished with ${candidate.finishReason}${
                 candidate.finishMessage === undefined ? "" : `: ${candidate.finishMessage}`
               }`,
               providerMetadata: {
@@ -264,9 +262,7 @@ const decodeResponse = Effect.fn("GoogleImages.decodeResponse")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.inline<Request, ImageResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.inline<Request, ImageResponse>(route, {
   unsupported: ["mask", "size", "format"],
   body: { from: fromRequest },
   response: { decode: decodeResponse },
@@ -275,8 +271,6 @@ export const protocol = MediaProtocol.inline<Request, ImageResponse>({
 export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<GoogleImageOptions>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       path: ({ request }) => `/models/${request.model.id}:generateContent`,

packages/ai/src/protocols/google-speech.ts

@@ -1,14 +1,12 @@
 import { Effect, Schema } from "effect"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords } from "../schema/index.js"
 import { SpeechModel, type SpeechEvent, type SpeechRequestFor } from "../speech.js"
 import { GeminiGenerateContent } from "./utils/gemini-generate-content.js"
 import { SpeechStream } from "./utils/speech-stream.js"
 
-const ADAPTER = "google-speech"
-const NAME = "Google Speech"
-const PROVIDER = ProviderID.make("google")
+const route = MediaProtocol.identity({ id: "google-speech", name: "Google Speech", provider: "google" })
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
 const DEFAULT_SAMPLE_RATE = 24000
 
@@ -43,7 +41,7 @@ const GenerateContentChunk = GeminiGenerateContent.chunk(
   }),
 )
 
-const decodeChunk = MediaProtocol.decodeFrame(ADAPTER, NAME, GenerateContentChunk)
+const decodeChunk = route.decodeFrame(GenerateContentChunk)
 
 // ---------------------------------------------------------------------------
 // 4. Parser state
@@ -59,10 +57,9 @@ interface State extends SpeechStream.Audio, GeminiGenerateContent.Metadata {
 
 const fromRequest = Effect.fn("GoogleSpeech.fromRequest")(function* (request: MediaProtocol.Addressed<Request>) {
   if (request.format !== undefined && request.format !== "pcm")
-    return yield* SpeechStream.unsupportedFormat(
-      PROVIDER,
-      ADAPTER,
-      `${NAME} only returns raw PCM; request format "pcm" or omit it, then wrap the samples yourself`,
+    return yield* route.unsupported(
+      "media.format",
+      `${route.name} only returns raw PCM; request format "pcm" or omit it, then wrap the samples yourself`,
     )
   const voiceName = SpeechStream.voiceID(request.voice)
   return MediaProtocol.json(
@@ -91,7 +88,7 @@ const fromRequest = Effect.fn("GoogleSpeech.fromRequest")(function* (request: Me
 
 const step = Effect.fn("GoogleSpeech.step")(function* (state: State, frame: string) {
   const chunk = yield* decodeChunk(frame)
-  const blocked = GeminiGenerateContent.blocked(NAME, chunk, frame)
+  const blocked = GeminiGenerateContent.blocked(route.name, chunk, frame)
   if (blocked !== undefined) return yield* blocked
   const audio = (chunk.candidates?.[0]?.content?.parts ?? []).flatMap((part) =>
     part.inlineData === undefined ? [] : [part.inlineData],
@@ -102,7 +99,7 @@ const step = Effect.fn("GoogleSpeech.step")(function* (state: State, frame: stri
 
 const finish = (state: State) => {
   const sampleRate = SpeechStream.sampleRate(state.mimeType) ?? DEFAULT_SAMPLE_RATE
-  return SpeechStream.finish(ADAPTER, state, {
+  return SpeechStream.finish(route, state, {
     ...SpeechStream.pcm("pcm_s16le", sampleRate, state.mimeType ?? `audio/L16;codec=pcm;rate=${sampleRate}`),
     usage: GeminiGenerateContent.usage(state.usage),
     providerMetadata: GeminiGenerateContent.providerMetadata(state),
@@ -114,9 +111,7 @@ const finish = (state: State) => {
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, SpeechEvent, string, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, SpeechEvent, string, State>(route, {
   unsupported: ["instructions", "speed", "timestamps"],
   body: { from: fromRequest },
   frames: (bytes, context) => GeminiGenerateContent.frames(bytes, context.request.mode),
@@ -128,8 +123,6 @@ export const protocol = MediaProtocol.stream<Request, SpeechEvent, string, State
 export const model = (input: MediaRoute.ModelInput) =>
   SpeechModel.fromRoute<GoogleSpeechOptions, string, State>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       // Only `gemini-3.1-flash-tts-preview` and later stream; earlier TTS models reject `streamGenerateContent`.

packages/ai/src/protocols/google-transcription.ts

@@ -1,7 +1,7 @@
 import { Effect, Schema, SchemaGetter } from "effect"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import {
   TranscriptionFinishEvent,
   TranscriptionModel,
@@ -12,12 +12,9 @@ import {
   type TranscriptionWord,
   type TranscriptionEvent,
 } from "../transcription.js"
-import { ProviderShared } from "./shared.js"
 import { GeminiGenerateContent } from "./utils/gemini-generate-content.js"
 
-const ADAPTER = "google-transcription"
-const NAME = "Google Transcription"
-const PROVIDER = ProviderID.make("google")
+const route = MediaProtocol.identity({ id: "google-transcription", name: "Google Transcription", provider: "google" })
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
 
 // ---------------------------------------------------------------------------
@@ -30,7 +27,7 @@ export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1bet
  */
 export type GoogleTranscriptionOptions = {
   readonly audioTranscriptionConfig?: {
-    readonly mode?: "VERBATIM" | "SMART" | (string & {})
+    readonly mode?: OpenString<"VERBATIM" | "SMART">
     readonly customVocabulary?: ReadonlyArray<string>
     readonly languageCodes?: ReadonlyArray<string>
   }
@@ -64,9 +61,7 @@ const AudioTranscription = Schema.Struct({
   ),
 })
 
-const decodeChunk = MediaProtocol.decodeFrame(
-  ADAPTER,
-  NAME,
+const decodeChunk = route.decodeFrame(
   GeminiGenerateContent.chunk(Schema.Struct({ audioTranscription: Schema.optional(AudioTranscription) })),
 )
 
@@ -87,16 +82,14 @@ interface State extends GeminiGenerateContent.Metadata {
 const fromRequest = Effect.fn("GoogleTranscription.fromRequest")(function* (request: MediaProtocol.Addressed<Request>) {
   // General Gemini models ignore `audioTranscriptionConfig` and answer the audio conversationally.
   if (!request.model.id.includes("transcribe"))
-    return yield* ProviderShared.unsupportedOperation({
-      operation: "transcription.model",
-      provider: PROVIDER,
-      route: ADAPTER,
-      message: `${request.model.id} is not a transcription model; use a transcribe model such as gemini-3.5-transcribe`,
-    })
+    return yield* route.unsupported(
+      "transcription.model",
+      `${request.model.id} is not a transcription model; use a transcribe model such as gemini-3.5-transcribe`,
+    )
   return MediaProtocol.json(
     mergeJsonRecords(
       {
-        contents: [{ role: "user", parts: [yield* GeminiGenerateContent.mediaPart(ADAPTER, request.audio)] }],
+        contents: [{ role: "user", parts: [yield* GeminiGenerateContent.mediaPart(route.id, request.audio)] }],
         generationConfig: mergeJsonRecords(
           {
             audioTranscriptionConfig: {
@@ -147,7 +140,7 @@ const turn = (part: Schema.Schema.Type<typeof AudioTranscription>) => {
 
 const step = Effect.fn("GoogleTranscription.step")(function* (state: State, frame: string) {
   const chunk = yield* decodeChunk(frame)
-  const blocked = GeminiGenerateContent.blocked(NAME, chunk, frame)
+  const blocked = GeminiGenerateContent.blocked(route.name, chunk, frame)
   if (blocked !== undefined) return yield* blocked
   const turns = (chunk.candidates?.[0]?.content?.parts ?? []).flatMap((part) =>
     part.audioTranscription === undefined ? [] : [turn(part.audioTranscription)],
@@ -169,7 +162,7 @@ const step = Effect.fn("GoogleTranscription.step")(function* (state: State, fram
 })
 
 const finish = (state: State) => {
-  if (state.finishReason === undefined) return Effect.fail(MediaProtocol.incomplete(ADAPTER))
+  if (state.finishReason === undefined) return Effect.fail(route.incomplete())
   return Effect.succeed([
     TranscriptionFinishEvent.make({
       text: state.text,
@@ -185,9 +178,7 @@ const finish = (state: State) => {
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, TranscriptionEvent, string, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, TranscriptionEvent, string, State>(route, {
   unsupported: ["prompt", "speakers"],
   body: { from: fromRequest },
   frames: (bytes, context) => GeminiGenerateContent.frames(bytes, context.request.mode),
@@ -199,8 +190,6 @@ export const protocol = MediaProtocol.stream<Request, TranscriptionEvent, string
 export const model = (input: MediaRoute.ModelInput) =>
   TranscriptionModel.fromRoute<GoogleTranscriptionOptions, string, State>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       path: ({ request }) => GeminiGenerateContent.path(request.model.id, request.mode),

packages/ai/src/protocols/google-video.ts

@@ -4,13 +4,11 @@ import type { Status } from "../generation.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { VideoModel, VideoResponse, type VideoRequestFor } from "../video.js"
 import { ProviderShared, optionalArray } from "./shared.js"
 
-const ADAPTER = "google-video"
-const NAME = "Google Veo"
-const PROVIDER = ProviderID.make("google")
+const route = MediaProtocol.identity({ id: "google-video", name: "Google Veo", provider: "google" })
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
 /** Veo keeps generated files for two days; the asset carries that deadline so callers materialize in time. */
 const FILE_RETENTION = Duration.days(2)
@@ -19,11 +17,9 @@ const FILE_RETENTION = Duration.days(2)
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type GoogleVideoString<Known extends string> = Known | (string & {})
-
 /** Provider-native `parameters`. Common fields (`aspectRatio`, `resolution`, `durationSeconds`, `seed`) live on the request. */
 export type GoogleVideoOptions = {
-  readonly personGeneration?: GoogleVideoString<"allow_all" | "allow_adult" | "dont_allow">
+  readonly personGeneration?: OpenString<"allow_all" | "allow_adult" | "dont_allow">
 } & Record<string, unknown>
 
 export type Request = VideoRequestFor<GoogleVideoOptions>
@@ -70,27 +66,23 @@ const Operation = Schema.Struct({
 
 // Veo takes inline media only; a prior Veo output is `Media.url` with transient auth, so materialize it first.
 const inlineMedia = (asset: Media.Asset) =>
-  ProviderShared.requireInlineMedia(NAME, asset).pipe(
+  ProviderShared.requireInlineMedia(route.name, asset).pipe(
     Effect.map((inline) => ({ inlineData: { mimeType: inline.mime, data: inline.base64 } })),
   )
 
 const fromRequest = Effect.fn("GoogleVideo.fromRequest")(function* (request: Request) {
   if (request.n !== undefined && request.n > 1)
-    return yield* ProviderShared.unsupportedOperation({
-      operation: "video.n",
-      provider: PROVIDER,
-      route: ADAPTER,
-      message: `${NAME} generates one video per request; call it once per video instead of n=${request.n}`,
-    })
+    return yield* route.unsupported(
+      "video.n",
+      `${route.name} generates one video per request; call it once per video instead of n=${request.n}`,
+    )
   if (request.audio === false)
-    return yield* ProviderShared.unsupportedOperation({
-      operation: "video.audio",
-      provider: PROVIDER,
-      route: ADAPTER,
-      message: `${NAME} always generates audio; audio: false cannot be honored`,
-    })
+    return yield* route.unsupported(
+      "video.audio",
+      `${route.name} always generates audio; audio: false cannot be honored`,
+    )
   if (request.frames?.last !== undefined && request.frames.first === undefined)
-    return yield* ProviderShared.invalidRequest(`${NAME} requires frames.first when frames.last is set`)
+    return yield* ProviderShared.invalidRequest(`${route.name} requires frames.first when frames.last is set`)
   const image = request.frames?.first === undefined ? undefined : yield* inlineMedia(request.frames.first)
   const lastFrame = request.frames?.last === undefined ? undefined : yield* inlineMedia(request.frames.last)
   const video = request.video === undefined ? undefined : yield* inlineMedia(request.video)
@@ -129,7 +121,7 @@ const fromRequest = Effect.fn("GoogleVideo.fromRequest")(function* (request: Req
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeStart = MediaProtocol.decodeStarted(ADAPTER, NAME, StartResponse, (value) => ({
+const decodeStart = route.decodeStarted(StartResponse, (value) => ({
   token: { operation: value.name },
   snapshot: { id: value.name, status: "running" },
 }))
@@ -140,7 +132,7 @@ const statusOf = (operation: typeof Operation.Type): Status => {
   return operation.error === undefined ? "completed" : "failed"
 }
 
-const decodeOperation = MediaProtocol.decodeJson(ADAPTER, NAME, Operation)
+const decodeOperation = route.decodeJson(Operation)
 
 const decodeStatus = Effect.fn("GoogleVideo.decodeStatus")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -158,11 +150,11 @@ const decodeResult = Effect.fn("GoogleVideo.decodeResult")(function* (
   const operation = output.value
   const status = statusOf(operation)
   if (status === "running")
-    return yield* output.invalid(`${NAME} operation ${context.token.operation} has not finished`)
+    return yield* output.invalid(`${route.name} operation ${context.token.operation} has not finished`)
   if (status === "failed")
     return yield* output.ended(
       "failed",
-      `${NAME} operation failed${operation.error?.message === undefined ? "" : `: ${operation.error.message}`}`,
+      `${route.name} operation failed${operation.error?.message === undefined ? "" : `: ${operation.error.message}`}`,
     )
   const generated = operation.response?.generateVideoResponse
   // Downloads require the same API key as the poll; the asset carries it transiently and follows the redirect.
@@ -179,14 +171,14 @@ const decodeResult = Effect.fn("GoogleVideo.decodeResult")(function* (
   const reasons = generated?.raiMediaFilteredReasons ?? []
   const notices = reasons.map((reason) => ({
     type: "filtered" as const,
-    message: `${NAME} filtered media: ${reason}`,
+    message: `${route.name} filtered media: ${reason}`,
     providerMetadata: { google: { raiMediaFilteredReason: reason } },
   }))
   if (videos.length === 0 && (reasons.length > 0 || (generated?.raiMediaFilteredCount ?? 0) > 0))
     return yield* output.contentPolicy(
-      `${NAME} filtered every video${reasons.length === 0 ? "" : `: ${reasons.join("; ")}`}`,
+      `${route.name} filtered every video${reasons.length === 0 ? "" : `: ${reasons.join("; ")}`}`,
     )
-  if (videos.length === 0) return yield* output.invalid(`${NAME} operation completed without any video`)
+  if (videos.length === 0) return yield* output.invalid(`${route.name} operation completed without any video`)
   return new VideoResponse({
     videos,
     notices: notices.length === 0 ? undefined : notices,
@@ -206,9 +198,7 @@ const decodeResult = Effect.fn("GoogleVideo.decodeResult")(function* (
 
 const operationPath = (token: Token) => `/${token.operation}`
 
-export const protocol = MediaProtocol.queued<Request, VideoResponse, Token>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.queued<Request, VideoResponse, Token>(route, {
   token: Token,
   start: { body: { from: fromRequest }, decode: decodeStart },
   status: { path: operationPath, decode: decodeStatus },
@@ -218,8 +208,6 @@ export const protocol = MediaProtocol.queued<Request, VideoResponse, Token>({
 export const model = (input: MediaRoute.ModelInput) =>
   VideoModel.fromRoute<GoogleVideoOptions, Token>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       path: ({ request }) => `/models/${request.model.id}:predictLongRunning`,

packages/ai/src/protocols/meta-images.ts

@@ -4,20 +4,17 @@ import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { JsonObject, ProviderShared, optionalNull } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "meta-images"
-const NAME = "Meta Images"
-const PROVIDER = ProviderID.make("meta")
+const route = MediaProtocol.identity({ id: "meta-images", name: "Meta Images", provider: "meta" })
+export const DEFAULT_BASE_URL = "https://api.meta.ai/v1"
 
 // ---------------------------------------------------------------------------
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-type OpenString<Known extends string> = Known | (string & {})
-
 /** Provider-native options. Common fields (`n`, `size`, `format`, `images`) live on the request. */
 export type ImageOptions = {
   readonly responseFormat?: OpenString<"b64_json" | "url">
@@ -72,7 +69,7 @@ const isEdit = (request: Request) => (request.images?.length ?? 0) > 0
 
 // Meta has no file handles: refs are rejected even when they name this provider.
 const reference = (asset: Media.Asset) =>
-  ProviderShared.mediaReference(asset, undefined, NAME).pipe(Effect.map((item) => ({ image_url: item.value })))
+  ProviderShared.mediaReference(asset, undefined, route.name).pipe(Effect.map((item) => ({ image_url: item.value })))
 
 const fromRequest = Effect.fn("MetaImages.fromRequest")(function* (request: Request) {
   const images = yield* Effect.forEach(request.images ?? [], reference)
@@ -101,24 +98,23 @@ const fromRequest = Effect.fn("MetaImages.fromRequest")(function* (request: Requ
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
+const decodeDocument = route.decodeJson(Response)
+
 const decodeResponse = Effect.fn("MetaImages.decodeResponse")(function* (
   response: HttpClientResponse.HttpClientResponse,
   context: MediaProtocol.DecodeContext<Request>,
 ) {
-  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, Response)(response)
+  const output = yield* decodeDocument(response)
   const decoded = output.value
   const requested = context.body.type === "json" ? context.body.value.output_format : undefined
   const format = decoded.output_format ?? (typeof requested === "string" ? requested : "webp")
   const mediaType = `image/${format}`
-  const images = yield* Effect.forEach(decoded.data, (item, index) => {
-    if (item.b64_json)
-      return MediaInput.decodedAsset(output.invalid, `${NAME} result ${index}`, item.b64_json, mediaType, {
-        info: { format },
-      })
-    if (item.url) return Effect.succeed(Media.url(item.url, { mediaType, info: { format } }))
-    return Effect.fail(output.invalid(`${NAME} result ${index} has neither image data nor a URL`))
-  })
-  if (images.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  const images = yield* Effect.forEach(decoded.data, (item, index) =>
+    MediaInput.imageOutput(output.invalid, `${route.name} result ${index}`, item, mediaType, {
+      info: { format },
+    }),
+  )
+  if (images.length === 0) return yield* output.invalid(`${route.name} returned no images`)
   return new ImageResponse({
     images,
     usage:
@@ -139,20 +135,17 @@ const decodeResponse = Effect.fn("MetaImages.decodeResponse")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.inline<Request, ImageResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.inline<Request, ImageResponse>(route, {
   unsupported: ["mask", "aspectRatio", "seed"],
   body: { from: fromRequest },
   response: { decode: decodeResponse },
 })
 
-export const model = (input: MediaRoute.ModelInput & { readonly baseURL: string }) =>
+export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<ImageOptions>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
+      baseURL: DEFAULT_BASE_URL,
       path: ({ request }) => `/images/${isEdit(request) ? "edits" : "generations"}`,
     },
     input,

packages/ai/src/protocols/meta-responses.ts

@@ -5,8 +5,7 @@ import { LLMEvent, LLMRequest, Message, ToolResultPart } from "../schema/index.j
 import { OpenResponses } from "./open-responses.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
-import { ToolSchemaProjection } from "./utils/tool-schema.js"
-import { MetaImage } from "./utils/meta-image.js"
+import { detectMediaType } from "../utils/media-type.js"
 
 const ADAPTER = "meta-responses"
 const NAME = "Meta Responses"
@@ -103,12 +102,7 @@ const fromRequest = Effect.fn("MetaResponses.fromRequest")(function* (request: L
         ? undefined
         : yield* Effect.forEach(projected.tools, (tool) =>
             Effect.gen(function* () {
-              if (tool.native === undefined)
-                return yield* OpenResponses.lowerTool(
-                  NAME,
-                  tool,
-                  ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model),
-                )
+              if (tool.native === undefined) return yield* OpenResponses.lowerTool(NAME, tool)
               return yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(NativeTool))(tool.native.meta)
             }),
           ),
@@ -151,7 +145,11 @@ const HOSTED_TOOLS = {
           ),
         ),
       )
-      const mime = MetaImage.mediaType(data, item.output_format)
+      // Responses image items can omit output_format, including when PNG/JPEG was requested.
+      const mime =
+        item.output_format === undefined
+          ? (detectMediaType(data) ?? "application/octet-stream")
+          : `image/${item.output_format}`
       return {
         type: "content" as const,
         value: [{ type: "file" as const, uri: `data:${mime};base64,${item.result}`, mime }],

packages/ai/src/protocols/open-responses.ts

@@ -8,7 +8,6 @@ import {
   ProviderInternalError,
   Usage,
   type FinishReason,
-  type JsonSchema,
   type LLMRequest,
   type MediaPart,
   type ProviderMetadata,
@@ -24,7 +23,6 @@ import { classifyProviderFailure } from "../provider-error.js"
 import { effortUpdate } from "../effort-updates.js"
 import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 import { Lifecycle } from "./utils/lifecycle.js"
-import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "open-responses"
@@ -443,23 +441,24 @@ interface ReasoningStreamItem {
 // =============================================================================
 // Request Lowering
 // =============================================================================
-export const lowerTool = Effect.fn("OpenResponses.lowerTool")(function* (
-  protocolName: string,
-  tool: ToolDefinition,
-  inputSchema: JsonSchema,
-) {
+export const lowerTool = Effect.fn("OpenResponses.lowerTool")(function* (protocolName: string, tool: ToolDefinition) {
   if (tool.native !== undefined)
     return yield* ProviderShared.invalidRequest(`${protocolName} does not support provider-native tool ${tool.name}`)
   return {
     type: "function" as const,
     name: tool.name,
     description: tool.description,
-    parameters: inputSchema,
+    parameters: tool.inputSchema,
     // The common tool definition does not currently express Responses strict-schema policy.
     strict: false,
   }
 })
 
+export const lowerTools = (tools: ReadonlyArray<ToolDefinition>, adapter: ProviderAdapter) =>
+  Effect.forEach(tools, (tool) =>
+    tool.native !== undefined && adapter.nativeTool ? adapter.nativeTool(tool.native) : lowerTool(adapter.name, tool),
+  )
+
 export const lowerToolChoice = (protocolName: string, toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
   ProviderShared.matchToolChoice(protocolName, toolChoice, {
     auto: () => "auto" as const,
@@ -821,14 +820,7 @@ export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAd
   return {
     ...(yield* lowerConversation(projected.request, adapter)),
     ...lowerGeneration(request),
-    tools:
-      projected.tools.length === 0
-        ? undefined
-        : yield* Effect.forEach(projected.tools, (tool) =>
-            tool.native !== undefined && adapter.nativeTool
-              ? adapter.nativeTool(tool.native)
-              : lowerTool(adapter.name, tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model)),
-          ),
+    tools: projected.tools.length === 0 ? undefined : yield* lowerTools(projected.tools, adapter),
     tool_choice:
       allowedToolChoice(request) ??
       (request.toolChoice ? yield* lowerToolChoice(adapter.name, request.toolChoice) : undefined),

packages/ai/src/protocols/openai-chat.ts

@@ -17,7 +17,6 @@ import {
   type FinishReason,
   type FinishReasonDetails,
   type CacheHint,
-  type JsonSchema,
   type LLMRequest,
   type MediaPart,
   type ReasoningPart,
@@ -29,7 +28,6 @@ import { classifyProviderFailure } from "../provider-error.js"
 import { isRecord, JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { OpenAIOptions } from "./utils/openai-options.js"
 import { Lifecycle } from "./utils/lifecycle.js"
-import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "openai-chat"
@@ -330,17 +328,12 @@ interface LoweringOptions {
   readonly toolCallID?: (id: string) => string
 }
 
-const lowerTool = (
-  tool: ToolDefinition,
-  inputSchema: JsonSchema,
-  options: LoweringOptions,
-  supportsStrictMode: boolean,
-): OpenAIChatTool => ({
+const lowerTool = (tool: ToolDefinition, options: LoweringOptions, supportsStrictMode: boolean): OpenAIChatTool => ({
   type: "function",
   function: {
     name: tool.name,
     description: tool.description,
-    parameters: inputSchema,
+    parameters: tool.inputSchema,
     ...(supportsStrictMode ? { strict: false } : {}),
   },
   cache_control: options.cacheControl?.(tool.cache),
@@ -825,14 +818,7 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
         ? hasHistory
           ? []
           : undefined
-        : flattened.tools.map((tool) =>
-            lowerTool(
-              tool,
-              ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model),
-              options,
-              supportsStrictMode,
-            ),
-          ),
+        : flattened.tools.map((tool) => lowerTool(tool, options, supportsStrictMode)),
     tool_choice: hasActiveTools && request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined,
     stream: true as const,
     ...(supportsUsageInStreaming ? { stream_options: { include_usage: true } } : {}),

packages/ai/src/protocols/openai-images.ts

@@ -11,13 +11,11 @@ import { Media } from "../media.js"
 import { Framing } from "../route/framing.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords, type MediaUsage } from "../schema/index.js"
+import { mergeJsonRecords, type MediaUsage, type OpenString } from "../schema/index.js"
 import { ProviderShared } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "openai-images"
-const NAME = "OpenAI Images"
-const PROVIDER = ProviderID.make("openai")
+const route = MediaProtocol.identity({ id: "openai-images", name: "OpenAI Images", provider: "openai" })
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/images/generations"
 export const EDIT_PATH = "/images/edits"
@@ -26,13 +24,11 @@ export const EDIT_PATH = "/images/edits"
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type OpenAIImageString<Known extends string> = Known | (string & {})
-
 /** Provider-native options. Common fields (`n`, `size`, `format`, `images`, `mask`) live on the request. */
 export type OpenAIImageOptions = {
-  readonly quality?: OpenAIImageString<"auto" | "low" | "medium" | "high" | "standard" | "hd">
-  readonly background?: OpenAIImageString<"auto" | "opaque" | "transparent">
-  readonly moderation?: OpenAIImageString<"auto" | "low">
+  readonly quality?: OpenString<"auto" | "low" | "medium" | "high" | "standard" | "hd">
+  readonly background?: OpenString<"auto" | "opaque" | "transparent">
+  readonly moderation?: OpenString<"auto" | "low">
   readonly outputCompression?: number
   /** Previews sent before the final image when streaming (default 2); ignored by `Image.generate`. */
   readonly partialImages?: number
@@ -83,7 +79,7 @@ const StreamEvent = Schema.Union([
   }),
 ])
 
-const decodeEvent = MediaProtocol.decodeFrame(ADAPTER, NAME, StreamEvent)
+const decodeEvent = route.decodeFrame(StreamEvent)
 const decodeDocument = Schema.decodeUnknownEffect(Schema.fromJsonString(OpenAIImageResponse))
 
 /** `generate` reads the whole JSON response as one frame, with the requested format for responses that omit it. */
@@ -116,21 +112,11 @@ const streamOptions = (request: MediaProtocol.Addressed<Request>) => {
   if (request.mode !== "stream") return Effect.succeed(undefined)
   if (request.model.id.startsWith("dall-e"))
     return Effect.fail(
-      ProviderShared.unsupportedOperation({
-        operation: "media.stream",
-        provider: PROVIDER,
-        route: ADAPTER,
-        message: `${request.model.id} does not stream; use Image.generate or a GPT image model`,
-      }),
+      route.unsupported("media.stream", `${request.model.id} does not stream; use Image.generate or a GPT image model`),
     )
   if (request.n !== undefined && request.n > 1)
     return Effect.fail(
-      ProviderShared.unsupportedOperation({
-        operation: "media.n",
-        provider: PROVIDER,
-        route: ADAPTER,
-        message: `${NAME} streams one image; use Image.generate for n=${request.n}`,
-      }),
+      route.unsupported("media.n", `${route.name} streams one image; use Image.generate for n=${request.n}`),
     )
   return Effect.succeed({ stream: true, partial_images: request.providerOptions?.partialImages ?? 2 })
 }
@@ -140,7 +126,7 @@ const isEdit = (request: Request) => (request.images?.length ?? 0) > 0
 const isInline = (asset: Media.Asset) => asset.source.type === "bytes" || asset.source.type === "base64"
 
 const reference = (asset: Media.Asset) =>
-  ProviderShared.mediaReference(asset, PROVIDER, NAME).pipe(
+  ProviderShared.mediaReference(asset, route.provider, route.name).pipe(
     Effect.map((item) => (item.type === "ref" ? { file_id: item.value } : { image_url: item.value })),
   )
 
@@ -158,18 +144,17 @@ const fromRequest = Effect.fn("OpenAIImages.fromRequest")(function* (request: Me
   // Owned bytes go through multipart edits; remote URLs and file IDs use the JSON edits body instead.
   if (images.length > 0 && images.every(isInline) && (mask === undefined || isInline(mask))) {
     const form = new FormData()
-    form.append("model", request.model.id)
-    form.append("prompt", request.prompt)
-    Object.entries(fields ?? {}).forEach(([key, value]) => {
-      if (RESERVED_FORM_FIELDS.has(key)) return
-      form.append(key, typeof value === "string" ? value : ProviderShared.encodeJson(value))
-    })
-    const uploads = yield* Effect.forEach(images, (image) => MediaInput.inlineBytes(ADAPTER, image))
+    MediaInput.appendFields(
+      form,
+      { model: request.model.id, prompt: request.prompt },
+      { overlay: fields, reserved: RESERVED_FORM_FIELDS },
+    )
+    const uploads = yield* Effect.forEach(images, (image) => MediaInput.inlineBytes(route.id, image))
     uploads.forEach((data, index) =>
       form.append("image[]", MediaInput.blob(data, images[index].mediaType), `image-${index}`),
     )
     if (mask !== undefined)
-      form.append("mask", MediaInput.blob(yield* MediaInput.inlineBytes(ADAPTER, mask), mask.mediaType), "mask")
+      form.append("mask", MediaInput.blob(yield* MediaInput.inlineBytes(route.id, mask), mask.mediaType), "mask")
     return MediaProtocol.multipart(form)
   }
 
@@ -210,22 +195,18 @@ const usage = (value: Schema.Schema.Type<typeof Usage> | undefined): MediaUsage
       }
 
 const eventImage = (frame: string, label: string, data: string, format: string) =>
-  MediaInput.decodedAsset(
-    (message, cause) => MediaProtocol.frameError(ADAPTER, message, frame, cause),
-    label,
-    data,
-    `image/${format}`,
-    { info: { format } },
-  )
+  MediaInput.decodedAsset((message, cause) => route.frameError(message, frame, cause), label, data, `image/${format}`, {
+    info: { format },
+  })
 
 const onEvent = Effect.fn("OpenAIImages.onEvent")(function* (state: State, frame: string) {
   const event = yield* decodeEvent(frame)
   const format = event.output_format
   if ("partial_image_index" in event) {
-    const image = yield* eventImage(frame, `${NAME} partial image`, event.b64_json, format)
+    const image = yield* eventImage(frame, `${route.name} partial image`, event.b64_json, format)
     return [state, [ImagePartialEvent.make({ index: event.partial_image_index, image })]] as const
   }
-  const image = yield* eventImage(frame, `${NAME} result ${state.completed}`, event.b64_json, format)
+  const image = yield* eventImage(frame, `${route.name} result ${state.completed}`, event.b64_json, format)
   return [
     { ...state, completed: state.completed + 1, format, usage: usage(event.usage) },
     [ImageOutputEvent.make({ index: state.completed, image })],
@@ -233,25 +214,20 @@ const onEvent = Effect.fn("OpenAIImages.onEvent")(function* (state: State, frame
 })
 
 const onDocument = Effect.fn("OpenAIImages.onDocument")(function* (frame: Exclude<Frame, string>) {
-  const invalid = (message: string, cause?: unknown) =>
-    MediaProtocol.frameError(ADAPTER, message, frame.document, cause)
+  const invalid = (message: string, cause?: unknown) => route.frameError(message, frame.document, cause)
   const decoded = yield* decodeDocument(frame.document).pipe(
-    Effect.mapError((cause) => invalid(`${NAME} returned an invalid response`, cause)),
+    Effect.mapError((cause) => invalid(`${route.name} returned an invalid response`, cause)),
   )
   const format = decoded.output_format ?? frame.requested ?? "png"
   const mediaType = `image/${format}`
-  const images = yield* Effect.forEach(decoded.data, (item, index) => {
-    const providerMetadata =
-      item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } }
-    if (item.b64_json)
-      return MediaInput.decodedAsset(invalid, `${NAME} result ${index}`, item.b64_json, mediaType, {
-        info: { format },
-        providerMetadata,
-      })
-    if (item.url) return Effect.succeed(Media.url(item.url, { mediaType, info: { format }, providerMetadata }))
-    return Effect.fail(invalid(`${NAME} result ${index} has neither image data nor a URL`))
-  })
-  if (images.length === 0) return yield* invalid(`${NAME} returned no images`)
+  const images = yield* Effect.forEach(decoded.data, (item, index) =>
+    MediaInput.imageOutput(invalid, `${route.name} result ${index}`, item, mediaType, {
+      info: { format },
+      providerMetadata:
+        item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
+    }),
+  )
+  if (images.length === 0) return yield* invalid(`${route.name} returned no images`)
   const state: State = { completed: images.length, format, usage: usage(decoded.usage) }
   return [state, images.map((image, index) => ImageOutputEvent.make({ index, image }))] as const
 })
@@ -259,7 +235,7 @@ const onDocument = Effect.fn("OpenAIImages.onDocument")(function* (frame: Exclud
 const step = (state: State, frame: Frame) => (typeof frame === "string" ? onEvent(state, frame) : onDocument(frame))
 
 const finish = (state: State) => {
-  if (state.completed === 0) return Effect.fail(MediaProtocol.incomplete(ADAPTER))
+  if (state.completed === 0) return Effect.fail(route.incomplete())
   return Effect.succeed([
     ImageFinishEvent.make({ usage: state.usage, providerMetadata: { openai: { outputFormat: state.format } } }),
   ])
@@ -269,9 +245,7 @@ const finish = (state: State) => {
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, ImageEvent, Frame, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, ImageEvent, Frame, State>(route, {
   unsupported: ["aspectRatio", "seed"],
   body: { from: fromRequest },
   frames: (bytes, context) =>
@@ -287,13 +261,7 @@ export const protocol = MediaProtocol.stream<Request, ImageEvent, Frame, State>(
 
 export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<OpenAIImageOptions, Frame, State>(
-    {
-      id: ADAPTER,
-      provider: PROVIDER,
-      protocol,
-      baseURL: DEFAULT_BASE_URL,
-      path: ({ request }) => (isEdit(request) ? EDIT_PATH : PATH),
-    },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: ({ request }) => (isEdit(request) ? EDIT_PATH : PATH) },
     input,
   )
 

packages/ai/src/protocols/openai-responses.ts

@@ -5,21 +5,12 @@ import { Auth } from "../route/auth.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
-import {
-  LLMRequest,
-  mergeJsonRecords,
-  type JsonSchema,
-  type LanguageModel,
-  type ToolDefinition,
-  type ToolEntry,
-} from "../schema/index.js"
+import { LLMRequest, type ToolDefinition, type ToolEntry } from "../schema/index.js"
 import { resolveEffortUpdates } from "../effort-updates.js"
 import { OpenResponses } from "./open-responses.js"
 import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
-import { OpenAIImage } from "./utils/openai-image.js"
 import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"
-import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { OpenResponsesChannel } from "./open-responses-channel.js"
 import { ResponsesCompaction } from "./utils/responses-compaction.js"
 import { ResponsesCheckpoint } from "./utils/responses-checkpoint.js"
@@ -48,7 +39,16 @@ const OpenAIResponsesImageGenerationTool = Schema.Struct({
   output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
   partial_images: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
   quality: Schema.optional(Schema.Literals(["auto", "low", "medium", "high"])),
-  size: Schema.optional(OpenAIImage.Size),
+  size: Schema.optional(
+    Schema.String.check(
+      Schema.makeFilter((value) => {
+        if (value === "auto") return undefined
+        const match = /^(\d+)x(\d+)$/.exec(value)
+        if (!match) return "image size must be `auto` or `{width}x{height}`"
+        return Number(match[1]) > 0 && Number(match[2]) > 0 ? undefined : "image dimensions must be positive integers"
+      }),
+    ),
+  ),
 })
 
 const OpenAIResponsesHostedToolItem = Schema.Union([
@@ -135,11 +135,6 @@ export const CompactionTrigger = Schema.Struct({ type: Schema.Literal("compactio
 const CheckpointBody = Schema.Struct({
   ...OpenAIResponsesBody.fields,
   input: Schema.Array(Schema.Union([OpenAIResponsesInputItem, CompactionTrigger])),
-  store: Schema.Literal(false),
-  prompt_cache_retention: optionalNull(Schema.String),
-  prompt_cache_options: optionalNull(
-    Schema.Struct({ mode: Schema.optional(Schema.String), ttl: Schema.optional(Schema.String) }),
-  ),
 })
 
 const adapter = {
@@ -166,20 +161,19 @@ const nativeImageTool = (tool: ToolDefinition) => {
   return Schema.is(OpenAIResponsesImageGenerationTool)(native) ? native : undefined
 }
 
-const lowerTool = Effect.fn("OpenAIResponses.lowerTool")(function* (tool: ToolDefinition, inputSchema: JsonSchema) {
+const lowerTool = Effect.fn("OpenAIResponses.lowerTool")(function* (tool: ToolDefinition) {
   const native = nativeImageToolInput(tool)
   if (native !== undefined) {
     if (Schema.is(OpenAIResponsesImageGenerationTool)(native)) return native
     return yield* ProviderShared.invalidRequest("OpenAI Responses image generation tool options are invalid")
   }
-  return yield* OpenResponses.lowerTool(NAME, tool, inputSchema)
+  return yield* OpenResponses.lowerTool(NAME, tool)
 })
 
 // Native namespaces hold only function tools, so deeper levels flatten into
 // the leaf names the same way non-native protocols flatten the whole tree.
-const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (tool: ToolEntry, model: LanguageModel) {
-  if (tool.type === "tool")
-    return yield* lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, model))
+const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (tool: ToolEntry) {
+  if (tool.type === "tool") return yield* lowerTool(tool)
   // OpenAI requires a namespace description; fall back to a generic one so a
   // missing description never blocks the request.
   return {
@@ -187,11 +181,13 @@ const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (to
     name: tool.name,
     description: tool.description ?? `Tools in the ${tool.name} namespace.`,
     tools: yield* Effect.forEach(ProviderShared.flattenTools(tool.tools), (leaf) =>
-      OpenResponses.lowerTool(NAME, leaf, ToolSchemaProjection.modelCompatibility(leaf.inputSchema, model)),
+      OpenResponses.lowerTool(NAME, leaf),
     ),
   }
 })
 
+const lowerTools = (request: LLMRequest) => Effect.forEach(request.tools, lowerToolEntry)
+
 const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, tools: ReadonlyArray<ToolEntry>) =>
   ProviderShared.matchToolChoice(NAME, toolChoice, {
     auto: () => "auto" as const,
@@ -215,10 +211,7 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
     ...(yield* OpenResponses.lowerConversation(updates.request, adapter)),
     ...OpenResponses.lowerGeneration(request, { ...options, reasoningEffort: updates.effort }),
     context_management: management?.map((edit) => ({ type: edit.type, compact_threshold: edit.compactThreshold })),
-    tools:
-      request.tools.length === 0
-        ? undefined
-        : yield* Effect.forEach(request.tools, (tool) => lowerToolEntry(tool, request.model)),
+    tools: request.tools.length === 0 ? undefined : yield* lowerTools(request),
     tool_choice:
       request.tools.length === 0
         ? undefined
@@ -230,7 +223,6 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
 const checkpointBody = {
   schema: CheckpointBody,
   from: Effect.fn("OpenAIResponses.checkpointBody")(function* (request: LLMRequest) {
-    const native = yield* fromRequest(LLMRequest.update(request, { toolChoice: undefined }))
     const overlay = request.http?.body
     // Complete history is required for stateless replay and SSE recovery. Raw input overrides bypass that contract.
     if (
@@ -241,18 +233,13 @@ const checkpointBody = {
       return yield* ProviderShared.invalidRequest(
         "Trigger compaction requires complete canonical history, not an input or continuation override",
       )
-    return yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(CheckpointBody))({
-      ...mergeJsonRecords(native, overlay),
-      input: [...native.input, { type: "compaction_trigger" }],
-      stream: true,
-      store: false,
-      parallel_tool_calls: true,
-      tool_choice: undefined,
-      context_management: undefined,
-      text: undefined,
-      max_output_tokens: undefined,
-      max_tool_calls: undefined,
-    })
+    if (overlay?.stream !== undefined && overlay.stream !== true)
+      return yield* ProviderShared.invalidRequest("Trigger compaction requires a streamed response")
+    const native = yield* fromRequest(request)
+    return {
+      ...native,
+      input: [...native.input, { type: "compaction_trigger" as const }],
+    }
   }),
 }
 
@@ -334,7 +321,10 @@ export const transport = channelTransport({
 })
 
 export const route = Route.make({
-  compact: { endpoint: ResponsesCompaction.make(adapter), trigger: ResponsesCheckpoint.make(checkpointBody) },
+  compact: {
+    endpoint: ResponsesCompaction.make(adapter, lowerTools),
+    trigger: ResponsesCheckpoint.make(checkpointBody),
+  },
   id: ADAPTER,
   provider: "openai",
   providerMetadataKey: "openai",

packages/ai/src/protocols/openai-speech.ts

@@ -2,13 +2,11 @@ import { Effect, Schema } from "effect"
 import { Framing } from "../route/framing.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords, type MediaUsage } from "../schema/index.js"
+import { mergeJsonRecords, type MediaUsage } from "../schema/index.js"
 import { SpeechModel, type SpeechEvent, type SpeechRequestFor } from "../speech.js"
 import { SpeechStream } from "./utils/speech-stream.js"
 
-const ADAPTER = "openai-speech"
-const NAME = "OpenAI Speech"
-const PROVIDER = ProviderID.make("openai")
+const route = MediaProtocol.identity({ id: "openai-speech", name: "OpenAI Speech", provider: "openai" })
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/audio/speech"
 /** `pcm` is raw 24 kHz, 16-bit signed little-endian mono samples without a header. */
@@ -44,7 +42,7 @@ const SpeechStreamEvent = Schema.Union([
   }),
 ])
 
-const decodeEvent = MediaProtocol.decodeFrame(ADAPTER, NAME, SpeechStreamEvent)
+const decodeEvent = route.decodeFrame(SpeechStreamEvent)
 
 // ---------------------------------------------------------------------------
 // 4. Parser state
@@ -110,9 +108,9 @@ const onEvent = Effect.fn("OpenAISpeech.onEvent")(function* (state: State, frame
 })
 
 const finish = (state: State, context: MediaProtocol.ResponseContext<Request>) => {
-  if (isSse(context.body) && !state.done) return Effect.fail(MediaProtocol.incomplete(ADAPTER))
+  if (isSse(context.body) && !state.done) return Effect.fail(route.incomplete())
   const format = context.request.format ?? "mp3"
-  return SpeechStream.finish(ADAPTER, state, {
+  return SpeechStream.finish(route, state, {
     ...(format === "pcm" ? SpeechStream.pcm("pcm_s16le", PCM_SAMPLE_RATE) : SpeechStream.container(format)),
     usage: state.usage,
   })
@@ -122,9 +120,7 @@ const finish = (state: State, context: MediaProtocol.ResponseContext<Request>) =
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint8Array, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint8Array, State>(route, {
   unsupported: ["language", "timestamps"],
   body: { from: fromRequest },
   frames: (bytes, context) => (isSse(context.body) ? Framing.sse.frame(bytes) : bytes),
@@ -135,7 +131,7 @@ export const protocol = MediaProtocol.stream<Request, SpeechEvent, string | Uint
 
 export const model = (input: MediaRoute.ModelInput) =>
   SpeechModel.fromRoute<OpenAISpeechOptions, string | Uint8Array, State>(
-    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
     input,
   )
 

packages/ai/src/protocols/openai-transcription.ts

@@ -2,7 +2,7 @@ import { Effect, Schema, Stream } from "effect"
 import { Framing } from "../route/framing.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords, type MediaUsage } from "../schema/index.js"
+import { mergeJsonRecords, type MediaUsage } from "../schema/index.js"
 import {
   TranscriptionFinishEvent,
   TranscriptionModel,
@@ -16,9 +16,7 @@ import { mediaTypeExtension } from "../utils/media-type.js"
 import { ProviderShared } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "openai-transcription"
-const NAME = "OpenAI Transcription"
-const PROVIDER = ProviderID.make("openai")
+const route = MediaProtocol.identity({ id: "openai-transcription", name: "OpenAI Transcription", provider: "openai" })
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/audio/transcriptions"
 
@@ -85,8 +83,8 @@ const Event = Schema.Union([
 const Transcript = Schema.Struct(transcriptFields)
 type Transcript = Schema.Schema.Type<typeof Transcript>
 
-const decodeEvent = MediaProtocol.decodeFrame(ADAPTER, NAME, Event)
-const decodeTranscript = MediaProtocol.decodeFrame(ADAPTER, NAME, Transcript)
+const decodeEvent = route.decodeFrame(Event)
+const decodeTranscript = route.decodeFrame(Transcript)
 
 type Frame = string | { readonly document: string }
 
@@ -120,24 +118,21 @@ const capabilities = (model: string): Capabilities => {
   return TRANSCRIBE
 }
 
-const unsupported = (operation: string, message: string) =>
-  Effect.fail(ProviderShared.unsupportedOperation({ operation, provider: PROVIDER, route: ADAPTER, message }))
-
 const validate = (request: MediaProtocol.Addressed<Request>, model: Capabilities) => {
   const id = request.model.id
   if (request.mode === "stream" && !model.stream)
-    return unsupported("media.stream", `${id} does not stream; use Transcription.generate`)
+    return Effect.fail(route.unsupported("media.stream", `${id} does not stream; use Transcription.generate`))
   if (request.diarize === true && !model.diarize)
-    return unsupported("media.diarize", `${id} does not diarize; use gpt-4o-transcribe-diarize`)
+    return Effect.fail(route.unsupported("media.diarize", `${id} does not diarize; use gpt-4o-transcribe-diarize`))
   if (request.prompt !== undefined && model.diarize)
-    return unsupported("media.prompt", `${id} does not accept a prompt`)
+    return Effect.fail(route.unsupported("media.prompt", `${id} does not accept a prompt`))
   if (
     request.timestamps === undefined ||
     request.timestamps === "none" ||
     model.timestamps.includes(request.timestamps)
   )
     return Effect.void
-  return unsupported("media.timestamps", `${id} does not return ${request.timestamps} timestamps`)
+  return Effect.fail(route.unsupported("media.timestamps", `${id} does not return ${request.timestamps} timestamps`))
 }
 
 const RESERVED_FORM_FIELDS = new Set([
@@ -150,11 +145,6 @@ const RESERVED_FORM_FIELDS = new Set([
   "stream",
 ])
 
-const appendField = (form: FormData, key: string, value: unknown) => {
-  if (Array.isArray(value)) return value.forEach((item) => form.append(`${key}[]`, String(item)))
-  form.append(key, typeof value === "object" && value !== null ? ProviderShared.encodeJson(value) : String(value))
-}
-
 const fromRequest = Effect.fn("OpenAITranscription.fromRequest")(function* (request: MediaProtocol.Addressed<Request>) {
   const model = capabilities(request.model.id)
   yield* validate(request, model)
@@ -162,18 +152,18 @@ const fromRequest = Effect.fn("OpenAITranscription.fromRequest")(function* (requ
   const extension = mediaTypeExtension(request.audio.mediaType)
   if (extension === undefined)
     return yield* ProviderShared.invalidRequest(
-      `${NAME} cannot name a ${request.audio.mediaType} upload; send mp3, mp4, m4a, wav, webm, ogg, or flac audio`,
+      `${route.name} cannot name a ${request.audio.mediaType} upload; send mp3, mp4, m4a, wav, webm, ogg, or flac audio`,
     )
-  const audio = yield* MediaInput.inlineBytes(ADAPTER, request.audio)
+  const audio = yield* MediaInput.inlineBytes(route.id, request.audio)
   const responseFormat = model.diarize
     ? "diarized_json"
     : request.timestamps === undefined || request.timestamps === "none"
       ? undefined
       : "verbose_json"
-  const native = Object.entries(mergeJsonRecords(request.providerOptions, request.http?.body) ?? {}).filter(
-    ([key]) => !RESERVED_FORM_FIELDS.has(key),
-  )
-  const fields = mergeJsonRecords(
+  const form = new FormData()
+  form.append("file", MediaInput.blob(audio, request.audio.mediaType), `audio.${extension}`)
+  MediaInput.appendFields(
+    form,
     {
       model: request.model.id,
       language: model.languageField === "language" ? request.language : undefined,
@@ -185,11 +175,12 @@ const fromRequest = Effect.fn("OpenAITranscription.fromRequest")(function* (requ
       chunking_strategy: model.diarize ? "auto" : undefined,
       stream: request.mode === "stream" ? true : undefined,
     },
-    Object.fromEntries(native),
+    {
+      overlay: mergeJsonRecords(request.providerOptions, request.http?.body),
+      reserved: RESERVED_FORM_FIELDS,
+      repeatArrays: true,
+    },
   )
-  const form = new FormData()
-  form.append("file", MediaInput.blob(audio, request.audio.mediaType), `audio.${extension}`)
-  Object.entries(fields ?? {}).forEach(([key, value]) => appendField(form, key, value))
   return MediaProtocol.multipart(form)
 })
 
@@ -233,7 +224,7 @@ const usage = (value: Transcript["usage"]): MediaUsage | undefined => {
 
 const finish = (state: State) => {
   const transcript = state.transcript
-  if (transcript === undefined) return Effect.fail(MediaProtocol.incomplete(ADAPTER))
+  if (transcript === undefined) return Effect.fail(route.incomplete())
   const segments = transcript.segments?.map(segment) ?? state.segments
   return Effect.succeed([
     TranscriptionFinishEvent.make({
@@ -251,9 +242,7 @@ const finish = (state: State) => {
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.stream<Request, TranscriptionEvent, Frame, State>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.stream<Request, TranscriptionEvent, Frame, State>(route, {
   unsupported: ["speakers"],
   body: { from: fromRequest },
   frames: (bytes, context) =>
@@ -267,7 +256,7 @@ export const protocol = MediaProtocol.stream<Request, TranscriptionEvent, Frame,
 
 export const model = (input: MediaRoute.ModelInput) =>
   TranscriptionModel.fromRoute<OpenAITranscriptionOptions, Frame, State>(
-    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
     input,
   )
 

packages/ai/src/protocols/replicate-images.ts

@@ -5,12 +5,10 @@ import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords, type AIError } from "../schema/index.js"
+import { mergeJsonRecords, type AIError } from "../schema/index.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 
-const ADAPTER = "replicate-images"
-const NAME = "Replicate"
-const PROVIDER = ProviderID.make("replicate")
+const route = MediaProtocol.identity({ id: "replicate-images", name: "Replicate", provider: "replicate" })
 export const DEFAULT_BASE_URL = "https://api.replicate.com"
 const OUTPUT_RETENTION = Duration.hours(1)
 const MAX_DATA_URL_BYTES = 256 * 1024
@@ -71,9 +69,11 @@ const inlineSize = (source: Media.Source) => {
 const fileInput = (asset: Media.Asset) => {
   if (inlineSize(asset.source) > MAX_DATA_URL_BYTES)
     return Effect.fail(
-      ProviderShared.invalidRequest(`${NAME} data URL inputs are limited to 256 KB; pass a larger file by https URL`),
+      ProviderShared.invalidRequest(
+        `${route.name} data URL inputs are limited to 256 KB; pass a larger file by https URL`,
+      ),
     )
-  return ProviderShared.mediaReference(asset, undefined, NAME).pipe(Effect.map((reference) => reference.value))
+  return ProviderShared.mediaReference(asset, undefined, route.name).pipe(Effect.map((reference) => reference.value))
 }
 
 const inputValue = (value: unknown): Effect.Effect<unknown, AIError> => {
@@ -98,7 +98,7 @@ const fromRequest = Effect.fn("ReplicateImages.fromRequest")(function* (request:
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodePrediction = MediaProtocol.decodeJson(ADAPTER, NAME, Prediction)
+const decodePrediction = route.decodeJson(Prediction)
 
 const decodeStart = Effect.fn("ReplicateImages.decodeStart")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -130,15 +130,16 @@ const decodeResult = Effect.fn("ReplicateImages.decodeResult")(function* (
   if (status === "failed" || status === "cancelled" || status === "expired")
     return yield* output.ended(
       status,
-      `${NAME} prediction ${context.token.id} ${prediction.status}${typeof prediction.error === "string" ? `: ${prediction.error}` : ""}`,
+      `${route.name} prediction ${context.token.id} ${prediction.status}${typeof prediction.error === "string" ? `: ${prediction.error}` : ""}`,
     )
-  if (status !== "completed") return yield* output.invalid(`${NAME} prediction ${context.token.id} has not finished`)
+  if (status !== "completed")
+    return yield* output.invalid(`${route.name} prediction ${context.token.id} has not finished`)
   if (prediction.data_removed === true)
-    return yield* output.ended("expired", `${NAME} removed the output of prediction ${context.token.id}`)
+    return yield* output.ended("expired", `${route.name} removed the output of prediction ${context.token.id}`)
   if (!isOutput(prediction.output))
-    return yield* output.invalid(`${NAME} prediction ${context.token.id} returned output that is not image URLs`)
+    return yield* output.invalid(`${route.name} prediction ${context.token.id} returned output that is not image URLs`)
   const urls = typeof prediction.output === "string" ? [prediction.output] : prediction.output
-  if (urls.length === 0) return yield* output.invalid(`${NAME} prediction ${context.token.id} returned no images`)
+  if (urls.length === 0) return yield* output.invalid(`${route.name} prediction ${context.token.id} returned no images`)
   const predictTime = prediction.metrics?.predict_time ?? undefined
   const completedAt = prediction.completed_at ?? undefined
   const expiresAt =
@@ -154,9 +155,7 @@ const decodeResult = Effect.fn("ReplicateImages.decodeResult")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.queued<Request, ImageResponse, Token>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.queued<Request, ImageResponse, Token>(route, {
   token: Token,
   unsupported: ["images", "mask", "n", "size", "aspectRatio", "seed", "format"],
   start: { body: { from: fromRequest }, decode: decodeStart },
@@ -168,8 +167,6 @@ export const protocol = MediaProtocol.queued<Request, ImageResponse, Token>({
 export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<ReplicateImageOptions, Token>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       path: ({ request }) =>

packages/ai/src/protocols/runway-video.ts

@@ -4,13 +4,11 @@ import type { Status } from "../generation.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { VideoModel, VideoResponse, type VideoRequestFor } from "../video.js"
 import { ProviderShared, optionalArray, optionalNull } from "./shared.js"
 
-const ADAPTER = "runway-video"
-const NAME = "Runway"
-const PROVIDER = ProviderID.make("runway")
+const route = MediaProtocol.identity({ id: "runway-video", name: "Runway", provider: "runway" })
 export const DEFAULT_BASE_URL = "https://api.dev.runwayml.com/v1"
 /** Every Runway request must pin the API version. */
 export const API_VERSION = "2024-11-06"
@@ -25,16 +23,14 @@ const OUTPUT_RETENTION = Duration.hours(24)
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type RunwayVideoString<Known extends string> = Known | (string & {})
-
 /**
  * Provider-native options. Common fields lower to Runway's names: `aspectRatio` → `ratio` (Runway expects pixel
  * ratios such as `1280:720` for most models), `durationSeconds` → `duration`, `audio`, `negativePrompt`,
  * `resolution`, `references`, and `frames` → `promptImage`.
  */
 export type RunwayVideoOptions = {
-  readonly contentModeration?: { readonly publicFigureThreshold?: RunwayVideoString<"auto" | "low"> }
-  readonly outputFormat?: RunwayVideoString<"mp4" | "prores" | "png_sequence">
+  readonly contentModeration?: { readonly publicFigureThreshold?: OpenString<"auto" | "low"> }
+  readonly outputFormat?: OpenString<"mp4" | "prores" | "png_sequence">
 } & Record<string, unknown>
 
 export type Request = VideoRequestFor<RunwayVideoOptions>
@@ -75,7 +71,7 @@ const STATUS = {
 
 // Runway accepts HTTPS URLs, `runway://` upload URIs, and data URIs, all as one string.
 const mediaUri = (asset: Media.Asset) =>
-  ProviderShared.mediaReference(asset, PROVIDER, NAME).pipe(Effect.map((reference) => reference.value))
+  ProviderShared.mediaReference(asset, route.provider, route.name).pipe(Effect.map((reference) => reference.value))
 
 const fromRequest = Effect.fn("RunwayVideo.fromRequest")(function* (request: Request) {
   const first = request.frames?.first === undefined ? undefined : yield* mediaUri(request.frames.first)
@@ -113,12 +109,12 @@ const fromRequest = Effect.fn("RunwayVideo.fromRequest")(function* (request: Req
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeStart = MediaProtocol.decodeStarted(ADAPTER, NAME, StartResponse, (value) => ({
+const decodeStart = route.decodeStarted(StartResponse, (value) => ({
   token: { taskID: value.id },
   snapshot: { id: value.id, status: "queued" },
 }))
 
-const decodeTask = MediaProtocol.decodeJson(ADAPTER, NAME, Task)
+const decodeTask = route.decodeJson(Task)
 
 const decodeStatus = Effect.fn("RunwayVideo.decodeStatus")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -138,16 +134,17 @@ const decodeResult = Effect.fn("RunwayVideo.decodeResult")(function* (
   const status = yield* MediaProtocol.status(STATUS, task.status, output)
   if (status === "failed") {
     const code = task.failureCode ?? undefined
-    const message = `${NAME} task failed${code === undefined ? "" : ` (${code})`}${task.failure ? `: ${task.failure}` : ""}`
+    const message = `${route.name} task failed${code === undefined ? "" : ` (${code})`}${task.failure ? `: ${task.failure}` : ""}`
     // Runway failure codes are dotted paths; every moderation outcome carries a SAFETY segment.
     if (code !== undefined && /(^|\.)SAFETY(\.|$)/.test(code)) return yield* output.contentPolicy(message)
     return yield* output.ended("failed", message)
   }
   if (status === "cancelled")
-    return yield* output.ended("cancelled", `${NAME} task ${context.token.taskID} was cancelled`)
-  if (status !== "completed") return yield* output.invalid(`${NAME} task ${context.token.taskID} has not finished`)
+    return yield* output.ended("cancelled", `${route.name} task ${context.token.taskID} was cancelled`)
+  if (status !== "completed")
+    return yield* output.invalid(`${route.name} task ${context.token.taskID} has not finished`)
   const urls = task.output ?? []
-  if (urls.length === 0) return yield* output.invalid(`${NAME} task succeeded without any output`)
+  if (urls.length === 0) return yield* output.invalid(`${route.name} task succeeded without any output`)
   return new VideoResponse({
     videos: yield* Effect.forEach(urls, (url) =>
       MediaProtocol.expiringUrl(url, OUTPUT_RETENTION, { mediaType: "video/mp4" }),
@@ -168,9 +165,7 @@ const decodeResult = Effect.fn("RunwayVideo.decodeResult")(function* (
 
 const taskPath = (token: Token) => `${TASKS_PATH}/${token.taskID}`
 
-export const protocol = MediaProtocol.queued<Request, VideoResponse, Token>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.queued<Request, VideoResponse, Token>(route, {
   token: Token,
   unsupported: ["n"],
   start: { body: { from: fromRequest }, decode: decodeStart },
@@ -188,8 +183,6 @@ const startPath = (request: Request) => {
 export const model = (input: MediaRoute.ModelInput) =>
   VideoModel.fromRoute<RunwayVideoOptions, Token>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       headers: { "X-Runway-Version": API_VERSION },

packages/ai/src/protocols/shared.ts

@@ -1,6 +1,5 @@
 import { Tool } from "@opencode/schema/tool"
-import { Effect, Option, Schema, Stream } from "effect"
-import * as Sse from "effect/unstable/encoding/Sse"
+import { Effect, Option, Schema } from "effect"
 import { Headers, HttpClientRequest } from "effect/unstable/http"
 import { Media } from "../media.js"
 import {
@@ -13,17 +12,16 @@ import {
   ToolDefinition,
   type ContentPart,
   type MediaPart,
+  type OpenString,
   type ProviderID,
   type TextPart,
   type ToolEntry,
   type ToolResultPart,
 } from "../schema/index.js"
+import { Json, decodeJson, encodeJson } from "../utils/json.js"
 import { isRecord } from "../utils/record.js"
-export { isRecord }
+export { Json, decodeJson, encodeJson, isRecord }
 
-export const Json = Schema.fromJsonString(Schema.Unknown)
-export const decodeJson = Schema.decodeUnknownSync(Json)
-export const encodeJson = Schema.encodeSync(Json)
 const isJson = Schema.is(Schema.Json)
 export const JsonObject = Schema.Record(Schema.String, Schema.Unknown)
 export const optionalArray = <const S extends Schema.Top>(schema: S) => Schema.optional(Schema.Array(schema))
@@ -35,7 +33,7 @@ export const lenient = <const S extends Schema.Top>(schema: S) =>
   )
 /** Provider-defined string enum: known values for autocomplete, any string accepted at runtime. */
 export const knownString = <Known extends string>() =>
-  Schema.declare<Known | (string & {})>((value): value is Known | (string & {}) => typeof value === "string", {
+  Schema.declare<OpenString<Known>>((value): value is OpenString<Known> => typeof value === "string", {
     expected: "string",
   })
 
@@ -112,6 +110,14 @@ export const sumTokens = (...values: ReadonlyArray<number | undefined>): number
   return values.reduce((acc: number, value) => acc + (value ?? 0), 0)
 }
 
+/**
+ * Caps an explicit thinking budget at half the output limit. Thinking counts against the output limit, so a budget
+ * near it leaves the answer, a tool call, or a summary without room. Smaller budgets, special values such as `-1` and
+ * `0`, and requests without an output limit pass through unchanged.
+ */
+export const fitThinkingBudget = (budget: number, maxTokens: number | undefined, minimum = 1) =>
+  maxTokens === undefined || budget <= maxTokens / 2 ? budget : Math.max(minimum, Math.floor(maxTokens / 2))
+
 export const eventError = (route: string, message: string, body?: string, cause?: unknown) =>
   new AIError({
     reason: new InvalidProviderOutputError({ route, message, body, cause }),
@@ -229,8 +235,6 @@ export const toolFileMedia = (item: Tool.FileContent): MediaPart => {
   return Message.media(asset, { filename: item.name })
 }
 
-export const trimBaseUrl = (value: string) => value.replace(/\/+$/, "")
-
 export const toolResultText = (part: ToolResultPart) => {
   if (part.result.type === "text") return String(part.result.value)
   if (part.result.type === "error") {
@@ -252,54 +256,6 @@ export const errorText = (error: unknown) => {
   return "Unknown stream error"
 }
 
-/**
- * `framing` step for Server-Sent Events. Decodes UTF-8, runs the SSE channel
- * decoder, optionally filters named events, and drops empty events and known
- * keepalives that proxies send as data. `[DONE]` is dropped by default or
- * retained for protocols that use it as their stream boundary. Retry control events are ignored without
- * interrupting the stream. Decoder failures become provider output errors so
- * the public error channel stays `AIError`.
- */
-export const sseFraming = (
-  bytes: Stream.Stream<Uint8Array, AIError>,
-  events?: ReadonlySet<string>,
-  includeDone = false,
-): Stream.Stream<string, AIError> =>
-  bytes.pipe(
-    Stream.decodeText(),
-    Stream.mapAccumEffect(
-      () => {
-        const output: Sse.Event[] = []
-        return {
-          output,
-          parser: Sse.makeParser((event) => {
-            if (event._tag === "Event") output.push(event)
-          }),
-        }
-      },
-      (state, chunk) =>
-        Effect.gen(function* () {
-          const error = state.parser.feed(chunk)
-          if (error) return yield* eventError("sse", error.message, chunk, error)
-          return [state, state.output.splice(0)] as const
-        }),
-    ),
-    Stream.filter(
-      (event) =>
-        (events === undefined || events.has(event.event)) &&
-        event.data.length > 0 &&
-        // Some OpenAI-compatible proxies serialize an empty flush as a bare
-        // `data: null`, between events or after `[DONE]`. No protocol has a
-        // null event, so it carries nothing and must not abort the stream.
-        event.data !== "null" &&
-        // Vertex AI partner models (e.g. `xai/grok-4.6`) send their SSE
-        // keepalive comment as `data: : keepalive` while reasoning.
-        event.data !== ": keepalive" &&
-        (event.data !== "[DONE]" || includeDone || (events !== undefined && event.event !== "message")),
-    ),
-    Stream.map((event) => event.data),
-  )
-
 /**
  * Canonical invalid-request constructor shared by protocol lowering.
  */

packages/ai/src/protocols/stability-images.ts

@@ -3,14 +3,12 @@ import type { HttpClientResponse } from "effect/unstable/http"
 import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { ProviderShared } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "stability-images"
-const UPSCALE_ADAPTER = "stability-upscale"
-const NAME = "Stability AI"
-const PROVIDER = ProviderID.make("stability")
+const route = MediaProtocol.identity({ id: "stability-images", name: "Stability AI", provider: "stability" })
+const upscaleRoute = MediaProtocol.identity({ id: "stability-upscale", name: "Stability AI", provider: "stability" })
 export const DEFAULT_BASE_URL = "https://api.stability.ai"
 const RESULTS_PATH = "/v2beta/results"
 const UPSCALE_MODEL = "creative"
@@ -21,7 +19,7 @@ const HEADERS = { accept: "application/json" }
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type StabilityStylePreset =
+export type StabilityStylePreset = OpenString<
   | "enhance"
   | "anime"
   | "photographic"
@@ -39,7 +37,7 @@ export type StabilityStylePreset =
   | "3d-model"
   | "pixel-art"
   | "tile-texture"
-  | (string & {})
+>
 
 export type StabilityImageOptions = {
   readonly negative_prompt?: string
@@ -84,36 +82,31 @@ const endpoint = (model: string) => (model.startsWith("sd3") ? "sd3" : model)
 
 const RESERVED_FORM_FIELDS = new Set(["image", "prompt", "mode", "model"])
 
-const unsupported = (route: string, operation: string, message: string) =>
-  ProviderShared.unsupportedOperation({ operation, provider: PROVIDER, route, message })
-
 const form = Effect.fn("StabilityImages.form")(function* (
-  route: string,
+  identity: MediaProtocol.Identity,
   fields: Record<string, unknown>,
   native: Record<string, unknown> | undefined,
   source: Request["images"],
 ) {
-  if ((source?.length ?? 0) > 1) return yield* unsupported(route, "media.images", `${NAME} takes one source image`)
+  if ((source?.length ?? 0) > 1)
+    return yield* identity.unsupported("media.images", `${identity.name} takes one source image`)
   const body = new FormData()
-  const overlay = Object.entries(native ?? {}).filter(([key]) => !RESERVED_FORM_FIELDS.has(key))
-  Object.entries(mergeJsonRecords(fields, Object.fromEntries(overlay)) ?? {}).forEach(([key, value]) =>
-    body.append(key, typeof value === "string" ? value : ProviderShared.encodeJson(value)),
-  )
+  MediaInput.appendFields(body, fields, { overlay: native, reserved: RESERVED_FORM_FIELDS })
   const image = source?.[0]
   if (image !== undefined)
-    body.append("image", MediaInput.blob(yield* MediaInput.inlineBytes(route, image), image.mediaType), "image")
+    body.append("image", MediaInput.blob(yield* MediaInput.inlineBytes(identity.id, image), image.mediaType), "image")
   return MediaProtocol.multipart(body)
 })
 
 const fromRequest = Effect.fn("StabilityImages.fromRequest")(function* (request: Request) {
   if (request.n !== undefined && request.n > 1)
-    return yield* unsupported(ADAPTER, "media.n", `${NAME} generates one image per request; call it once per image`)
+    return yield* route.unsupported("media.n", `${route.name} generates one image per request; call it once per image`)
   const target = endpoint(request.model.id)
   const edit = (request.images?.length ?? 0) > 0
   if (edit && target === "core")
-    return yield* unsupported(ADAPTER, "media.images", `${NAME} core is text-to-image only; use ultra or sd3.5-*`)
+    return yield* route.unsupported("media.images", `${route.name} core is text-to-image only; use ultra or sd3.5-*`)
   return yield* form(
-    ADAPTER,
+    route,
     {
       prompt: request.prompt,
       aspect_ratio: request.aspectRatio,
@@ -129,9 +122,9 @@ const fromRequest = Effect.fn("StabilityImages.fromRequest")(function* (request:
 
 const fromUpscaleRequest = Effect.fn("StabilityImages.fromUpscaleRequest")(function* (request: UpscaleRequest) {
   if ((request.images?.length ?? 0) === 0)
-    return yield* ProviderShared.invalidRequest(`${NAME} upscale requires the source image in images`)
+    return yield* ProviderShared.invalidRequest(`${upscaleRoute.name} upscale requires the source image in images`)
   return yield* form(
-    UPSCALE_ADAPTER,
+    upscaleRoute,
     { prompt: request.prompt, seed: request.seed, output_format: request.format },
     mergeJsonRecords(request.providerOptions, request.http?.body),
     request.images,
@@ -142,29 +135,29 @@ const fromUpscaleRequest = Effect.fn("StabilityImages.fromUpscaleRequest")(funct
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeImageDocument = (route: string) => {
-  const decode = MediaProtocol.decodeJson(route, NAME, ImageDocument)
+const decodeImageDocument = (identity: MediaProtocol.Identity) => {
+  const decode = identity.decodeJson(ImageDocument)
   return Effect.fn("StabilityImages.decodeImage")(function* (response: HttpClientResponse.HttpClientResponse) {
     const output = yield* decode(response)
     const document = output.value
     const data = document.image ?? document.result
-    if (data === undefined) return yield* output.invalid(`${NAME} returned no image`)
-    const image = yield* MediaInput.decodedAsset(output.invalid, `${NAME} result`, data, undefined)
+    if (data === undefined) return yield* output.invalid(`${identity.name} returned no image`)
+    const image = yield* MediaInput.decodedAsset(output.invalid, `${identity.name} result`, data, undefined)
     return new ImageResponse({
       images: [image],
       notices:
         document.finish_reason === "CONTENT_FILTERED"
-          ? [{ type: "moderated", message: `${NAME} blurred the image for violating its content policy` }]
+          ? [{ type: "moderated", message: `${identity.name} blurred the image for violating its content policy` }]
           : undefined,
       providerMetadata: { stability: { seed: document.seed, finishReason: document.finish_reason } },
     })
   })
 }
 
-const decodeResponse = decodeImageDocument(ADAPTER)
-const decodeUpscaleImage = decodeImageDocument(UPSCALE_ADAPTER)
+const decodeResponse = decodeImageDocument(route)
+const decodeUpscaleImage = decodeImageDocument(upscaleRoute)
 
-const decodeStart = MediaProtocol.decodeStarted(UPSCALE_ADAPTER, NAME, Started, (value) => ({
+const decodeStart = upscaleRoute.decodeStarted(Started, (value) => ({
   token: { id: value.id },
   snapshot: { id: value.id, status: "queued" },
 }))
@@ -181,8 +174,8 @@ const decodeUpscaleResult = Effect.fn("StabilityImages.decodeUpscaleResult")(fun
   context: MediaProtocol.PollContext<Token>,
 ) {
   if (response.status === 202) {
-    const output = yield* MediaProtocol.text(UPSCALE_ADAPTER, NAME, response)
-    return yield* output.invalid(`${NAME} upscale ${context.token.id} has not finished`)
+    const output = yield* upscaleRoute.text(response)
+    return yield* output.invalid(`${upscaleRoute.name} upscale ${context.token.id} has not finished`)
   }
   return yield* decodeUpscaleImage(response)
 })
@@ -191,17 +184,13 @@ const decodeUpscaleResult = Effect.fn("StabilityImages.decodeUpscaleResult")(fun
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.inline<Request, ImageResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.inline<Request, ImageResponse>(route, {
   unsupported: ["size", "mask"],
   body: { from: fromRequest },
   response: { decode: decodeResponse },
 })
 
-export const upscaleProtocol = MediaProtocol.queued<UpscaleRequest, ImageResponse, Token>({
-  id: UPSCALE_ADAPTER,
-  name: NAME,
+export const upscaleProtocol = MediaProtocol.queued<UpscaleRequest, ImageResponse, Token>(upscaleRoute, {
   token: Token,
   unsupported: ["n", "size", "aspectRatio", "mask"],
   start: { body: { from: fromUpscaleRequest }, decode: decodeStart },
@@ -212,8 +201,6 @@ export const upscaleProtocol = MediaProtocol.queued<UpscaleRequest, ImageRespons
 export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<StabilityImageOptions>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       headers: HEADERS,
@@ -225,8 +212,6 @@ export const model = (input: MediaRoute.ModelInput) =>
 export const upscaleModel = (input: Omit<MediaRoute.ModelInput, "id">) =>
   ImageModel.fromRoute<StabilityUpscaleOptions, Token>(
     {
-      id: UPSCALE_ADAPTER,
-      provider: PROVIDER,
       protocol: upscaleProtocol,
       baseURL: DEFAULT_BASE_URL,
       headers: HEADERS,

packages/ai/src/protocols/utils/fal-queue.ts

@@ -41,25 +41,24 @@ const STATUS = {
 export const mediaUrl = (asset: Media.Asset, name: string) =>
   ProviderShared.mediaReference(asset, undefined, name).pipe(Effect.map((reference) => reference.value))
 
-export const protocol = <Request, Response>(input: {
-  readonly id: string
-  readonly name: string
-  readonly unsupported?: ReadonlyArray<keyof Request & string>
-  readonly from: (request: Request) => Effect.Effect<MediaProtocol.Body, AIError>
-  readonly decodeResult: (
-    response: HttpClientResponse.HttpClientResponse,
-    context: MediaProtocol.PollContext<Token>,
-  ) => Effect.Effect<Response, AIError>
-}) => {
-  const decodeQueueStatus = MediaProtocol.decodeJson(input.id, input.name, QueueStatus)
-  return MediaProtocol.queued<Request, Response, Token>({
-    id: input.id,
-    name: input.name,
+export const protocol = <Request, Response>(
+  route: MediaProtocol.Identity,
+  input: {
+    readonly unsupported?: ReadonlyArray<keyof Request & string>
+    readonly from: (request: Request) => Effect.Effect<MediaProtocol.Body, AIError>
+    readonly decodeResult: (
+      response: HttpClientResponse.HttpClientResponse,
+      context: MediaProtocol.PollContext<Token>,
+    ) => Effect.Effect<Response, AIError>
+  },
+) => {
+  const decodeQueueStatus = route.decodeJson(QueueStatus)
+  return MediaProtocol.queued<Request, Response, Token>(route, {
     token: Token,
     unsupported: input.unsupported,
     start: {
       body: { from: input.from },
-      decode: MediaProtocol.decodeStarted(input.id, input.name, StartResponse, (value) => ({
+      decode: route.decodeStarted(StartResponse, (value) => ({
         token: {
           requestID: value.request_id,
           statusURL: value.status_url,

packages/ai/src/protocols/utils/media-input.ts

@@ -1,7 +1,8 @@
 import { Effect, Encoding } from "effect"
 import { Media } from "../../media.js"
 import type { MediaProtocol } from "../../route/media-protocol.js"
-import type { AIError, ProviderID } from "../../schema/index.js"
+import { mergeJsonRecords, type AIError, type ProviderID } from "../../schema/index.js"
+import { encodeJson } from "../../utils/json.js"
 import { ProviderShared } from "../shared.js"
 
 /** Owned bytes for multipart uploads; decodes `base64` sources and rejects remote sources. */
@@ -56,4 +57,38 @@ export const decodedAsset = (
     Effect.map((bytes) => Media.bytes(bytes, mediaType, options)),
   )
 
+/** One image of an OpenAI-shaped `data` array, which carries either `b64_json` or a `url`. */
+export const imageOutput = (
+  invalid: (message: string, cause?: unknown) => AIError,
+  label: string,
+  item: { readonly b64_json?: string | null; readonly url?: string | null },
+  mediaType: string | undefined,
+  options?: Media.AssetOptions,
+) => {
+  if (item.b64_json) return decodedAsset(invalid, label, item.b64_json, mediaType, options)
+  if (item.url) return Effect.succeed(Media.url(item.url, { ...options, mediaType }))
+  return Effect.fail(invalid(`${label} has neither image data nor a URL`))
+}
+
+/**
+ * Append multipart text fields: strings as-is, other values as JSON, or arrays as repeated `key[]` parts with
+ * `repeatArrays`. `overlay` keys in `reserved` are dropped so `http.body` cannot replace route-owned fields.
+ */
+export const appendFields = (
+  form: FormData,
+  fields: Record<string, unknown>,
+  options: {
+    readonly overlay?: Record<string, unknown>
+    readonly reserved: ReadonlySet<string>
+    readonly repeatArrays?: true
+  },
+) => {
+  const overlay = Object.entries(options.overlay ?? {}).filter(([key]) => !options.reserved.has(key))
+  Object.entries(mergeJsonRecords(fields, Object.fromEntries(overlay)) ?? {}).forEach(([key, value]) => {
+    if (Array.isArray(value) && options.repeatArrays)
+      return value.forEach((item) => form.append(`${key}[]`, String(item)))
+    form.append(key, typeof value === "string" ? value : encodeJson(value))
+  })
+}
+
 export * as MediaInput from "./media-input.js"

packages/ai/src/protocols/utils/meta-image.ts

@@ -1,11 +0,0 @@
-// Responses image items can omit output_format, including when PNG/JPEG was requested.
-export const mediaType = (data: Uint8Array, format?: string) => {
-  if (format !== undefined) return `image/${format}`
-  if (data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71) return "image/png"
-  if (data[0] === 255 && data[1] === 216 && data[2] === 255) return "image/jpeg"
-  if (new TextDecoder().decode(data.slice(0, 4)) === "RIFF" && new TextDecoder().decode(data.slice(8, 12)) === "WEBP")
-    return "image/webp"
-  return "application/octet-stream"
-}
-
-export * as MetaImage from "./meta-image.js"

packages/ai/src/protocols/utils/openai-image.ts

@@ -1,20 +0,0 @@
-import { Schema } from "effect"
-
-const dimensions = (value: string) => {
-  const match = /^(\d+)x(\d+)$/.exec(value)
-  if (!match) return undefined
-  return { width: Number(match[1]), height: Number(match[2]) }
-}
-
-export const Size = Schema.String.check(
-  Schema.makeFilter((value) => {
-    if (value === "auto") return undefined
-    const parsed = dimensions(value)
-    if (!parsed) return "image size must be `auto` or `{width}x{height}`"
-    return parsed.width > 0 && parsed.height > 0 ? undefined : "image dimensions must be positive integers"
-  }),
-)
-
-export const OpenAIImage = {
-  Size,
-} as const

packages/ai/src/protocols/utils/responses-checkpoint.ts

@@ -1,7 +1,7 @@
 import { Effect, Schema, Stream } from "effect"
 import { Route, type RouteBody, type TriggerCompactOperation } from "../../route/client.js"
 import { Protocol } from "../../route/protocol.js"
-import { CompactionCheckpointResponse, HttpOptions, LLMEvent, LLMRequest } from "../../schema/index.js"
+import { CompactionCheckpointResponse, LLMEvent, LLMRequest } from "../../schema/index.js"
 import { OpenResponses } from "../open-responses.js"
 import { ProviderShared } from "../shared.js"
 
@@ -109,12 +109,8 @@ export const make = <Body>(body: RouteBody<Body>): TriggerCompactOperation =>
       transport: source.transport,
     })
     const native = yield* body.from(request)
-    // The body builder already applied and validated overlays. Do not let transport reapply them.
-    const preparedRequest = LLMRequest.update(request, {
-      http: request.http === undefined ? undefined : new HttpOptions({ ...request.http, body: undefined }),
-    })
-    const prepared = yield* route.prepareTransport(native, preparedRequest, options)
-    yield* route.streamPrepared(prepared, preparedRequest, { http: executor }, options).pipe(Stream.runDrain)
+    const prepared = yield* route.prepareTransport(native, request, options)
+    yield* route.streamPrepared(prepared, request, { http: executor }, options).pipe(Stream.runDrain)
     if (!result) return yield* ProviderShared.eventError(source.id, "Compaction response ended without a checkpoint")
     return result
   })

packages/ai/src/protocols/utils/responses-compaction.ts

@@ -19,12 +19,18 @@ import { OpenResponses } from "../open-responses.js"
 import { JsonObject, optionalNull, ProviderShared } from "../shared.js"
 import { Media } from "../../media.js"
 
+// /compact has a smaller wire contract than /responses; keep the request controls it accepts.
 const Body = Schema.Struct({
   model: Schema.String,
   input: Schema.Array(Schema.Unknown),
   instructions: optionalNull(Schema.String),
   previous_response_id: optionalNull(Schema.String),
   service_tier: optionalNull(Schema.String),
+  reasoning: Schema.optional(JsonObject),
+  text: Schema.optional(JsonObject),
+  include: OpenResponses.coreFields.include,
+  parallel_tool_calls: OpenResponses.coreFields.parallel_tool_calls,
+  tools: Schema.optional(Schema.Array(JsonObject)),
   prompt_cache_key: optionalNull(Schema.String),
   prompt_cache_retention: optionalNull(Schema.String),
   prompt_cache_options: optionalNull(
@@ -74,17 +80,27 @@ const Response = Schema.Struct({
   usage: Schema.optional(Schema.StructWithRest(OpenResponses.OpenResponsesUsage, [JsonObject])),
 })
 
-export const make = (adapter: OpenResponses.ProviderAdapter): CompactOperation =>
+export const make = (
+  adapter: OpenResponses.ProviderAdapter,
+  lowerTools: (request: LLMRequest) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, AIError>,
+): CompactOperation =>
   Effect.fn("ResponsesCompaction.execute")(function* (request, executor, options) {
     const route = request.model.route
     // The standalone compaction endpoint rejects histories containing configuration updates.
     const native = yield* OpenResponses.lowerConversation(stripEffortUpdates(request), adapter)
+    const generation = OpenResponses.lowerGeneration(request)
+    const tools = request.tools.length === 0 ? undefined : yield* lowerTools(request)
     const body = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Body))(
       mergeJsonRecords(
         {
           ...native,
-          service_tier: request.providerOptions?.serviceTier,
-          prompt_cache_key: ProviderShared.promptCacheKey(request),
+          service_tier: generation.service_tier,
+          reasoning: generation.reasoning,
+          text: generation.text,
+          include: generation.include,
+          parallel_tool_calls: generation.parallel_tool_calls,
+          tools,
+          prompt_cache_key: generation.prompt_cache_key,
         },
         request.http?.body,
       ),

packages/ai/src/protocols/utils/speech-stream.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { Media } from "../../media.js"
-import { MediaProtocol } from "../../route/media-protocol.js"
-import type { AIError, MediaUsage, ProviderID, ProviderMetadata } from "../../schema/index.js"
+import type { MediaProtocol } from "../../route/media-protocol.js"
+import type { AIError, MediaUsage, ProviderMetadata } from "../../schema/index.js"
 import {
   SpeechAudioDeltaEvent,
   SpeechFinishEvent,
@@ -10,7 +10,6 @@ import {
   type SpeechVoice,
 } from "../../speech.js"
 import { concatBytes } from "../../utils/bytes.js"
-import { ProviderShared } from "../shared.js"
 
 export interface Audio {
   /** Appended in place: the route creates fresh state for each response through `initial`. */
@@ -78,12 +77,9 @@ export const sampleRate = (mediaType: string | undefined) => {
   return rate === undefined ? undefined : Number(rate)
 }
 
-export const unsupportedFormat = (provider: ProviderID, route: string, message: string) =>
-  ProviderShared.unsupportedOperation({ operation: "media.format", provider, route, message })
-
 /** A declared `mediaType` wins over sniffing: headerless PCM can start with bytes that look like an MPEG frame sync. */
 export const finish = (
-  route: string,
+  route: MediaProtocol.Identity,
   state: Audio,
   output: {
     readonly mediaType: string | undefined
@@ -95,10 +91,7 @@ export const finish = (
 ): Effect.Effect<ReadonlyArray<SpeechEvent>, AIError> => {
   if (state.chunks.length === 0)
     return Effect.fail(
-      MediaProtocol.frameError(
-        route,
-        `The provider returned no audio${output.detail === undefined ? "" : ` (${output.detail})`}`,
-      ),
+      route.frameError(`The provider returned no audio${output.detail === undefined ? "" : ` (${output.detail})`}`),
     )
   return Effect.succeed([
     SpeechFinishEvent.make({

packages/ai/src/protocols/utils/tool-schema.ts

@@ -1,4 +1,4 @@
-import type { JsonSchema, LanguageModel, LanguageModelSanitizerCompatibility } from "../../schema/index.js"
+import { ToolDefinition, type JsonSchema, type LanguageModel, type LLMRequest } from "../../schema/index.js"
 import { isRecord } from "../../utils/record.js"
 import { GeminiJsonSchema } from "./gemini-json-schema.js"
 
@@ -53,29 +53,52 @@ const MODEL_NAMES = [
   [/kimi/i, "moonshot"],
 ] as const
 
-// An explicit `sanitizer` wins, and `none` opts out. Otherwise the protocol's own default
-// applies (the Gemini API always uses Gemini's rules), then the model name selects the family's rules
-// so models reached through gateways and OpenAI-compatible endpoints get the same handling.
-const modelCompatibility = (
-  schema: JsonSchema,
-  model: LanguageModel,
-  protocolDefault?: LanguageModelSanitizerCompatibility,
-): JsonSchema => {
-  switch (model.compatibility?.sanitizer ?? protocolDefault ?? MODEL_NAMES.find(([name]) => name.test(model.id))?.[1]) {
+// Tool arguments are always a JSON object, and most providers reject a tool schema whose root does not
+// declare `type: "object"`, such as `{}` or a bare `properties` map. Effect encodes an empty struct as
+// `anyOf` object or array; every object matches its bare object branch, so that `anyOf` is dropped.
+const objectRoot = (schema: JsonSchema): JsonSchema => {
+  if (schema.type !== undefined) return schema
+  if (
+    Array.isArray(schema.anyOf) &&
+    schema.anyOf.some((branch) => isRecord(branch) && branch.type === "object" && Object.keys(branch).length === 1)
+  )
+    return { type: "object", ...Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "anyOf")) }
+  return { type: "object", ...schema }
+}
+
+// Every tool schema gets an object root. Then an explicit `sanitizer` wins, and `none` opts out.
+// Otherwise the protocol's own default applies (the Gemini API always uses Gemini's rules), then the
+// model name selects the family's rules so models reached through gateways and OpenAI-compatible
+// endpoints get the same handling.
+const modelCompatibility = (schema: JsonSchema, model: LanguageModel): JsonSchema => {
+  const root = objectRoot(schema)
+  switch (
+    model.compatibility?.sanitizer ??
+    model.route.sanitizer ??
+    MODEL_NAMES.find(([name]) => name.test(model.id))?.[1]
+  ) {
     case "gemini":
-      return gemini(schema)
+      return gemini(root)
     case "moonshot":
-      return moonshot(schema)
+      return moonshot(root)
     case "none":
     case undefined:
-      return schema
+      return root
   }
 }
 
+// Applied once to every request before any protocol builds its body, including tools in namespaces.
+const tools = (entries: LLMRequest["tools"], model: LanguageModel): LLMRequest["tools"] =>
+  entries.map((tool) =>
+    tool.type === "tool"
+      ? new ToolDefinition({ ...tool, inputSchema: modelCompatibility(tool.inputSchema, model) })
+      : { ...tool, tools: tools(tool.tools, model) },
+  )
+
 export const ToolSchemaProjection = {
   gemini,
-  modelCompatibility,
   moonshot,
   openAI,
   responses,
+  tools,
 } as const

packages/ai/src/protocols/xai-images.ts

@@ -4,13 +4,11 @@ import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 import { MediaInput } from "./utils/media-input.js"
 
-const ADAPTER = "xai-images"
-const NAME = "xAI Images"
-const PROVIDER = ProviderID.make("xai")
+const route = MediaProtocol.identity({ id: "xai-images", name: "xAI Images", provider: "xai" })
 export const DEFAULT_BASE_URL = "https://api.x.ai/v1"
 export const PATH = "/images/generations"
 export const EDIT_PATH = "/images/edits"
@@ -19,13 +17,11 @@ export const EDIT_PATH = "/images/edits"
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type XAIImageString<Known extends string> = Known | (string & {})
-
 /** Provider-native options. Common fields (`n`, `aspectRatio`, `images`) live on the request. */
 export type XAIImageOptions = {
-  readonly resolution?: XAIImageString<"1k" | "2k">
-  readonly responseFormat?: XAIImageString<"url" | "b64_json">
-  readonly response_format?: XAIImageString<"url" | "b64_json">
+  readonly resolution?: OpenString<"1k" | "2k">
+  readonly responseFormat?: OpenString<"url" | "b64_json">
+  readonly response_format?: OpenString<"url" | "b64_json">
 } & Record<string, unknown>
 
 export type Request = ImageRequestFor<XAIImageOptions>
@@ -59,7 +55,7 @@ const nativeOptions = (options: XAIImageOptions | undefined) => {
 const isEdit = (request: Request) => (request.images?.length ?? 0) > 0
 
 const reference = (asset: Media.Asset) =>
-  ProviderShared.mediaReference(asset, PROVIDER, NAME).pipe(
+  ProviderShared.mediaReference(asset, route.provider, route.name).pipe(
     Effect.map((item) =>
       item.type === "ref" ? { file_id: item.value } : { url: item.value, type: "image_url" as const },
     ),
@@ -88,31 +84,22 @@ const fromRequest = Effect.fn("XAIImages.fromRequest")(function* (request: Reque
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
+const decodeDocument = route.decodeJson(XAIImageResponse)
+
 const decodeResponse = Effect.fn("XAIImages.decodeResponse")(function* (
   response: HttpClientResponse.HttpClientResponse,
 ) {
-  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, XAIImageResponse)(response)
+  const output = yield* decodeDocument(response)
   const decoded = output.value
-  const images = yield* Effect.forEach(decoded.data, (item, index) => {
-    const providerMetadata =
-      item.revised_prompt === undefined || item.revised_prompt === null
-        ? undefined
-        : { xai: { revisedPrompt: item.revised_prompt } }
-    if (item.b64_json)
-      return MediaInput.decodedAsset(
-        output.invalid,
-        `${NAME} result ${index}`,
-        item.b64_json,
-        item.mime_type ?? undefined,
-        {
-          providerMetadata,
-        },
-      )
-    if (item.url)
-      return Effect.succeed(Media.url(item.url, { mediaType: item.mime_type ?? undefined, providerMetadata }))
-    return Effect.fail(output.invalid(`${NAME} result ${index} has neither image data nor a URL`))
-  })
-  if (images.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  const images = yield* Effect.forEach(decoded.data, (item, index) =>
+    MediaInput.imageOutput(output.invalid, `${route.name} result ${index}`, item, item.mime_type ?? undefined, {
+      providerMetadata:
+        item.revised_prompt === undefined || item.revised_prompt === null
+          ? undefined
+          : { xai: { revisedPrompt: item.revised_prompt } },
+    }),
+  )
+  if (images.length === 0) return yield* output.invalid(`${route.name} returned no images`)
   const usage = ProviderShared.isRecord(decoded.usage) ? decoded.usage : undefined
   // xAI reports image counts rather than tokens, seconds, or credits; the raw record stays in provider metadata.
   return new ImageResponse({
@@ -125,9 +112,7 @@ const decodeResponse = Effect.fn("XAIImages.decodeResponse")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.inline<Request, ImageResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.inline<Request, ImageResponse>(route, {
   unsupported: ["mask", "size", "seed", "format"],
   body: { from: fromRequest },
   response: { decode: decodeResponse },
@@ -135,13 +120,7 @@ export const protocol = MediaProtocol.inline<Request, ImageResponse>({
 
 export const model = (input: MediaRoute.ModelInput) =>
   ImageModel.fromRoute<XAIImageOptions>(
-    {
-      id: ADAPTER,
-      provider: PROVIDER,
-      protocol,
-      baseURL: DEFAULT_BASE_URL,
-      path: ({ request }) => (isEdit(request) ? EDIT_PATH : PATH),
-    },
+    { protocol, baseURL: DEFAULT_BASE_URL, path: ({ request }) => (isEdit(request) ? EDIT_PATH : PATH) },
     input,
   )
 

packages/ai/src/protocols/xai-responses.ts

@@ -50,7 +50,8 @@ const fromRequest = Effect.fn("XAIResponses.fromRequest")(function* (request: LL
       operation: "in-band-compaction",
       provider: request.model.provider,
       route: request.model.route.id,
-      message: "xAI requires explicit compaction through LLMClient.compact; automatic context management is not supported",
+      message:
+        "xAI requires explicit compaction through LLMClient.compact; automatic context management is not supported",
     })
   return yield* decodeBody(yield* OpenResponses.fromRequestWithAdapter(request, adapter))
 })
@@ -93,6 +94,8 @@ export const protocol = Protocol.make({
   },
 })
 
-export const compact = ResponsesCompaction.make(adapter)
+export const compact = ResponsesCompaction.make(adapter, (request) =>
+  OpenResponses.lowerTools(ProviderShared.flattenTools(request.tools), adapter),
+)
 
 export * as XAIResponses from "./xai-responses.js"

packages/ai/src/protocols/xai-video.ts

@@ -4,13 +4,11 @@ import type { Status } from "../generation.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords } from "../schema/index.js"
 import { VideoModel, VideoResponse, type VideoRequestFor } from "../video.js"
 import { ProviderShared, optionalNull } from "./shared.js"
 
-const ADAPTER = "xai-video"
-const NAME = "xAI Video"
-const PROVIDER = ProviderID.make("xai")
+const route = MediaProtocol.identity({ id: "xai-video", name: "xAI Video", provider: "xai" })
 export const DEFAULT_BASE_URL = "https://api.x.ai/v1"
 export const PATH = "/videos/generations"
 export const EDIT_PATH = "/videos/edits"
@@ -72,7 +70,7 @@ const STATUS = {
 // ---------------------------------------------------------------------------
 
 const mediaInput = (asset: Media.Asset) =>
-  ProviderShared.mediaReference(asset, PROVIDER, NAME).pipe(
+  ProviderShared.mediaReference(asset, route.provider, route.name).pipe(
     Effect.map((reference) => (reference.type === "ref" ? { file_id: reference.value } : { url: reference.value })),
   )
 
@@ -111,7 +109,7 @@ const fromRequest = Effect.fn("XAIVideo.fromRequest")(function* (request: Reques
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
-const decodeStart = MediaProtocol.decodeStarted(ADAPTER, NAME, StartResponse, (value) => ({
+const decodeStart = route.decodeStarted(StartResponse, (value) => ({
   token: { requestID: value.request_id },
   snapshot: { id: value.request_id, status: "running" },
 }))
@@ -120,7 +118,7 @@ const decodeStart = MediaProtocol.decodeStarted(ADAPTER, NAME, StartResponse, (v
 const fraction = (progress: number | null | undefined) =>
   progress !== undefined && progress !== null && progress >= 0 && progress <= 100 ? progress / 100 : undefined
 
-const decodeVideoStatus = MediaProtocol.decodeJson(ADAPTER, NAME, VideoStatus)
+const decodeVideoStatus = route.decodeJson(VideoStatus)
 
 const decodeStatus = Effect.fn("XAIVideo.decodeStatus")(function* (
   response: HttpClientResponse.HttpClientResponse,
@@ -138,26 +136,27 @@ const decodeResult = Effect.fn("XAIVideo.decodeResult")(function* (
   const output = yield* decodeVideoStatus(response)
   const decoded = output.value
   const status = yield* MediaProtocol.status(STATUS, decoded.status, output)
-  if (status === "running") return yield* output.invalid(`${NAME} request ${context.token.requestID} has not finished`)
+  if (status === "running")
+    return yield* output.invalid(`${route.name} request ${context.token.requestID} has not finished`)
   if (status === "failed") {
     const code = decoded.error?.code ?? undefined
     const message = decoded.error?.message ?? undefined
     return yield* output.ended(
       "failed",
-      `${NAME} generation failed${code === undefined ? "" : ` (${code})`}${message === undefined ? "" : `: ${message}`}`,
+      `${route.name} generation failed${code === undefined ? "" : ` (${code})`}${message === undefined ? "" : `: ${message}`}`,
     )
   }
   if (status !== "completed")
-    return yield* output.ended("expired", `${NAME} request ${context.token.requestID} expired`)
+    return yield* output.ended("expired", `${route.name} request ${context.token.requestID} expired`)
   // `respect_moderation: false` marks a filtered result; a URL may still be present, so report it as a notice.
   const notices =
     decoded.video?.respect_moderation === false
-      ? [{ type: "moderated" as const, message: `${NAME} flagged the generated video for moderation` }]
+      ? [{ type: "moderated" as const, message: `${route.name} flagged the generated video for moderation` }]
       : undefined
   const url = decoded.video?.url ?? undefined
   if (url === undefined && notices !== undefined)
-    return yield* output.contentPolicy(`${NAME} withheld the video for moderation`)
-  if (url === undefined) return yield* output.invalid(`${NAME} completed without a video URL`)
+    return yield* output.contentPolicy(`${route.name} withheld the video for moderation`)
+  if (url === undefined) return yield* output.invalid(`${route.name} completed without a video URL`)
   const duration = decoded.video?.duration ?? undefined
   return new VideoResponse({
     videos: [
@@ -177,9 +176,7 @@ const decodeResult = Effect.fn("XAIVideo.decodeResult")(function* (
 
 const statusPath = (token: Token) => `${STATUS_PATH}/${token.requestID}`
 
-export const protocol = MediaProtocol.queued<Request, VideoResponse, Token>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.queued<Request, VideoResponse, Token>(route, {
   token: Token,
   unsupported: ["n", "seed", "negativePrompt"],
   start: { body: { from: fromRequest }, decode: decodeStart },
@@ -196,8 +193,6 @@ const startPath = (request: Request) => {
 export const model = (input: MediaRoute.ModelInput) =>
   VideoModel.fromRoute<XAIVideoOptions, Token>(
     {
-      id: ADAPTER,
-      provider: PROVIDER,
       protocol,
       baseURL: DEFAULT_BASE_URL,
       path: ({ request }) => startPath(request),

packages/ai/src/protocols/zai-images.ts

@@ -4,11 +4,9 @@ import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
 import { Media } from "../media.js"
 import { MediaProtocol } from "../route/media-protocol.js"
 import { MediaRoute } from "../route/media.js"
-import { ProviderID, mergeJsonRecords } from "../schema/index.js"
+import { mergeJsonRecords, type OpenString } from "../schema/index.js"
 
-const ADAPTER = "zai-images"
-const NAME = "Z.ai Images"
-const PROVIDER = ProviderID.make("zai")
+const route = MediaProtocol.identity({ id: "zai-images", name: "Z.ai Images", provider: "zai" })
 export const DEFAULT_BASE_URL = "https://api.z.ai/api/paas/v4"
 export const PATH = "/images/generations"
 
@@ -16,11 +14,9 @@ export const PATH = "/images/generations"
 // 1. Public model input
 // ---------------------------------------------------------------------------
 
-export type ZAIImageString<Known extends string> = Known | (string & {})
-
 /** Provider-native options. The common `size` field lives on the request. */
 export type ZAIImageOptions = {
-  readonly quality?: ZAIImageString<"hd" | "standard">
+  readonly quality?: OpenString<"hd" | "standard">
   readonly userID?: string
 } & Record<string, unknown>
 
@@ -69,12 +65,14 @@ const fromRequest = Effect.fn("ZAIImages.fromRequest")(function* (request: Reque
 // 6. Response decoding
 // ---------------------------------------------------------------------------
 
+const decodeDocument = route.decodeJson(ZAIImageResponse)
+
 const decodeResponse = Effect.fn("ZAIImages.decodeResponse")(function* (
   response: HttpClientResponse.HttpClientResponse,
 ) {
-  const output = yield* MediaProtocol.decodeJson(ADAPTER, NAME, ZAIImageResponse)(response)
+  const output = yield* decodeDocument(response)
   const decoded = output.value
-  if (decoded.data.length === 0) return yield* output.invalid(`${NAME} returned no images`)
+  if (decoded.data.length === 0) return yield* output.invalid(`${route.name} returned no images`)
   const filters = decoded.content_filter ?? []
   return new ImageResponse({
     // Z.ai returns only URLs and no content type; the media type resolves when the asset is materialized.
@@ -85,7 +83,7 @@ const decodeResponse = Effect.fn("ZAIImages.decodeResponse")(function* (
         ? undefined
         : filters.map((filter) => ({
             type: "moderated" as const,
-            message: `${NAME} applied a content filter${filter.role === undefined ? "" : ` for ${filter.role}`}${
+            message: `${route.name} applied a content filter${filter.role === undefined ? "" : ` for ${filter.role}`}${
               filter.level === undefined ? "" : ` at level ${filter.level}`
             }`,
             providerMetadata: { zai: filter },
@@ -105,19 +103,14 @@ const decodeResponse = Effect.fn("ZAIImages.decodeResponse")(function* (
 // 7. Protocol and route
 // ---------------------------------------------------------------------------
 
-export const protocol = MediaProtocol.inline<Request, ImageResponse>({
-  id: ADAPTER,
-  name: NAME,
+export const protocol = MediaProtocol.inline<Request, ImageResponse>(route, {
   unsupported: ["images", "mask", "n", "aspectRatio", "seed", "format"],
   body: { from: fromRequest },
   response: { decode: decodeResponse },
 })
 
 export const model = (input: MediaRoute.ModelInput) =>
-  ImageModel.fromRoute<ZAIImageOptions>(
-    { id: ADAPTER, provider: PROVIDER, protocol, baseURL: DEFAULT_BASE_URL, path: PATH },
-    input,
-  )
+  ImageModel.fromRoute<ZAIImageOptions>({ protocol, baseURL: DEFAULT_BASE_URL, path: PATH }, input)
 
 export const ZAIImages = {
   protocol,

packages/ai/src/provider-error.ts

@@ -80,7 +80,13 @@ const SERVER_CODES = new Set([
   "slow_down",
   "serviceunavailableexception",
 ])
-const INVALID_REQUEST_CODES = new Set(["invalid_prompt", "invalid_request_error", "validationexception"])
+// `invalid_request` is the Vercel AI Gateway's code for an upstream request rejection.
+const INVALID_REQUEST_CODES = new Set([
+  "invalid_prompt",
+  "invalid_request",
+  "invalid_request_error",
+  "validationexception",
+])
 // Azure OpenAI reports `content_filter` with `innererror.code` ResponsibleAIPolicyViolation.
 // OpenRouter tags provider failures with a typed `error_type`; its Responses skin also
 // emits `image_content_policy_violation` as the native code.

packages/ai/src/providers/amazon-bedrock.ts

@@ -31,6 +31,7 @@ export interface Settings extends ProviderPackage.Settings {
   readonly profile?: string
   readonly region?: string
   readonly topP?: number
+  readonly thinking?: BedrockConverse.OptionsInput["thinking"]
 }
 export const routes = [BedrockConverse.route]
 
@@ -71,6 +72,7 @@ export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, se
     generation: settings.topP === undefined ? undefined : { topP: settings.topP },
     headers: settings.headers === undefined ? undefined : { ...settings.headers },
     http: settings.body === undefined ? undefined : { body: { ...settings.body } },
+    providerOptions: settings.thinking === undefined ? undefined : { thinking: settings.thinking },
     profile: settings.profile,
     region: settings.region,
   }).model(modelID)

packages/ai/src/providers/assemblyai.ts

@@ -1,12 +1,12 @@
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { AssemblyAITranscription, DEFAULT_BASE_URL } from "../protocols/assemblyai-transcription.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { AssemblyAITranscription } from "../protocols/assemblyai-transcription.js"
 
 export type { AssemblyAITranscriptionOptions } from "../protocols/assemblyai-transcription.js"
 
 export const id = ProviderID.make("assemblyai")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   /** `https://api.eu.assemblyai.com` for the EU region. */
@@ -24,14 +24,8 @@ const auth = (options: ProviderAuthOption<"optional">) => {
 }
 
 export const configure = (input: Config = {}) => {
-  const transcription = (modelID: string | ModelID) =>
-    AssemblyAITranscription.model({
-      id: modelID,
-      auth: auth(input),
-      baseURL: input.baseURL ?? baseURL,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, auth(input))
+  const transcription = (modelID: string | ModelID) => AssemblyAITranscription.model({ ...media, id: modelID })
   return {
     id,
     transcription,

packages/ai/src/providers/azure.ts

@@ -1,11 +1,11 @@
 import { Auth } from "../route/auth.js"
 import { type AtLeastOne, type ProviderAuthOption } from "../route/auth-options.js"
 import type { Route, RouteDefaultsInput, CompactionOperations } from "../route/client.js"
+import { Endpoint } from "../route/endpoint.js"
 import type { ProviderPackage } from "../provider-package.js"
 import { ProviderConfigurationError, ProviderID, type ModelID } from "../schema/index.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
 import * as OpenAIResponses from "../protocols/openai-responses.js"
-import { ProviderShared } from "../protocols/shared.js"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options.js"
 
 export const id = ProviderID.make("azure")
@@ -108,7 +108,7 @@ const configuredRoute = <Body, Prepared, Compact extends CompactionOperations |
   })
 
 function endpoint(input: Config, modelID: string | ModelID) {
-  const baseURL = ProviderShared.trimBaseUrl(input.baseURL ?? resourceBaseURL(input.resourceName!))
+  const baseURL = Endpoint.trimBaseUrl(input.baseURL ?? resourceBaseURL(input.resourceName!))
   const query = { "api-version": input.apiVersion ?? "v1", ...input.queryParams }
 
   if (input.useDeploymentBasedUrls) return { baseURL: `${baseURL}/deployments/${modelID}`, query }

packages/ai/src/providers/black-forest-labs.ts

@@ -1,12 +1,12 @@
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { BlackForestLabsImages, DEFAULT_BASE_URL } from "../protocols/bfl-images.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { BlackForestLabsImages } from "../protocols/bfl-images.js"
 
 export type { BlackForestLabsImageOptions } from "../protocols/bfl-images.js"
 
 export const id = ProviderID.make("black-forest-labs")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   /** `https://api.eu.bfl.ai` or `https://api.us.bfl.ai` pin inference to one region. */
@@ -23,14 +23,8 @@ const auth = (options: ProviderAuthOption<"optional">) => {
 }
 
 export const configure = (input: Config = {}) => {
-  const image = (modelID: string | ModelID) =>
-    BlackForestLabsImages.model({
-      id: modelID,
-      auth: auth(input),
-      baseURL: input.baseURL ?? baseURL,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, auth(input))
+  const image = (modelID: string | ModelID) => BlackForestLabsImages.model({ ...media, id: modelID })
   return {
     id,
     image,

packages/ai/src/providers/cartesia.ts

@@ -1,11 +1,11 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { CartesiaSpeech, DEFAULT_BASE_URL } from "../protocols/cartesia-speech.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { CartesiaSpeech } from "../protocols/cartesia-speech.js"
 
 export type { CartesiaEncoding, CartesiaSpeechOptions } from "../protocols/cartesia-speech.js"
 
 export const id = ProviderID.make("cartesia")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   readonly baseURL?: string
@@ -16,14 +16,8 @@ export type Config = ProviderAuthOption<"optional"> & {
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "CARTESIA_API_KEY")
 
 export const configure = (input: Config = {}) => {
-  const speech = (modelID: string | ModelID) =>
-    CartesiaSpeech.model({
-      id: modelID,
-      auth: auth(input),
-      baseURL: input.baseURL ?? baseURL,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, auth(input))
+  const speech = (modelID: string | ModelID) => CartesiaSpeech.model({ ...media, id: modelID })
   return {
     id,
     speech,

packages/ai/src/providers/deepgram.ts

@@ -1,14 +1,14 @@
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { DEFAULT_BASE_URL, DeepgramSpeech } from "../protocols/deepgram-speech.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { DeepgramSpeech } from "../protocols/deepgram-speech.js"
 import { DeepgramTranscription } from "../protocols/deepgram-transcription.js"
 
 export type { DeepgramEncoding, DeepgramSpeechOptions } from "../protocols/deepgram-speech.js"
 export type { DeepgramTranscriptionOptions } from "../protocols/deepgram-transcription.js"
 
 export const id = ProviderID.make("deepgram")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   readonly baseURL?: string
@@ -24,17 +24,11 @@ const auth = (options: ProviderAuthOption<"optional">) => {
 }
 
 export const configure = (input: Config = {}) => {
-  const media = (modelID: string | ModelID) => ({
-    id: modelID,
-    auth: auth(input),
-    baseURL: input.baseURL ?? baseURL,
-    headers: input.headers,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-  })
+  const media = MediaRoute.deployment(input, auth(input))
   return {
     id,
-    speech: (modelID: string | ModelID) => DeepgramSpeech.model(media(modelID)),
-    transcription: (modelID: string | ModelID) => DeepgramTranscription.model(media(modelID)),
+    speech: (modelID: string | ModelID) => DeepgramSpeech.model({ ...media, id: modelID }),
+    transcription: (modelID: string | ModelID) => DeepgramTranscription.model({ ...media, id: modelID }),
     configure,
   }
 }

packages/ai/src/providers/elevenlabs.ts

@@ -1,12 +1,12 @@
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { DEFAULT_BASE_URL, ElevenLabsSpeech } from "../protocols/elevenlabs-speech.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { ElevenLabsSpeech } from "../protocols/elevenlabs-speech.js"
 
 export type { ElevenLabsOutputFormat, ElevenLabsSpeechOptions } from "../protocols/elevenlabs-speech.js"
 
 export const id = ProviderID.make("elevenlabs")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   readonly baseURL?: string
@@ -22,14 +22,8 @@ const auth = (options: ProviderAuthOption<"optional">) => {
 }
 
 export const configure = (input: Config = {}) => {
-  const speech = (modelID: string | ModelID) =>
-    ElevenLabsSpeech.model({
-      id: modelID,
-      auth: auth(input),
-      baseURL: input.baseURL ?? baseURL,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, auth(input))
+  const speech = (modelID: string | ModelID) => ElevenLabsSpeech.model({ ...media, id: modelID })
   return {
     id,
     speech,

packages/ai/src/providers/fal.ts

@@ -1,15 +1,14 @@
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
 import { FalImages } from "../protocols/fal-images.js"
 import { FalVideo } from "../protocols/fal-video.js"
-import { FalQueue } from "../protocols/utils/fal-queue.js"
 
 export type { FalImageOptions } from "../protocols/fal-images.js"
 export type { FalVideoOptions } from "../protocols/fal-video.js"
 
 export const id = ProviderID.make("fal")
-const baseURL = FalQueue.DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   readonly baseURL?: string
@@ -26,17 +25,11 @@ const auth = (options: ProviderAuthOption<"optional">) => {
 }
 
 export const configure = (input: Config = {}) => {
-  const media = (modelID: string | ModelID) => ({
-    id: modelID,
-    auth: auth(input),
-    baseURL: input.baseURL ?? baseURL,
-    headers: input.headers,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-  })
+  const media = MediaRoute.deployment(input, auth(input))
   return {
     id,
-    image: (modelID: string | ModelID) => FalImages.model(media(modelID)),
-    video: (modelID: string | ModelID) => FalVideo.model(media(modelID)),
+    image: (modelID: string | ModelID) => FalImages.model({ ...media, id: modelID }),
+    video: (modelID: string | ModelID) => FalVideo.model({ ...media, id: modelID }),
     configure,
   }
 }

packages/ai/src/providers/google.ts

@@ -1,8 +1,9 @@
 import type { RouteDefaultsInput } from "../route/client.js"
 import { Auth } from "../route/auth.js"
 import type { ProviderAuthOption } from "../route/auth-options.js"
+import { MediaRoute } from "../route/media.js"
 import type { ProviderPackage } from "../provider-package.js"
-import { HttpOptions, ProviderID, mergeHttpOptions, type ModelID } from "../schema/index.js"
+import { ProviderID, type ModelID } from "../schema/index.js"
 import { Gemini } from "../protocols/gemini.js"
 import { GoogleImages } from "../protocols/google-images.js"
 import { GoogleSpeech } from "../protocols/google-speech.js"
@@ -46,20 +47,14 @@ const configuredRoute = (input: Config) => {
 
 export const configure = (input: Config = {}) => {
   const route = configuredRoute(input)
-  const media = (modelID: string | ModelID) => ({
-    id: modelID,
-    auth: auth(input),
-    baseURL: input.baseURL,
-    headers: input.headers,
-    http: mergeHttpOptions(input.http === undefined ? undefined : HttpOptions.make(input.http)),
-  })
+  const media = MediaRoute.deployment(input, auth(input))
   return {
     id,
     model: (modelID: string | ModelID) => route.model<Gemini.ProviderOptionsInput>({ id: modelID }),
-    image: (modelID: string | ModelID) => GoogleImages.model(media(modelID)),
-    video: (modelID: string | ModelID) => GoogleVideo.model(media(modelID)),
-    speech: (modelID: string | ModelID) => GoogleSpeech.model(media(modelID)),
-    transcription: (modelID: string | ModelID) => GoogleTranscription.model(media(modelID)),
+    image: (modelID: string | ModelID) => GoogleImages.model({ ...media, id: modelID }),
+    video: (modelID: string | ModelID) => GoogleVideo.model({ ...media, id: modelID }),
+    speech: (modelID: string | ModelID) => GoogleSpeech.model({ ...media, id: modelID }),
+    transcription: (modelID: string | ModelID) => GoogleTranscription.model({ ...media, id: modelID }),
     configure,
   }
 }

packages/ai/src/providers/meta.ts

@@ -7,7 +7,8 @@ import { MetaImages } from "../protocols/meta-images.js"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { HttpOptions, ProviderID, ToolDefinition, type ModelID } from "../schema/index.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, ToolDefinition, type ModelID, type OpenString } from "../schema/index.js"
 import type { OpenResponsesProviderOptionsInput } from "./open-responses-options.js"
 
 export const id = ProviderID.make("meta")
@@ -48,8 +49,8 @@ export const webSearch = (options: WebSearchOptions = {}) =>
 
 export interface ImageGenerationOptions {
   readonly size?: string
-  readonly outputFormat?: "webp" | "png" | "jpeg" | (string & {})
-  readonly reasoningStrength?: "low" | "high" | (string & {})
+  readonly outputFormat?: OpenString<"webp" | "png" | "jpeg">
+  readonly reasoningStrength?: OpenString<"low" | "high">
   readonly enableImageSearch?: boolean
   readonly enableWebSearch?: boolean
   readonly enableShell?: boolean
@@ -139,14 +140,8 @@ export const configure = (input: LanguageModelOptions = {}) => {
       id: modelID,
       compatibility: { requireSignature: false },
     })
-  const image = (modelID: string | ModelID) =>
-    MetaImages.model({
-      id: modelID,
-      baseURL: endpoint ?? baseURL,
-      auth: options.auth,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, options.auth)
+  const image = (modelID: string | ModelID) => MetaImages.model({ ...media, id: modelID })
   return { id, model: responses, responses, chat, messages, image, configure }
 }
 

packages/ai/src/providers/openai-options.ts

@@ -32,10 +32,7 @@ const openAIProviderOptions = (options: OpenAIOptionsInput | undefined): Provide
   return result
 }
 
-export const gpt5DefaultOptions = (
-  modelID: string,
-  options: { readonly textVerbosity?: boolean } = {},
-): ProviderOptions | undefined => {
+export const gpt5DefaultOptions = (modelID: string): ProviderOptions | undefined => {
   const id = modelID.toLowerCase()
   if (!id.includes("gpt-5") || id.includes("gpt-5-chat") || id.includes("gpt-5-pro")) return undefined
   return openAIProviderOptions({
@@ -47,27 +44,19 @@ export const gpt5DefaultOptions = (
     // this, callers using the default model facade get reasoning summaries
     // they cannot replay statelessly.
     include: ["reasoning.encrypted_content"],
-    textVerbosity:
-      options.textVerbosity === true && id.includes("gpt-5.") && !id.includes("codex") && !id.includes("-chat")
-        ? "low"
-        : undefined,
   })
 }
 
-export const openAIDefaultOptions = (
-  modelID: string,
-  options: { readonly textVerbosity?: boolean } = {},
-): ProviderOptions | undefined =>
-  mergeProviderOptions(openAIProviderOptions({ store: false }), gpt5DefaultOptions(modelID, options))
+export const openAIDefaultOptions = (modelID: string): ProviderOptions | undefined =>
+  mergeProviderOptions(openAIProviderOptions({ store: false }), gpt5DefaultOptions(modelID))
 
 export const withOpenAIOptions = <Options extends { readonly providerOptions?: OpenAIProviderOptionsInput }>(
   modelID: string,
   options: Options,
-  defaults: { readonly textVerbosity?: boolean } = {},
 ): Omit<Options, "providerOptions"> & { readonly providerOptions?: ProviderOptions } => {
   return {
     ...options,
-    providerOptions: mergeProviderOptions(openAIDefaultOptions(modelID, defaults), options.providerOptions),
+    providerOptions: mergeProviderOptions(openAIDefaultOptions(modelID), options.providerOptions),
   }
 }
 

packages/ai/src/providers/openai.ts

@@ -1,11 +1,19 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import type { Route, RouteDefaultsInput, CompactionOperations } from "../route/client.js"
+import { MediaRoute } from "../route/media.js"
 import type { ProviderPackage } from "../provider-package.js"
-import { HttpOptions, ProviderID, ToolDefinition, mergeHttpOptions, type ModelID } from "../schema/index.js"
+import {
+  HttpOptions,
+  ProviderID,
+  ToolDefinition,
+  mergeHttpOptions,
+  type ModelID,
+  type OpenString,
+} from "../schema/index.js"
 import * as OpenAIChat from "../protocols/openai-chat.js"
 import * as OpenAIResponses from "../protocols/openai-responses.js"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options.js"
-import { OpenAIImages, type OpenAIImageString } from "../protocols/openai-images.js"
+import { OpenAIImages } from "../protocols/openai-images.js"
 import { OpenAISpeech } from "../protocols/openai-speech.js"
 import { OpenAITranscription } from "../protocols/openai-transcription.js"
 
@@ -29,14 +37,14 @@ export type Config = RouteDefaultsInput &
   }
 
 export interface ImageGenerationOptions {
-  readonly action?: OpenAIImageString<"auto" | "generate" | "edit">
-  readonly background?: OpenAIImageString<"auto" | "opaque" | "transparent">
-  readonly inputFidelity?: OpenAIImageString<"low" | "high">
+  readonly action?: OpenString<"auto" | "generate" | "edit">
+  readonly background?: OpenString<"auto" | "opaque" | "transparent">
+  readonly inputFidelity?: OpenString<"low" | "high">
   readonly outputCompression?: number
-  readonly outputFormat?: OpenAIImageString<"png" | "jpeg" | "webp">
+  readonly outputFormat?: OpenString<"png" | "jpeg" | "webp">
   readonly partialImages?: number
-  readonly quality?: OpenAIImageString<"auto" | "low" | "medium" | "high" | "standard" | "hd">
-  readonly size?: OpenAIImageString<
+  readonly quality?: OpenString<"auto" | "low" | "medium" | "high" | "standard" | "hd">
+  readonly size?: OpenString<
     "auto" | "256x256" | "512x512" | "1024x1024" | "1536x1024" | "1024x1536" | "1792x1024" | "1024x1792"
   >
 }
@@ -92,26 +100,24 @@ export const configure = (input: Config = {}) => {
   const modelDefaults = defaults(input)
   const responses = (id: string | ModelID) =>
     responsesRoute
-      .with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true }))
+      .with(withOpenAIOptions(id, modelDefaults))
       .model<OpenAIProviderOptionsInput>({ id })
   const chat = (id: string | ModelID) =>
     chatRoute.with(withOpenAIOptions(id, modelDefaults)).model<OpenAIProviderOptionsInput>({
       id,
       compatibility: { supportsPromptCacheKey: true },
     })
-  const media = (modelID: string | ModelID) => ({
-    id: modelID,
-    auth: auth(input),
-    baseURL: input.baseURL,
-    headers: input.headers,
+  const deployment = MediaRoute.deployment(input, auth(input))
+  const media = {
+    ...deployment,
     http: mergeHttpOptions(
-      input.http === undefined ? undefined : HttpOptions.make(input.http),
+      deployment.http,
       input.queryParams === undefined ? undefined : new HttpOptions({ query: input.queryParams }),
     ),
-  })
-  const image = (modelID: string | ModelID) => OpenAIImages.model(media(modelID))
-  const speech = (modelID: string | ModelID) => OpenAISpeech.model(media(modelID))
-  const transcription = (modelID: string | ModelID) => OpenAITranscription.model(media(modelID))
+  }
+  const image = (modelID: string | ModelID) => OpenAIImages.model({ ...media, id: modelID })
+  const speech = (modelID: string | ModelID) => OpenAISpeech.model({ ...media, id: modelID })
+  const transcription = (modelID: string | ModelID) => OpenAITranscription.model({ ...media, id: modelID })
 
   return {
     id,

packages/ai/src/providers/opencode-zen.ts

@@ -20,7 +20,7 @@ export const configure = (input: Options = {}) => {
       auth: AuthOptions.bearer(input, "OPENCODE_API_KEY"),
       baseURL: input.baseURL ?? baseURL,
       headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+      http: HttpOptions.make(input.http),
     })
   return { id, experimental: { evaluation }, configure }
 }

packages/ai/src/providers/openrouter.ts

@@ -3,29 +3,27 @@ import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type CacheHint, type ModelID } from "../schema/index.js"
+import { HttpOptions, ProviderID, type CacheHint, type ModelID, type OpenString } from "../schema/index.js"
 import type { ProviderPackage } from "../provider-package.js"
 import { SystemOne } from "../experimental/system-one.js"
 import { OpenAIChat } from "../protocols/openai-chat.js"
 import { newBreakpoints, ttlBucket } from "../protocols/utils/cache.js"
-import { isRecord } from "../protocols/shared.js"
+import { isRecord, ProviderShared } from "../protocols/shared.js"
 
 export const id = ProviderID.make("openrouter")
 const baseURL = "https://openrouter.ai/api/v1"
 const ADAPTER = "openrouter"
 
-type OpenRouterString<Known extends string> = Known | (string & {})
-
 export interface OpenRouterProviderRouting {
   readonly [key: string]: unknown
   readonly order?: ReadonlyArray<string>
   readonly allow_fallbacks?: boolean
   readonly require_parameters?: boolean
-  readonly data_collection?: OpenRouterString<"allow" | "deny">
+  readonly data_collection?: OpenString<"allow" | "deny">
   readonly only?: ReadonlyArray<string>
   readonly ignore?: ReadonlyArray<string>
   readonly quantizations?: ReadonlyArray<string>
-  readonly sort?: OpenRouterString<"price" | "throughput" | "latency">
+  readonly sort?: OpenString<"price" | "throughput" | "latency">
   readonly max_price?: Readonly<{
     prompt?: number | string
     completion?: number | string
@@ -41,7 +39,7 @@ export type OpenRouterPlugin =
       id: "web"
       max_results?: number
       search_prompt?: string
-      engine?: OpenRouterString<"native" | "exa">
+      engine?: OpenString<"native" | "exa">
     }>
   | Readonly<{ id: "file-parser"; max_files?: number; pdf?: { engine?: string } }>
   | Readonly<{ id: "moderation" }>
@@ -58,7 +56,7 @@ export interface OpenRouterOptions {
   readonly reasoning?: Readonly<{
     enabled?: boolean
     exclude?: boolean
-    effort?: OpenRouterString<"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">
+    effort?: OpenString<"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">
     max_tokens?: number
   }>
   readonly usage?: boolean | Readonly<{ include: boolean }>
@@ -66,7 +64,7 @@ export interface OpenRouterOptions {
   readonly web_search_options?: Readonly<{
     max_results?: number
     search_prompt?: string
-    engine?: OpenRouterString<"native" | "exa">
+    engine?: OpenString<"native" | "exa">
   }>
 }
 
@@ -125,7 +123,7 @@ export const protocol = Protocol.make({
           return {
             ...body,
             messages,
-            ...bodyOptions(request.providerOptions),
+            ...bodyOptions(request.providerOptions, request.generation?.maxTokens),
           } as OpenRouterBody
         }),
       ),
@@ -145,7 +143,14 @@ const cacheControl = () => {
   }
 }
 
-const bodyOptions = (input: unknown) => {
+// OpenRouter forwards `reasoning.max_tokens` as the upstream thinking budget. Upstreams such as Anthropic and Alibaba
+// reject one that is not below the output limit; 1,024 is Anthropic's minimum budget.
+const fitReasoning = (reasoning: Record<string, unknown>, maxTokens: number | undefined) =>
+  typeof reasoning.max_tokens === "number"
+    ? { ...reasoning, max_tokens: ProviderShared.fitThinkingBudget(reasoning.max_tokens, maxTokens, 1_024) }
+    : reasoning
+
+const bodyOptions = (input: unknown, maxTokens: number | undefined) => {
   const openrouter = isRecord(input) ? input : {}
   const { usage, models, provider, plugins, web_search_options, debug, user, reasoning, promptCacheKey, ...options } =
     openrouter
@@ -164,7 +169,7 @@ const bodyOptions = (input: unknown) => {
     ...(isRecord(web_search_options) ? { web_search_options } : {}),
     ...(isRecord(debug) ? { debug } : {}),
     ...(typeof user === "string" ? { user } : {}),
-    ...(isRecord(reasoning) ? { reasoning } : {}),
+    ...(isRecord(reasoning) ? { reasoning: fitReasoning(reasoning, maxTokens) } : {}),
   }
 }
 
@@ -198,7 +203,7 @@ export const configure = (input: LanguageModelOptions = {}) => {
       auth: AuthOptions.bearer(input, "OPENROUTER_API_KEY"),
       baseURL: input.baseURL ?? baseURL,
       headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+      http: HttpOptions.make(input.http),
     })
   return {
     id,

packages/ai/src/providers/replicate.ts

@@ -1,11 +1,11 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { DEFAULT_BASE_URL, ReplicateImages } from "../protocols/replicate-images.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { ReplicateImages } from "../protocols/replicate-images.js"
 
 export type { ReplicateImageOptions } from "../protocols/replicate-images.js"
 
 export const id = ProviderID.make("replicate")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   readonly baseURL?: string
@@ -17,14 +17,8 @@ export type Config = ProviderAuthOption<"optional"> & {
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "REPLICATE_API_TOKEN")
 
 export const configure = (input: Config = {}) => {
-  const image = (modelID: string | ModelID) =>
-    ReplicateImages.model({
-      id: modelID,
-      auth: auth(input),
-      baseURL: input.baseURL ?? baseURL,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, auth(input))
+  const image = (modelID: string | ModelID) => ReplicateImages.model({ ...media, id: modelID })
   return {
     id,
     image,

packages/ai/src/providers/runway.ts

@@ -1,11 +1,11 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { DEFAULT_BASE_URL, RunwayVideo } from "../protocols/runway-video.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { RunwayVideo } from "../protocols/runway-video.js"
 
 export type { RunwayVideoOptions } from "../protocols/runway-video.js"
 
 export const id = ProviderID.make("runway")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   readonly baseURL?: string
@@ -16,14 +16,8 @@ export type Config = ProviderAuthOption<"optional"> & {
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "RUNWAYML_API_SECRET")
 
 export const configure = (input: Config = {}) => {
-  const video = (modelID: string | ModelID) =>
-    RunwayVideo.model({
-      id: modelID,
-      auth: auth(input),
-      baseURL: input.baseURL ?? baseURL,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, auth(input))
+  const video = (modelID: string | ModelID) => RunwayVideo.model({ ...media, id: modelID })
   return {
     id,
     video,

packages/ai/src/providers/stability.ts

@@ -1,11 +1,11 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
-import { DEFAULT_BASE_URL, StabilityImages } from "../protocols/stability-images.js"
+import { MediaRoute } from "../route/media.js"
+import { type HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { StabilityImages } from "../protocols/stability-images.js"
 
 export type { StabilityImageOptions, StabilityUpscaleOptions } from "../protocols/stability-images.js"
 
 export const id = ProviderID.make("stability")
-const baseURL = DEFAULT_BASE_URL
 
 export type Config = ProviderAuthOption<"optional"> & {
   readonly baseURL?: string
@@ -16,16 +16,11 @@ export type Config = ProviderAuthOption<"optional"> & {
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "STABILITY_API_KEY")
 
 export const configure = (input: Config = {}) => {
-  const deployment = {
-    auth: auth(input),
-    baseURL: input.baseURL ?? baseURL,
-    headers: input.headers,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-  }
+  const media = MediaRoute.deployment(input, auth(input))
   return {
     id,
-    image: (modelID: string | ModelID) => StabilityImages.model({ ...deployment, id: modelID }),
-    upscale: () => StabilityImages.upscaleModel(deployment),
+    image: (modelID: string | ModelID) => StabilityImages.model({ ...media, id: modelID }),
+    upscale: () => StabilityImages.upscaleModel(media),
     configure,
   }
 }

packages/ai/src/providers/typesafe-ai.ts

@@ -20,7 +20,7 @@ export const configure = (input: Options = {}) => {
       auth: AuthOptions.bearer(input, "TYPESAFE_API_KEY"),
       baseURL: input.baseURL ?? baseURL,
       headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+      http: HttpOptions.make(input.http),
     })
   return { id, experimental: { evaluation }, configure }
 }

packages/ai/src/providers/vercel-ai-gateway.ts

@@ -67,7 +67,7 @@ export const configure = (input: Options = {}) => {
     EvaluationModel.make<EvaluationOptions>({
       id: modelID,
       provider: id,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+      http: HttpOptions.make(input.http),
       route: {
         id: "vercel-evaluation",
         evaluate: (req, send) =>

packages/ai/src/providers/xai.ts

@@ -1,7 +1,8 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, type ModelID } from "../schema/index.js"
 import { OpenAIChat } from "../protocols/openai-chat.js"
 import { OpenResponsesChannel } from "../protocols/open-responses-channel.js"
 import { XAIResponses } from "../protocols/xai-responses.js"
@@ -89,20 +90,14 @@ export const configure = (input: LanguageModelOptions = {}) => {
   const chatRoute = configuredChatRoute(input)
   const responses = (modelID: string | ModelID) => responsesRoute.model<XAIProviderOptionsInput>({ id: modelID })
   const chat = (modelID: string | ModelID) => chatRoute.model<XAIProviderOptionsInput>({ id: modelID })
-  const media = (modelID: string | ModelID) => ({
-    id: modelID,
-    auth: auth(input),
-    baseURL: input.baseURL ?? baseURL,
-    headers: input.headers,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-  })
+  const media = MediaRoute.deployment(input, auth(input))
   return {
     id,
     model: responses,
     responses,
     chat,
-    image: (modelID: string | ModelID) => XAIImages.model(media(modelID)),
-    video: (modelID: string | ModelID) => XAIVideo.model(media(modelID)),
+    image: (modelID: string | ModelID) => XAIImages.model({ ...media, id: modelID }),
+    video: (modelID: string | ModelID) => XAIVideo.model({ ...media, id: modelID }),
     configure,
   }
 }

packages/ai/src/providers/zai.ts

@@ -5,7 +5,8 @@ import { OpenAIChat } from "../protocols/openai-chat.js"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
 import { Route, type RouteDefaultsInput } from "../route/client.js"
 import { Endpoint } from "../route/endpoint.js"
-import { HttpOptions, ProviderID, type ModelID } from "../schema/index.js"
+import { MediaRoute } from "../route/media.js"
+import { ProviderID, type ModelID } from "../schema/index.js"
 
 export const id = ProviderID.make("zai")
 
@@ -48,14 +49,8 @@ export const configure = (input: Config = {}) => {
         auth: auth(input),
       })
       .model<ChatOptionsInput>({ id: modelID, compatibility: ZAIChat.compatibility })
-  const image = (modelID: string | ModelID) =>
-    ZAIImages.model({
-      id: modelID,
-      auth: auth(input),
-      baseURL: input.baseURL,
-      headers: input.headers,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
-    })
+  const media = MediaRoute.deployment(input, auth(input))
+  const image = (modelID: string | ModelID) => ZAIImages.model({ ...media, id: modelID })
 
   return {
     id,

packages/ai/src/route/client.ts

@@ -11,7 +11,8 @@ import { applyEffortUpdates } from "../effort-updates.js"
 import { normalizeToolHistory } from "../tool-history.js"
 import { sanitizeSurrogates } from "../utils/sanitize.js"
 import * as ProviderShared from "../protocols/shared.js"
-import type { ProtocolID, ProviderOptions } from "../schema/index.js"
+import { ToolSchemaProjection } from "../protocols/utils/tool-schema.js"
+import type { LanguageModelSanitizerCompatibility, ProtocolID, ProviderOptions } from "../schema/index.js"
 import {
   AIError,
   CompactionResponse,
@@ -57,6 +58,7 @@ export interface Route<
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
   readonly supportsEffortUpdates?: (request: LLMRequest) => boolean
+  readonly sanitizer?: LanguageModelSanitizerCompatibility
   readonly with: {
     <Next extends CompactionOperations | undefined>(
       patch: RoutePatch<Body, Prepared> & { readonly compact: Next },
@@ -152,7 +154,7 @@ const mergeRouteDefaults = (base: RouteDefaults | undefined, patch: RouteDefault
     providerOptions: mergeProviderOptions(base?.providerOptions, patch.providerOptions),
     http: mergeHttpOptions(
       base?.http,
-      httpOptions(patch.http),
+      HttpOptions.make(patch.http),
       headers === undefined ? undefined : new HttpOptions({ headers }),
     ),
   }
@@ -172,11 +174,6 @@ const mergeHeaders = (...items: ReadonlyArray<Record<string, string> | undefined
 export const generationOptions = (input: GenerationOptions.Input | undefined) =>
   input === undefined ? undefined : GenerationOptions.make(input)
 
-export const httpOptions = (input: HttpOptionsInput | undefined) => {
-  if (input === undefined) return input
-  return HttpOptions.make(input)
-}
-
 export interface Interface {
   readonly compact: CompactMethod
   readonly stream: StreamMethod
@@ -393,6 +390,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
       defaults: routeInput.defaults ?? {},
       body: protocol.body,
       supportsEffortUpdates: protocol.supportsEffortUpdates,
+      sanitizer: protocol.sanitizer,
       with: (patch: RoutePatch<Body, Prepared>) => {
         const { compact, id, provider, providerMetadataKey, auth, transport, endpoint, ...defaults } = patch
         return build({
@@ -564,7 +562,9 @@ const prepareRequest = (request: LLMRequest) => {
       tool.type === "tool" ? tool : { ...tool, tools: dedupe(tool.tools) },
     )
   const resolved = applyCachePolicy(
-    applyEffortUpdates(LLMRequest.update(sanitized, { tools: dedupe(sanitized.tools) })),
+    applyEffortUpdates(
+      LLMRequest.update(sanitized, { tools: ToolSchemaProjection.tools(dedupe(sanitized.tools), sanitized.model) }),
+    ),
   )
   const headers = resolved.model.route.headers?.({ request: resolved })
   return headers === undefined

packages/ai/src/route/endpoint.ts

@@ -1,5 +1,4 @@
 import type { LLMRequest } from "../schema/index.js"
-import * as ProviderShared from "../protocols/shared.js"
 
 export interface EndpointInput<Body, Request = LLMRequest> {
   readonly request: Request
@@ -47,6 +46,8 @@ export const merge = <Body, Request = LLMRequest>(
   query: patch.query === undefined ? base.query : { ...base.query, ...patch.query },
 })
 
+export const trimBaseUrl = (value: string) => value.replace(/\/+$/, "")
+
 const renderPart = <Body, Request>(part: EndpointPart<Body, Request>, input: EndpointInput<Body, Request>) =>
   typeof part === "function" ? part(input) : part
 
@@ -54,7 +55,7 @@ export const render = <Body, Request = LLMRequest>(
   endpoint: Definition<Body, Request>,
   input: EndpointInput<Body, Request>,
 ) => {
-  const url = new URL(`${ProviderShared.trimBaseUrl(endpoint.baseURL ?? "")}${renderPart(endpoint.path, input)}`)
+  const url = new URL(`${trimBaseUrl(endpoint.baseURL ?? "")}${renderPart(endpoint.path, input)}`)
   for (const [key, value] of Object.entries(endpoint.query ?? {})) url.searchParams.set(key, value)
   return url
 }

packages/ai/src/route/framing.ts

@@ -1,6 +1,6 @@
-import { Stream } from "effect"
-import * as ProviderShared from "../protocols/shared.js"
-import type { AIError } from "../schema/index.js"
+import { Effect, Stream } from "effect"
+import { makeParser, type Event } from "effect/unstable/encoding/Sse"
+import { AIError, InvalidProviderOutputError } from "../schema/index.js"
 
 /**
  * Decode a streaming HTTP response body into provider-protocol frames.
@@ -25,19 +25,75 @@ export interface Definition<Frame> {
   readonly body?: (frame: Frame) => string | undefined
 }
 
+/**
+ * `framing` step for Server-Sent Events. Decodes UTF-8, runs the SSE channel
+ * decoder, optionally filters named events, and drops empty events and known
+ * keepalives that proxies send as data. `[DONE]` is dropped by default or
+ * retained for protocols that use it as their stream boundary. Retry control events are ignored without
+ * interrupting the stream. Decoder failures become provider output errors so
+ * the public error channel stays `AIError`.
+ */
+export const sseFraming = (
+  bytes: Stream.Stream<Uint8Array, AIError>,
+  events?: ReadonlySet<string>,
+  includeDone = false,
+): Stream.Stream<string, AIError> =>
+  bytes.pipe(
+    Stream.decodeText(),
+    Stream.mapAccumEffect(
+      () => {
+        const output: Event[] = []
+        return {
+          output,
+          parser: makeParser((event) => {
+            if (event._tag === "Event") output.push(event)
+          }),
+        }
+      },
+      (state, chunk) =>
+        Effect.gen(function* () {
+          const error = state.parser.feed(chunk)
+          if (error)
+            return yield* new AIError({
+              reason: new InvalidProviderOutputError({
+                route: "sse",
+                message: error.message,
+                body: chunk,
+                cause: error,
+              }),
+            })
+          return [state, state.output.splice(0)] as const
+        }),
+    ),
+    Stream.filter(
+      (event) =>
+        (events === undefined || events.has(event.event)) &&
+        event.data.length > 0 &&
+        // Some OpenAI-compatible proxies serialize an empty flush as a bare
+        // `data: null`, between events or after `[DONE]`. No protocol has a
+        // null event, so it carries nothing and must not abort the stream.
+        event.data !== "null" &&
+        // Vertex AI partner models (e.g. `xai/grok-4.6`) send their SSE
+        // keepalive comment as `data: : keepalive` while reasoning.
+        event.data !== ": keepalive" &&
+        (event.data !== "[DONE]" || includeDone || (events !== undefined && event.event !== "message")),
+    ),
+    Stream.map((event) => event.data),
+  )
+
 /** Server-Sent Events framing. Used by every JSON-streaming HTTP provider. */
-export const sse: Definition<string> = { id: "sse", frame: ProviderShared.sseFraming }
+export const sse: Definition<string> = { id: "sse", frame: sseFraming }
 
 /** Server-Sent Events framing that retains the conventional `[DONE]` sentinel. */
 export const sseWithDone: Definition<string> = {
   id: "sse",
-  frame: (bytes) => ProviderShared.sseFraming(bytes, undefined, true),
+  frame: (bytes) => sseFraming(bytes, undefined, true),
 }
 
 /** SSE framing restricted to protocol-recognized event names. */
 export const sseEvents = (events: ReadonlySet<string>): Definition<string> => ({
   id: "sse",
-  frame: (bytes) => ProviderShared.sseFraming(bytes, events),
+  frame: (bytes) => sseFraming(bytes, events),
 })
 
 export const lines: Definition<string> = {

packages/ai/src/route/media-protocol.ts

@@ -9,7 +9,9 @@ import {
   HttpContext,
   InvalidProviderOutputError,
   InvalidRequestError,
+  ProviderID,
   ProviderInternalError,
+  UnsupportedOperationError,
 } from "../schema/index.js"
 
 // ---------------------------------------------------------------------------
@@ -61,7 +63,7 @@ export interface DecodeContext<Request> {
 export interface Inline<Request, Response> {
   readonly kind: "inline"
   readonly id: string
-  readonly name: string
+  readonly provider: ProviderID
   /** Common request fields this protocol cannot lower; the route rejects them before `body.from` runs. */
   readonly unsupported?: ReadonlyArray<keyof Request & string>
   readonly body: { readonly from: (request: Request) => Effect.Effect<Body, AIError> }
@@ -74,11 +76,9 @@ export interface Inline<Request, Response> {
 }
 
 export const inline = <Request, Response>(
-  input: Omit<Inline<Request, Response>, "kind">,
-): Inline<Request, Response> => ({
-  kind: "inline",
-  ...input,
-})
+  route: Identity,
+  input: Omit<Inline<Request, Response>, "kind" | "id" | "provider">,
+): Inline<Request, Response> => ({ kind: "inline", id: route.id, provider: route.provider, ...input })
 
 /** What `start` learned from the submission response: the route-owned handle plus the first observation. */
 export interface Started<Token> {
@@ -107,7 +107,7 @@ export interface PollContext<Token> {
 export interface Queued<Request, Response, Token> {
   readonly kind: "queued"
   readonly id: string
-  readonly name: string
+  readonly provider: ProviderID
   /** Common request fields this protocol cannot lower; the route rejects them before `start.body.from` runs. */
   readonly unsupported?: ReadonlyArray<keyof Request & string>
   /** Serializable handle. `Generation.token` carries the encoded form so it can be persisted and resumed elsewhere. */
@@ -141,11 +141,9 @@ export interface Queued<Request, Response, Token> {
 }
 
 export const queued = <Request, Response, Token>(
-  input: Omit<Queued<Request, Response, Token>, "kind">,
-): Queued<Request, Response, Token> => ({
-  kind: "queued",
-  ...input,
-})
+  route: Identity,
+  input: Omit<Queued<Request, Response, Token>, "kind" | "id" | "provider">,
+): Queued<Request, Response, Token> => ({ kind: "queued", id: route.id, provider: route.provider, ...input })
 
 export type Mode = "generate" | "stream"
 
@@ -162,7 +160,7 @@ export interface ResponseContext<Request> extends DecodeContext<Addressed<Reques
 export interface Streamed<Request, Event, Frame, State> {
   readonly kind: "stream"
   readonly id: string
-  readonly name: string
+  readonly provider: ProviderID
   /** Common request fields this protocol cannot lower; the route rejects them before `body.from` runs. */
   readonly unsupported?: ReadonlyArray<keyof Request & string>
   readonly body: { readonly from: (request: Addressed<Request>) => Effect.Effect<Body, AIError> }
@@ -177,11 +175,9 @@ export interface Streamed<Request, Event, Frame, State> {
 }
 
 export const stream = <Request, Event, Frame, State>(
-  input: Omit<Streamed<Request, Event, Frame, State>, "kind">,
-): Streamed<Request, Event, Frame, State> => ({
-  kind: "stream",
-  ...input,
-})
+  route: Identity,
+  input: Omit<Streamed<Request, Event, Frame, State>, "kind" | "id" | "provider">,
+): Streamed<Request, Event, Frame, State> => ({ kind: "stream", id: route.id, provider: route.provider, ...input })
 
 // ---------------------------------------------------------------------------
 // Response helpers
@@ -190,71 +186,98 @@ export const stream = <Request, Event, Frame, State>(
 const context = (response: HttpClientResponse.HttpClientResponse) =>
   new HttpContext({ url: response.request.url, status: response.status, headers: response.headers })
 
-/**
- * Read a text body while retaining the original payload and HTTP context on every downstream error. `invalid` is a
- * malformed provider document; `ended` is a generation that reached a terminal status without output (`failed` is
- * provider-side, `cancelled`/`expired` mean the result will never exist); `contentPolicy` is a moderated result.
- */
-export const text = Effect.fn("MediaProtocol.text")(function* (
-  route: string,
-  name: string,
-  response: HttpClientResponse.HttpClientResponse,
-) {
-  const http = context(response)
-  const body = yield* response.text.pipe(
-    Effect.mapError(
-      (cause) =>
-        new AIError({
-          reason: new InvalidProviderOutputError({
-            route,
-            message: `Failed to read the ${name} response`,
-            http,
-            cause,
+/** One protocol's route id, display name, and provider, with the decoders and errors that carry them. */
+export const identity = (input: { readonly id: string; readonly name: string; readonly provider: string }) => {
+  const provider = ProviderID.make(input.provider)
+  const frameError = (message: string, body?: string, cause?: unknown) =>
+    new AIError({ reason: new InvalidProviderOutputError({ route: input.id, message, body, cause }) })
+
+  /**
+   * Read a text body while retaining the original payload and HTTP context on every downstream error. `invalid` is a
+   * malformed provider document; `ended` is a generation that reached a terminal status without output (`failed` is
+   * provider-side, `cancelled`/`expired` mean the result will never exist); `contentPolicy` is a moderated result.
+   */
+  const text = Effect.fn("MediaProtocol.text")(function* (response: HttpClientResponse.HttpClientResponse) {
+    const http = context(response)
+    const body = yield* response.text.pipe(
+      Effect.mapError(
+        (cause) =>
+          new AIError({
+            reason: new InvalidProviderOutputError({
+              route: input.id,
+              message: `Failed to read the ${input.name} response`,
+              http,
+              cause,
+            }),
           }),
-        }),
-    ),
-  )
-  return {
-    body,
-    http,
-    invalid: (message: string, cause?: unknown) =>
-      new AIError({ reason: new InvalidProviderOutputError({ route, message, body, http, cause }) }),
-    ended: (status: Exclude<Status, "queued" | "running" | "completed">, message: string) =>
-      new AIError({
-        reason:
-          status === "failed"
-            ? new ProviderInternalError({ message, body, http })
-            : new InvalidRequestError({ message, body, http }),
-      }),
-    contentPolicy: (message: string) => new AIError({ reason: new ContentPolicyError({ message, body, http }) }),
-  }
-})
-
-export type Output = Effect.Success<ReturnType<typeof text>>
-
-/** Read and Schema-decode a JSON body. Decode failures keep the raw body as `reason.body`. */
-export const decodeJson = <A>(route: string, name: string, schema: Schema.Codec<A, unknown>) => {
-  const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema))
-  return Effect.fn("MediaProtocol.decodeJson")(function* (response: HttpClientResponse.HttpClientResponse) {
-    const output = yield* text(route, name, response)
-    const value = yield* decode(output.body).pipe(
-      Effect.mapError((cause) => output.invalid(`${name} returned an invalid response`, cause)),
+      ),
     )
-    return { ...output, value }
+    return {
+      body,
+      http,
+      invalid: (message: string, cause?: unknown) =>
+        new AIError({ reason: new InvalidProviderOutputError({ route: input.id, message, body, http, cause }) }),
+      ended: (status: Exclude<Status, "queued" | "running" | "completed">, message: string) =>
+        new AIError({
+          reason:
+            status === "failed"
+              ? new ProviderInternalError({ message, body, http })
+              : new InvalidRequestError({ message, body, http }),
+        }),
+      contentPolicy: (message: string) => new AIError({ reason: new ContentPolicyError({ message, body, http }) }),
+    }
   })
+
+  /** Read and Schema-decode a JSON body. Decode failures keep the raw body as `reason.body`. */
+  const decodeJson = <A>(schema: Schema.Codec<A, unknown>) => {
+    const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema))
+    return Effect.fn("MediaProtocol.decodeJson")(function* (response: HttpClientResponse.HttpClientResponse) {
+      const output = yield* text(response)
+      const value = yield* decode(output.body).pipe(
+        Effect.mapError((cause) => output.invalid(`${input.name} returned an invalid response`, cause)),
+      )
+      return { ...output, value }
+    })
+  }
+
+  return {
+    id: input.id,
+    name: input.name,
+    provider,
+    text,
+    decodeJson,
+    /** Decode a submission response into the token and first snapshot. */
+    decodeStarted: <A, Token>(schema: Schema.Codec<A, unknown>, started: (value: A) => Started<Token>) => {
+      const decode = decodeJson(schema)
+      return (response: HttpClientResponse.HttpClientResponse) =>
+        decode(response).pipe(Effect.map((output) => started(output.value)))
+    },
+    /** Schema-decode one JSON stream frame. Decode failures keep the frame as `reason.body`. */
+    decodeFrame: <A>(schema: Schema.Codec<A, unknown>) => {
+      const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema))
+      return (frame: string) =>
+        decode(frame).pipe(
+          Effect.mapError((cause) => frameError(`${input.name} sent an invalid stream event`, frame, cause)),
+        )
+    },
+    /** A stream-time failure; the frame stays on `reason.body`. */
+    frameError,
+    incomplete: () =>
+      new AIError({
+        reason: new InvalidProviderOutputError({
+          route: input.id,
+          message: "The provider response ended unexpectedly.",
+          classification: "incomplete-stream",
+        }),
+      }),
+    unsupported: (operation: string, message: string) =>
+      new AIError({ reason: new UnsupportedOperationError({ operation, provider, route: input.id, message }) }),
+  }
 }
 
-/** Decode a submission response into the token and first snapshot. */
-export const decodeStarted = <A, Token>(
-  route: string,
-  name: string,
-  schema: Schema.Codec<A, unknown>,
-  started: (value: A) => Started<Token>,
-) => {
-  const decode = decodeJson(route, name, schema)
-  return (response: HttpClientResponse.HttpClientResponse) =>
-    decode(response).pipe(Effect.map((output) => started(output.value)))
-}
+export type Identity = ReturnType<typeof identity>
+
+export type Output = Effect.Success<ReturnType<Identity["text"]>>
 
 /** Map a provider status string through the protocol's table; unknown values are an invalid provider document. */
 export const status = <Table extends Record<string, Status>>(
@@ -267,27 +290,6 @@ export const status = <Table extends Record<string, Status>>(
   return Effect.succeed(normalized)
 }
 
-export const frameError = (route: string, message: string, body?: string, cause?: unknown) =>
-  new AIError({ reason: new InvalidProviderOutputError({ route, message, body, cause }) })
-
-export const incomplete = (route: string) =>
-  new AIError({
-    reason: new InvalidProviderOutputError({
-      route,
-      message: "The provider response ended unexpectedly.",
-      classification: "incomplete-stream",
-    }),
-  })
-
-/** Schema-decode one JSON stream frame. Decode failures keep the frame as `reason.body`. */
-export const decodeFrame = <A>(route: string, name: string, schema: Schema.Codec<A, unknown>) => {
-  const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema))
-  return (frame: string) =>
-    decode(frame).pipe(
-      Effect.mapError((cause) => frameError(route, `${name} sent an invalid stream event`, frame, cause)),
-    )
-}
-
 /** A `url` asset whose provider-declared retention window starts now. */
 export const expiringUrl = (url: string, retention: Duration.Duration, options?: Parameters<typeof Media.url>[1]) =>
   Clock.currentTimeMillis.pipe(

packages/ai/src/route/media.ts

@@ -2,26 +2,21 @@ import { Effect, Schema, Stream } from "effect"
 import { Headers, HttpClientRequest, type HttpClientResponse } from "effect/unstable/http"
 import { Auth, type AuthInput } from "./auth.js"
 import { Endpoint } from "./endpoint.js"
-import { Service as RequestExecutorService, type Interface } from "./executor-service.js"
+import { RequestExecutorService, type Interface } from "./executor-service.js"
 import { RequestExecutor } from "./executor.js"
 import { MediaProtocol } from "./media-protocol.js"
-import {
-  Generation,
-  resultEvents,
-  type AwaitOptions,
-  type Observation,
-  type Route as GenerationRoute,
-} from "../generation.js"
+import { Generation } from "../generation.js"
 import type { Media } from "../media.js"
-import { ProviderShared } from "../protocols/shared.js"
 import {
   AIError,
   AIErrorReason,
   HttpOptions,
   InvalidRequestError,
   ProviderID,
+  UnsupportedOperationError,
   mergeHttpOptions,
 } from "../schema/index.js"
+import { encodeJson } from "../utils/json.js"
 import { sanitizeSurrogates } from "../utils/sanitize.js"
 
 export type Execute = Interface["execute"]
@@ -41,12 +36,23 @@ export interface ModelInput {
   readonly http?: HttpOptions
 }
 
+/** A provider facade's `configure(...)` input as the `ModelInput` every media selector shares, minus the model id. */
+export const deployment = (
+  input: { readonly baseURL?: string; readonly headers?: Record<string, string>; readonly http?: HttpOptions.Input },
+  auth: Auth.Definition,
+): Omit<ModelInput, "id"> => ({
+  auth,
+  baseURL: input.baseURL,
+  headers: input.headers,
+  http: HttpOptions.make(input.http),
+})
+
 // ---------------------------------------------------------------------------
 // Routes
 // ---------------------------------------------------------------------------
 
 /** One request, one response. */
-export interface Route<Request extends MediaRequest, Response> {
+export interface InlineRoute<Request extends MediaRequest, Response> {
   readonly kind: "inline"
   readonly id: string
   readonly provider: ProviderID
@@ -80,13 +86,11 @@ export interface StreamRoute<Request extends MediaRequest, Event, Response> {
 }
 
 export type AnyRoute<Request extends MediaRequest, Event, Response> =
-  | Route<Request, Response>
+  | InlineRoute<Request, Response>
   | StreamRoute<Request, Event, Response>
   | QueuedRoute<Request, Response>
 
 export interface Composition<Request extends MediaRequest> {
-  readonly id: string
-  readonly provider: string | ProviderID
   readonly endpoint: Endpoint.Definition<MediaProtocol.Body, Request>
   readonly auth: Auth.Definition
   /** Deployment headers applied before transport authentication. */
@@ -115,12 +119,12 @@ export interface StreamInput<Request extends MediaRequest, Event, Response, Fram
  */
 export const inline = <Request extends MediaRequest, Response>(
   input: InlineInput<Request, Response>,
-): Route<Request, Response> => {
+): InlineRoute<Request, Response> => {
   const transport = makeTransport(input)
   return {
     kind: "inline",
-    id: input.id,
-    provider: transport.provider,
+    id: input.protocol.id,
+    provider: input.protocol.provider,
     protocol: input.protocol.id,
     generate: Effect.fn(`MediaRoute.generate`)(function* (request: Request, execute: Execute) {
       const submitted = yield* transport.submit(
@@ -161,7 +165,7 @@ export const queued = <Request extends MediaRequest, Response, Token>(
         .call("GET", operation.path(token), http, execute)
         .pipe(Effect.flatMap((sent) => operation.decode(sent.response, { token, auth: sent.auth, materialize })))
     const cancel = protocol.cancel
-    const route: GenerationRoute<Response> = {
+    return {
       status: poll(protocol.status),
       result: poll(protocol.result),
       cancel:
@@ -169,7 +173,6 @@ export const queued = <Request extends MediaRequest, Response, Token>(
           ? undefined
           : transport.call(cancel.method, cancel.path(token), http, execute).pipe(Effect.asVoid),
     }
-    return route
   }
 
   const start = Effect.fn("MediaRoute.start")(function* (request: Request, execute: Execute) {
@@ -193,7 +196,7 @@ export const queued = <Request extends MediaRequest, Response, Token>(
         (cause) =>
           new AIError({
             reason: new InvalidRequestError({
-              message: `${input.id} cannot resume a generation from this token`,
+              message: `${protocol.id} cannot resume a generation from this token`,
               cause,
             }),
           }),
@@ -203,7 +206,7 @@ export const queued = <Request extends MediaRequest, Response, Token>(
     return new Generation(route, encodeToken(token), yield* route.status)
   })
 
-  return { kind: "queued", id: input.id, provider: transport.provider, protocol: protocol.id, start, resume }
+  return { kind: "queued", id: protocol.id, provider: protocol.provider, protocol: protocol.id, start, resume }
 }
 
 /** Compose a streaming media protocol; `generate` runs the same stream in `generate` mode and folds it with `collect`. */
@@ -255,8 +258,8 @@ export const stream = <Request extends MediaRequest, Event, Response, Frame, Sta
     )
   return {
     kind: "stream",
-    id: input.id,
-    provider: transport.provider,
+    id: protocol.id,
+    provider: protocol.provider,
     protocol: protocol.id,
     stream: (request, execute) => events(request, execute, "stream"),
     generate: (request, execute) =>
@@ -264,67 +267,17 @@ export const stream = <Request extends MediaRequest, Event, Response, Frame, Sta
   }
 }
 
-export const dispatch = <Event, Response>(input: {
-  readonly modality: string
-  readonly execute: Execute
-  readonly responseEvents: (response: Response) => ReadonlyArray<Event>
-}) => {
-  const notQueued = (route: { readonly provider: ProviderID; readonly id: string }, operation: string) =>
-    ProviderShared.unsupportedOperation({
-      operation: `${input.modality}.${operation}`,
-      provider: route.provider,
-      route: route.id,
-      message: `${route.provider}/${route.id} is not a queued route; use generate or stream`,
-    })
-  const start = <Request extends MediaRequest>(route: AnyRoute<Request, Event, Response>, request: Request) => {
-    if (route.kind !== "queued") return Effect.fail(notQueued(route, "start"))
-    return route.start(request, input.execute)
-  }
-  return {
-    start,
-    resume: <Request extends MediaRequest>(
-      route: AnyRoute<Request, Event, Response>,
-      model: MediaRequest["model"],
-      token: unknown,
-    ) => {
-      if (route.kind !== "queued") return Effect.fail(notQueued(route, "resume"))
-      return route.resume(model, token, input.execute)
-    },
-    generate: <Request extends MediaRequest>(
-      route: AnyRoute<Request, Event, Response>,
-      request: Request,
-      options?: AwaitOptions,
-    ) => {
-      if (route.kind !== "queued") return route.generate(request, input.execute)
-      return start(route, request).pipe(Effect.flatMap((generation) => generation.await(options)))
-    },
-    stream: <Request extends MediaRequest>(
-      route: AnyRoute<Request, Event, Response>,
-      request: Request,
-      options?: AwaitOptions,
-    ): Stream.Stream<Event | Observation, AIError> => {
-      if (route.kind === "stream") return route.stream(request, input.execute)
-      if (route.kind === "queued")
-        return Stream.unwrap(
-          start(route, request).pipe(
-            Effect.map((generation) => resultEvents(generation, input.responseEvents, options)),
-          ),
-        )
-      return Stream.fromIterableEffect(Effect.map(route.generate(request, input.execute), input.responseEvents))
-    },
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Transport plumbing shared by every kind
 // ---------------------------------------------------------------------------
 
-const makeTransport = <Request extends MediaRequest>(input: Composition<Request>) => {
-  const provider = ProviderID.make(input.provider)
+const makeTransport = <Request extends MediaRequest>(
+  input: Composition<Request> & { readonly protocol: { readonly id: string; readonly provider: ProviderID } },
+) => {
   const routeHttp = input.headers === undefined ? undefined : new HttpOptions({ headers: input.headers })
   const authorize = Auth.toEffect(input.auth)
-  const baseURL = (path: string) => new URL(`${ProviderShared.trimBaseUrl(input.endpoint.baseURL ?? "")}${path}`)
-  /** `auth` is only what `Auth` added, never deployment headers. */
+  const baseURL = (path: string) => new URL(`${Endpoint.trimBaseUrl(input.endpoint.baseURL ?? "")}${path}`)
+  /** `auth` is only what `Auth` added or changed, never untouched deployment headers. */
   const send = Effect.fn("MediaRoute.send")(function* (
     call: {
       readonly method: AuthInput["method"]
@@ -347,10 +300,12 @@ const makeTransport = <Request extends MediaRequest>(input: Composition<Request>
     const response = yield* execute(
       encoded.apply(HttpClientRequest.make(call.method)(url).pipe(HttpClientRequest.setHeaders(headers))),
     )
-    return { response, auth: Object.fromEntries(Object.entries(headers).filter(([key]) => !(key in call.headers))) }
+    return {
+      response,
+      auth: Object.fromEntries(Object.entries(headers).filter(([key, value]) => encoded.headers[key] !== value)),
+    }
   })
   return {
-    provider,
     /** Route and model overlays; `start` additionally merges the request's own `http`. */
     http: (model: MediaRequest["model"]) => mergeHttpOptions(routeHttp, model.http),
     /** POST the protocol body to the route endpoint. */
@@ -363,7 +318,7 @@ const makeTransport = <Request extends MediaRequest>(input: Composition<Request>
       },
       execute: Execute,
     ) {
-      yield* rejectUnsupported(input.id, provider, request, protocol.unsupported)
+      yield* rejectUnsupported(input.protocol.id, input.protocol.provider, request, protocol.unsupported)
       const http = mergeHttpOptions(routeHttp, request.model.http, request.http)
       const headers = Headers.fromInput(http?.headers)
       const prepared =
@@ -408,7 +363,7 @@ const withQuery = (url: URL, query: MediaProtocol.Query | undefined) => {
 const encode = (body: MediaProtocol.Body | undefined, headers: Headers.Headers) => {
   if (body === undefined) return { text: "", headers, apply: (request: HttpClientRequest.HttpClientRequest) => request }
   if (body.type === "json") {
-    const text = ProviderShared.encodeJson(body.value)
+    const text = encodeJson(body.value)
     return { text, headers, apply: HttpClientRequest.bodyText(text, "application/json") }
   }
   if (body.type === "binary")
@@ -438,11 +393,13 @@ const rejectUnsupported = <Request extends object>(
   })
   if (present.length === 0) return Effect.void
   return Effect.fail(
-    ProviderShared.unsupportedOperation({
-      operation: `media.${present[0]}`,
-      provider,
-      route,
-      message: `${provider}/${route} does not support ${present.join(", ")}`,
+    new AIError({
+      reason: new UnsupportedOperationError({
+        operation: `media.${present[0]}`,
+        provider,
+        route,
+        message: `${provider}/${route} does not support ${present.join(", ")}`,
+      }),
     }),
   )
 }

packages/ai/src/route/protocol.ts

@@ -1,5 +1,5 @@
 import { Schema, type Effect } from "effect"
-import type { AIError, LLMEvent, LLMRequest, ProtocolID } from "../schema/index.js"
+import type { AIError, LanguageModelSanitizerCompatibility, LLMEvent, LLMRequest, ProtocolID } from "../schema/index.js"
 
 /**
  * The semantic API contract of one model server family.
@@ -43,6 +43,8 @@ export interface Protocol<Body, Frame, Event, State> {
   readonly stream: ProtocolStream<Frame, Event, State>
   /** Whether `body.from` lowers `Message.effort(...)` markers; wrappers around another `body.from` must forward it. */
   readonly supportsEffortUpdates?: (request: LLMRequest) => boolean
+  /** Tool schema sanitizer for every model on this protocol unless the model's compatibility sets one; wrappers around another `body.from` must forward it. */
+  readonly sanitizer?: LanguageModelSanitizerCompatibility
 }
 
 export interface ProtocolBody<Body> {

packages/ai/src/schema/options.ts

@@ -57,8 +57,13 @@ export class HttpOptions extends Schema.Class<HttpOptions>("AI.HttpOptions")({
 export namespace HttpOptions {
   export type Input = HttpOptions | ConstructorParameters<typeof HttpOptions>[0]
 
-  /** Normalize HTTP option input into the canonical `HttpOptions` class. */
-  export const make = (input: Input) => (input instanceof HttpOptions ? input : new HttpOptions(input))
+  /** Normalize HTTP option input into the canonical `HttpOptions` class; `undefined` stays `undefined`. */
+  export function make(input: Input): HttpOptions
+  export function make(input: Input | undefined): HttpOptions | undefined
+  export function make(input: Input | undefined) {
+    if (input === undefined || input instanceof HttpOptions) return input
+    return new HttpOptions(input)
+  }
 }
 
 export const mergeHttpOptions = (...items: ReadonlyArray<HttpOptions | undefined>): HttpOptions | undefined => {
@@ -140,13 +145,16 @@ export namespace LanguageModelDefaults {
     return new LanguageModelDefaults({
       generation: input.generation === undefined ? undefined : GenerationOptions.make(input.generation),
       providerOptions: input.providerOptions,
-      http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+      http: HttpOptions.make(input.http),
     })
   }
 }
 
+/** Provider-defined string enum: known values for autocomplete, any string accepted. */
+export type OpenString<Known extends string> = Known | (string & {})
+
 export const ReasoningEfforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const
-export type ReasoningEffort = (typeof ReasoningEfforts)[number] | (string & {})
+export type ReasoningEffort = OpenString<(typeof ReasoningEfforts)[number]>
 export const ReasoningEffort = Schema.declare<ReasoningEffort>(
   (value): value is ReasoningEffort => typeof value === "string",
   { title: "ReasoningEffort" },

packages/ai/src/speech-client.ts

@@ -1,53 +1,31 @@
-import { Context, Effect, Layer, Stream } from "effect"
-import { RequestExecutor } from "./route/executor.js"
-import type { AIError } from "./schema/index.js"
-import type { SpeechEvent, SpeechOptions, SpeechRequestFor, SpeechResponse } from "./speech.js"
+import { Context } from "effect"
+import { MediaClient } from "./media-client.js"
+import {
+  SpeechTimestampsEvent,
+  SpeechFinishEvent,
+  type SpeechEvent,
+  type SpeechRequestFor,
+  type SpeechResponse,
+} from "./speech.js"
 
-export interface Interface {
-  readonly generate: <Options extends SpeechOptions>(
-    request: SpeechRequestFor<Options>,
-  ) => Effect.Effect<SpeechResponse, AIError>
-  readonly stream: <Options extends SpeechOptions>(
-    request: SpeechRequestFor<Options>,
-  ) => Stream.Stream<SpeechEvent, AIError>
-}
+export type Interface = MediaClient.Interface<SpeechRequestFor, SpeechEvent, SpeechResponse>
 
 export class SpeechClientService extends Context.Service<SpeechClientService, Interface>()("@opencode/SpeechClient") {}
 export const Service = SpeechClientService
 export type Service = SpeechClientService
 
-export const generate = <Options extends SpeechOptions>(
-  request: SpeechRequestFor<Options>,
-): Effect.Effect<SpeechResponse, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.generate(request)
-  })
-
-export const stream = <Options extends SpeechOptions>(
-  request: SpeechRequestFor<Options>,
-): Stream.Stream<SpeechEvent, AIError, Service> =>
-  Stream.unwrap(
-    Effect.gen(function* () {
-      const client = yield* Service
-      return client.stream(request)
-    }),
-  )
-
-export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const executor = yield* RequestExecutor.Service
-    return Service.of({
-      generate: (request) => request.model.route.generate(request, executor.execute),
-      stream: (request) => request.model.route.stream(request, executor.execute),
-    })
-  }),
-)
-
 export const SpeechClient = {
   Service,
-  layer,
-  generate,
-  stream,
+  ...MediaClient.make(Service, {
+    modality: "speech",
+    responseEvents: (response: SpeechResponse) => [
+      ...(response.timestamps === undefined ? [] : [SpeechTimestampsEvent.make({ items: response.timestamps })]),
+      SpeechFinishEvent.make({
+        audio: response.audio,
+        usage: response.usage,
+        notices: response.notices,
+        providerMetadata: response.providerMetadata,
+      }),
+    ],
+  }),
 } as const

packages/ai/src/speech.ts

@@ -1,62 +1,48 @@
 import { Effect, Schema, Stream } from "effect"
+import { ProgressEvent, QueuedEvent } from "./generation.js"
 import { Media } from "./media.js"
 import { MediaModel, composeRoute, tryRequest } from "./media-model.js"
 import { MediaRoute } from "./route/media.js"
-import type { MediaProtocol } from "./route/media-protocol.js"
-import { AIError, HttpOptions, MediaUsage, ProviderMetadata } from "./schema/index.js"
+import { AIError, HttpOptions, MediaUsage, ProviderMetadata, type OpenString } from "./schema/index.js"
 import { SpeechClient, Service } from "./speech-client.js"
 
 // ---------------------------------------------------------------------------
 // Model
 // ---------------------------------------------------------------------------
 
-export type SpeechOptions = Record<string, unknown>
+export type SpeechOptions = MediaModel.Options
 
-export type SpeechRoute<Options extends SpeechOptions = SpeechOptions> = MediaRoute.StreamRoute<
-  SpeechRequestFor<Options>,
-  SpeechEvent,
-  SpeechResponse
->
+export type SpeechRoute = MediaRoute.AnyRoute<SpeechRequestFor, SpeechEvent, SpeechResponse>
 
-export class SpeechModel<Options extends SpeechOptions = SpeechOptions> extends MediaModel<
-  SpeechRoute<Options>,
-  Options
-> {
+export class SpeechModel<Options extends SpeechOptions = SpeechOptions> extends MediaModel<SpeechRoute, Options> {
   declare protected readonly _SpeechModel: void
 
-  static make<Options extends SpeechOptions = SpeechOptions>(input: MediaModel.Input<SpeechRoute<Options>>) {
-    return new SpeechModel<Options>(input)
-  }
-
-  /** Compose a streaming speech protocol with its canonical path into a model for one deployment. */
-  static fromRoute<Options extends SpeechOptions = SpeechOptions, Frame = unknown, State = unknown>(
-    route: SpeechModel.RouteInput<Options, Frame, State>,
+  /** The number of type arguments selects the kind: `<Options>`, `<Options, Frame, State>`, or `<Options, Token>`. */
+  static fromRoute<Options extends SpeechOptions>(
+    route: MediaModel.InlineRouteInput<SpeechRequestFor<Options>, SpeechResponse>,
+    input: MediaRoute.ModelInput,
+  ): SpeechModel<Options>
+  static fromRoute<Options extends SpeechOptions, Frame, State>(
+    route: MediaModel.StreamRouteInput<SpeechRequestFor<Options>, SpeechEvent, Frame, State>,
+    input: MediaRoute.ModelInput,
+  ): SpeechModel<Options>
+  static fromRoute<Options extends SpeechOptions, Token>(
+    route: MediaModel.QueuedRouteInput<SpeechRequestFor<Options>, SpeechResponse, Token>,
+    input: MediaRoute.ModelInput,
+  ): SpeechModel<Options>
+  static fromRoute<Options extends SpeechOptions, Frame, State, Token>(
+    route: MediaModel.AnyRouteInput<SpeechRequestFor<Options>, SpeechEvent, SpeechResponse, Frame, State, Token>,
     input: MediaRoute.ModelInput,
   ) {
     return new SpeechModel<Options>({
       id: input.id,
-      provider: route.provider,
+      provider: route.protocol.provider,
       http: input.http,
-      route: composeRoute(
-        (composition) => MediaRoute.stream({ ...composition, collect: collectResponse }),
-        route,
-        input,
-      ),
+      route: composeRoute(route, input, collectResponse) as SpeechRoute,
     })
   }
 }
 
-export namespace SpeechModel {
-  export type RouteInput<
-    Options extends SpeechOptions = SpeechOptions,
-    Frame = unknown,
-    State = unknown,
-  > = MediaModel.RouteInput<
-    MediaProtocol.Addressed<SpeechRequestFor<Options>>,
-    MediaProtocol.Streamed<SpeechRequestFor<Options>, SpeechEvent, Frame, State>
-  >
-}
-
 export const SpeechModelSchema = Schema.declare((value): value is SpeechModel => value instanceof SpeechModel, {
   expected: "Speech.Model",
 })
@@ -71,7 +57,7 @@ export const SpeechVoice = Schema.Union([Schema.String, Schema.Struct({ id: Sche
 })
 export type SpeechVoice = Schema.Schema.Type<typeof SpeechVoice>
 
-export type SpeechFormat = "mp3" | "wav" | "pcm" | "opus" | "aac" | "flac" | (string & {})
+export type SpeechFormat = OpenString<"mp3" | "wav" | "pcm" | "opus" | "aac" | "flac">
 
 /** Granularity is provider-native: characters on ElevenLabs, words on Cartesia. */
 export const SpeechTimestamp = Schema.Struct({
@@ -148,11 +134,17 @@ export const SpeechFinishEvent = Schema.Struct({
   providerMetadata: Schema.optional(ProviderMetadata),
 }).annotate({ identifier: "Speech.Event.Finish" })
 
-const speechEventTagged = Schema.Union([SpeechAudioDeltaEvent, SpeechTimestampsEvent, SpeechFinishEvent]).pipe(
-  Schema.toTaggedUnion("type"),
-)
+const speechEventTagged = Schema.Union([
+  QueuedEvent,
+  ProgressEvent,
+  SpeechAudioDeltaEvent,
+  SpeechTimestampsEvent,
+  SpeechFinishEvent,
+]).pipe(Schema.toTaggedUnion("type"))
 export const SpeechEvent = Object.assign(speechEventTagged, {
   is: {
+    generationQueued: speechEventTagged.guards["generation-queued"],
+    generationProgress: speechEventTagged.guards["generation-progress"],
     audioDelta: speechEventTagged.guards["audio-delta"],
     timestamps: speechEventTagged.guards.timestamps,
     finish: speechEventTagged.guards.finish,
@@ -188,24 +180,22 @@ export function request(input: SpeechRequest | SpeechRequestInput) {
   if (input instanceof SpeechRequest) return input
   return new SpeechRequest({
     ...input,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+    http: HttpOptions.make(input.http),
   })
 }
 
 const requestEffect = (input: SpeechRequest | SpeechRequestInput) => tryRequest(() => request(input))
 
 export function generate<const Model extends SpeechModel>(
-  input: SpeechRequestInput<Model>,
+  input: SpeechRequest | SpeechRequestInput<Model>,
 ): Effect.Effect<SpeechResponse, AIError, Service>
-export function generate(input: SpeechRequest): Effect.Effect<SpeechResponse, AIError, Service>
 export function generate(input: SpeechRequest | SpeechRequestInput) {
   return requestEffect(input).pipe(Effect.flatMap((request) => SpeechClient.generate(request)))
 }
 
 export function stream<const Model extends SpeechModel>(
-  input: SpeechRequestInput<Model>,
+  input: SpeechRequest | SpeechRequestInput<Model>,
 ): Stream.Stream<SpeechEvent, AIError, Service>
-export function stream(input: SpeechRequest): Stream.Stream<SpeechEvent, AIError, Service>
 export function stream(input: SpeechRequest | SpeechRequestInput) {
   return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => SpeechClient.stream(request))))
 }

packages/ai/src/transcription-client.ts

@@ -1,34 +1,13 @@
-import { Context, Effect, Layer, Stream } from "effect"
-import type { AwaitOptions, Generation } from "./generation.js"
-import { RequestExecutor } from "./route/executor.js"
-import { MediaRoute } from "./route/media.js"
-import type { AIError } from "./schema/index.js"
+import { Context } from "effect"
+import { MediaClient } from "./media-client.js"
 import {
-  responseEvents,
+  TranscriptionFinishEvent,
   type TranscriptionEvent,
-  type TranscriptionModel,
-  type TranscriptionOptions,
   type TranscriptionRequestFor,
   type TranscriptionResponse,
 } from "./transcription.js"
 
-export interface Interface {
-  readonly generate: <Options extends TranscriptionOptions>(
-    request: TranscriptionRequestFor<Options>,
-    options?: AwaitOptions,
-  ) => Effect.Effect<TranscriptionResponse, AIError>
-  readonly stream: <Options extends TranscriptionOptions>(
-    request: TranscriptionRequestFor<Options>,
-    options?: AwaitOptions,
-  ) => Stream.Stream<TranscriptionEvent, AIError>
-  readonly start: <Options extends TranscriptionOptions>(
-    request: TranscriptionRequestFor<Options>,
-  ) => Effect.Effect<Generation<TranscriptionResponse>, AIError>
-  readonly resume: <Options extends TranscriptionOptions>(
-    model: TranscriptionModel<Options>,
-    token: unknown,
-  ) => Effect.Effect<Generation<TranscriptionResponse>, AIError>
-}
+export type Interface = MediaClient.Interface<TranscriptionRequestFor, TranscriptionEvent, TranscriptionResponse>
 
 export class TranscriptionClientService extends Context.Service<TranscriptionClientService, Interface>()(
   "@opencode/TranscriptionClient",
@@ -36,66 +15,10 @@ export class TranscriptionClientService extends Context.Service<TranscriptionCli
 export const Service = TranscriptionClientService
 export type Service = TranscriptionClientService
 
-export const generate = <Options extends TranscriptionOptions>(
-  request: TranscriptionRequestFor<Options>,
-  options?: AwaitOptions,
-): Effect.Effect<TranscriptionResponse, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.generate(request, options)
-  })
-
-export const stream = <Options extends TranscriptionOptions>(
-  request: TranscriptionRequestFor<Options>,
-  options?: AwaitOptions,
-): Stream.Stream<TranscriptionEvent, AIError, Service> =>
-  Stream.unwrap(
-    Effect.gen(function* () {
-      const client = yield* Service
-      return client.stream(request, options)
-    }),
-  )
-
-export const start = <Options extends TranscriptionOptions>(
-  request: TranscriptionRequestFor<Options>,
-): Effect.Effect<Generation<TranscriptionResponse>, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.start(request)
-  })
-
-export const resume = <Options extends TranscriptionOptions>(
-  model: TranscriptionModel<Options>,
-  token: unknown,
-): Effect.Effect<Generation<TranscriptionResponse>, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.resume(model, token)
-  })
-
-export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const executor = yield* RequestExecutor.Service
-    const dispatch = MediaRoute.dispatch<TranscriptionEvent, TranscriptionResponse>({
-      modality: "transcription",
-      execute: executor.execute,
-      responseEvents,
-    })
-    return Service.of({
-      start: (request) => dispatch.start(request.model.route, request),
-      resume: (model, token) => dispatch.resume(model.route, model, token),
-      generate: (request, options) => dispatch.generate(request.model.route, request, options),
-      stream: (request, options) => dispatch.stream(request.model.route, request, options),
-    })
-  }),
-)
-
 export const TranscriptionClient = {
   Service,
-  layer,
-  generate,
-  stream,
-  start,
-  resume,
+  ...MediaClient.make(Service, {
+    modality: "transcription",
+    responseEvents: (response: TranscriptionResponse) => [TranscriptionFinishEvent.make({ ...response })],
+  }),
 } as const

packages/ai/src/transcription.ts

@@ -1,9 +1,8 @@
 import { Effect, Schema, Stream } from "effect"
 import { Generation, ProgressEvent, QueuedEvent, type AwaitOptions } from "./generation.js"
 import { Media } from "./media.js"
-import { MediaModel, composeAnyRoute, tryRequest } from "./media-model.js"
+import { MediaModel, composeRoute, tryRequest } from "./media-model.js"
 import { MediaRoute } from "./route/media.js"
-import type { MediaProtocol } from "./route/media-protocol.js"
 import { AIError, HttpOptions, MediaUsage, ProviderMetadata } from "./schema/index.js"
 import { TranscriptionClient, Service } from "./transcription-client.js"
 
@@ -11,90 +10,49 @@ import { TranscriptionClient, Service } from "./transcription-client.js"
 // Model
 // ---------------------------------------------------------------------------
 
-export type TranscriptionOptions = Record<string, unknown>
+export type TranscriptionOptions = MediaModel.Options
 
-export type TranscriptionRoute<Options extends TranscriptionOptions = TranscriptionOptions> = MediaRoute.AnyRoute<
-  TranscriptionRequestFor<Options>,
-  TranscriptionEvent,
-  TranscriptionResponse
->
+export type TranscriptionRoute = MediaRoute.AnyRoute<TranscriptionRequestFor, TranscriptionEvent, TranscriptionResponse>
 
 export class TranscriptionModel<Options extends TranscriptionOptions = TranscriptionOptions> extends MediaModel<
-  TranscriptionRoute<Options>,
+  TranscriptionRoute,
   Options
 > {
   declare protected readonly _TranscriptionModel: void
 
-  static make<Options extends TranscriptionOptions = TranscriptionOptions>(
-    input: MediaModel.Input<TranscriptionRoute<Options>>,
-  ) {
-    return new TranscriptionModel<Options>(input)
-  }
-
   /** The number of type arguments selects the kind: `<Options>`, `<Options, Frame, State>`, or `<Options, Token>`. */
   static fromRoute<Options extends TranscriptionOptions>(
-    route: TranscriptionModel.InlineRouteInput<Options>,
+    route: MediaModel.InlineRouteInput<TranscriptionRequestFor<Options>, TranscriptionResponse>,
     input: MediaRoute.ModelInput,
   ): TranscriptionModel<Options>
   static fromRoute<Options extends TranscriptionOptions, Frame, State>(
-    route: TranscriptionModel.StreamRouteInput<Options, Frame, State>,
+    route: MediaModel.StreamRouteInput<TranscriptionRequestFor<Options>, TranscriptionEvent, Frame, State>,
     input: MediaRoute.ModelInput,
   ): TranscriptionModel<Options>
   static fromRoute<Options extends TranscriptionOptions, Token>(
-    route: TranscriptionModel.QueuedRouteInput<Options, Token>,
+    route: MediaModel.QueuedRouteInput<TranscriptionRequestFor<Options>, TranscriptionResponse, Token>,
     input: MediaRoute.ModelInput,
   ): TranscriptionModel<Options>
   static fromRoute<Options extends TranscriptionOptions, Frame, State, Token>(
-    route: TranscriptionModel.RouteInput<Options, Frame, State, Token>,
+    route: MediaModel.AnyRouteInput<
+      TranscriptionRequestFor<Options>,
+      TranscriptionEvent,
+      TranscriptionResponse,
+      Frame,
+      State,
+      Token
+    >,
     input: MediaRoute.ModelInput,
   ) {
     return new TranscriptionModel<Options>({
       id: input.id,
-      provider: route.provider,
+      provider: route.protocol.provider,
       http: input.http,
-      route: composeAnyRoute(route, input, collectResponse),
+      route: composeRoute(route, input, collectResponse) as TranscriptionRoute,
     })
   }
 }
 
-export namespace TranscriptionModel {
-  export type InlineRouteInput<Options extends TranscriptionOptions = TranscriptionOptions> = MediaModel.RouteInput<
-    TranscriptionRequestFor<Options>,
-    MediaProtocol.Inline<TranscriptionRequestFor<Options>, TranscriptionResponse>
-  >
-
-  export type StreamRouteInput<
-    Options extends TranscriptionOptions = TranscriptionOptions,
-    Frame = unknown,
-    State = unknown,
-  > = MediaModel.RouteInput<
-    MediaProtocol.Addressed<TranscriptionRequestFor<Options>>,
-    MediaProtocol.Streamed<TranscriptionRequestFor<Options>, TranscriptionEvent, Frame, State>
-  >
-
-  export type QueuedRouteInput<
-    Options extends TranscriptionOptions = TranscriptionOptions,
-    Token = unknown,
-  > = MediaModel.RouteInput<
-    TranscriptionRequestFor<Options>,
-    MediaProtocol.Queued<TranscriptionRequestFor<Options>, TranscriptionResponse, Token>
-  >
-
-  export type RouteInput<
-    Options extends TranscriptionOptions = TranscriptionOptions,
-    Frame = unknown,
-    State = unknown,
-    Token = unknown,
-  > = MediaModel.AnyRouteInput<
-    TranscriptionRequestFor<Options>,
-    TranscriptionEvent,
-    TranscriptionResponse,
-    Frame,
-    State,
-    Token
-  >
-}
-
 export const TranscriptionModelSchema = Schema.declare(
   (value): value is TranscriptionModel => value instanceof TranscriptionModel,
   { expected: "Transcription.Model" },
@@ -212,10 +170,6 @@ export const TranscriptionEvent = Object.assign(transcriptionEventTagged, {
 })
 export type TranscriptionEvent = Schema.Schema.Type<typeof transcriptionEventTagged>
 
-export const responseEvents = (response: TranscriptionResponse): ReadonlyArray<TranscriptionEvent> => [
-  TranscriptionFinishEvent.make({ ...response }),
-]
-
 const collectResponse = (events: ReadonlyArray<TranscriptionEvent>): Effect.Effect<TranscriptionResponse> => {
   const finish = events.find(TranscriptionEvent.is.finish)
   // Every transcription protocol's `finish` emits the terminal event or fails, so a completed stream always has one.
@@ -236,18 +190,14 @@ export function request(input: TranscriptionRequest | TranscriptionRequestInput)
   if (input instanceof TranscriptionRequest) return input
   return new TranscriptionRequest({
     ...input,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+    http: HttpOptions.make(input.http),
   })
 }
 
 const requestEffect = (input: TranscriptionRequest | TranscriptionRequestInput) => tryRequest(() => request(input))
 
 export function generate<const Model extends TranscriptionModel>(
-  input: TranscriptionRequestInput<Model>,
-  options?: AwaitOptions,
-): Effect.Effect<TranscriptionResponse, AIError, Service>
-export function generate(
-  input: TranscriptionRequest,
+  input: TranscriptionRequest | TranscriptionRequestInput<Model>,
   options?: AwaitOptions,
 ): Effect.Effect<TranscriptionResponse, AIError, Service>
 export function generate(input: TranscriptionRequest | TranscriptionRequestInput, options?: AwaitOptions) {
@@ -255,11 +205,7 @@ export function generate(input: TranscriptionRequest | TranscriptionRequestInput
 }
 
 export function stream<const Model extends TranscriptionModel>(
-  input: TranscriptionRequestInput<Model>,
-  options?: AwaitOptions,
-): Stream.Stream<TranscriptionEvent, AIError, Service>
-export function stream(
-  input: TranscriptionRequest,
+  input: TranscriptionRequest | TranscriptionRequestInput<Model>,
   options?: AwaitOptions,
 ): Stream.Stream<TranscriptionEvent, AIError, Service>
 export function stream(input: TranscriptionRequest | TranscriptionRequestInput, options?: AwaitOptions) {
@@ -268,15 +214,14 @@ export function stream(input: TranscriptionRequest | TranscriptionRequestInput,
 
 /** Inline and streaming routes fail with `UnsupportedOperation`. */
 export function start<const Model extends TranscriptionModel>(
-  input: TranscriptionRequestInput<Model>,
+  input: TranscriptionRequest | TranscriptionRequestInput<Model>,
 ): Effect.Effect<Generation<TranscriptionResponse>, AIError, Service>
-export function start(input: TranscriptionRequest): Effect.Effect<Generation<TranscriptionResponse>, AIError, Service>
 export function start(input: TranscriptionRequest | TranscriptionRequestInput) {
   return requestEffect(input).pipe(Effect.flatMap((request) => TranscriptionClient.start(request)))
 }
 
-export const resume = <Options extends TranscriptionOptions>(
-  model: TranscriptionModel<Options>,
+export const resume = (
+  model: TranscriptionModel,
   token: unknown,
 ): Effect.Effect<Generation<TranscriptionResponse>, AIError, Service> => TranscriptionClient.resume(model, token)
 

packages/ai/src/utils/json.ts

@@ -0,0 +1,5 @@
+import { Schema } from "effect"
+
+export const Json = Schema.fromJsonString(Schema.Unknown)
+export const decodeJson = Schema.decodeUnknownSync(Json)
+export const encodeJson = Schema.encodeSync(Json)

packages/ai/src/video-client.ts

@@ -1,98 +1,30 @@
-import { Context, Effect, Layer, Stream } from "effect"
-import { resultEvents, type AwaitOptions, type Generation } from "./generation.js"
-import { RequestExecutor } from "./route/executor.js"
-import type { AIError } from "./schema/index.js"
+import { Context } from "effect"
+import { MediaClient } from "./media-client.js"
 import {
-  responseEvents,
+  VideoOutputEvent,
+  VideoFinishEvent,
   type VideoEvent,
-  type VideoModel,
-  type VideoOptions,
   type VideoRequestFor,
   type VideoResponse,
 } from "./video.js"
 
-export interface Interface {
-  readonly start: <Options extends VideoOptions>(
-    request: VideoRequestFor<Options>,
-  ) => Effect.Effect<Generation<VideoResponse>, AIError>
-  readonly resume: <Options extends VideoOptions>(
-    model: VideoModel<Options>,
-    token: unknown,
-  ) => Effect.Effect<Generation<VideoResponse>, AIError>
-  readonly generate: <Options extends VideoOptions>(
-    request: VideoRequestFor<Options>,
-    options?: AwaitOptions,
-  ) => Effect.Effect<VideoResponse, AIError>
-  readonly stream: <Options extends VideoOptions>(
-    request: VideoRequestFor<Options>,
-    options?: AwaitOptions,
-  ) => Stream.Stream<VideoEvent, AIError>
-}
+export type Interface = MediaClient.Interface<VideoRequestFor, VideoEvent, VideoResponse>
 
 export class VideoClientService extends Context.Service<VideoClientService, Interface>()("@opencode/VideoClient") {}
 export const Service = VideoClientService
 export type Service = VideoClientService
 
-export const start = <Options extends VideoOptions>(
-  request: VideoRequestFor<Options>,
-): Effect.Effect<Generation<VideoResponse>, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.start(request)
-  })
-
-export const resume = <Options extends VideoOptions>(
-  model: VideoModel<Options>,
-  token: unknown,
-): Effect.Effect<Generation<VideoResponse>, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.resume(model, token)
-  })
-
-export const generate = <Options extends VideoOptions>(
-  request: VideoRequestFor<Options>,
-  options?: AwaitOptions,
-): Effect.Effect<VideoResponse, AIError, Service> =>
-  Effect.gen(function* () {
-    const client = yield* Service
-    return yield* client.generate(request, options)
-  })
-
-export const stream = <Options extends VideoOptions>(
-  request: VideoRequestFor<Options>,
-  options?: AwaitOptions,
-): Stream.Stream<VideoEvent, AIError, Service> =>
-  Stream.unwrap(
-    Effect.gen(function* () {
-      const client = yield* Service
-      return client.stream(request, options)
-    }),
-  )
-
-export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const executor = yield* RequestExecutor.Service
-    const start = <Options extends VideoOptions>(request: VideoRequestFor<Options>) =>
-      request.model.route.start(request, executor.execute)
-    return Service.of({
-      start,
-      resume: (model, token) => model.route.resume(model, token, executor.execute),
-      generate: (request, options) => start(request).pipe(Effect.flatMap((generation) => generation.await(options))),
-      stream: (request, options) =>
-        Stream.unwrap(
-          start(request).pipe(Effect.map((generation) => resultEvents(generation, responseEvents, options))),
-        ),
-    })
-  }),
-)
-
 export const VideoClient = {
   Service,
-  layer,
-  start,
-  resume,
-  generate,
-  stream,
+  ...MediaClient.make(Service, {
+    modality: "video",
+    responseEvents: (response: VideoResponse) => [
+      ...response.videos.map((video, index) => VideoOutputEvent.make({ index, video })),
+      VideoFinishEvent.make({
+        usage: response.usage,
+        notices: response.notices,
+        providerMetadata: response.providerMetadata,
+      }),
+    ],
+  }),
 } as const

packages/ai/src/video.ts

@@ -3,49 +3,46 @@ import { Generation, ProgressEvent, QueuedEvent, type AwaitOptions } from "./gen
 import { Media } from "./media.js"
 import { MediaModel, composeRoute, tryRequest } from "./media-model.js"
 import { MediaRoute } from "./route/media.js"
-import type { MediaProtocol } from "./route/media-protocol.js"
-import { AIError, HttpOptions, MediaUsage, ProviderMetadata } from "./schema/index.js"
+import { AIError, HttpOptions, MediaUsage, ProviderMetadata, type OpenString } from "./schema/index.js"
 import { VideoClient, Service } from "./video-client.js"
 
 // ---------------------------------------------------------------------------
 // Model
 // ---------------------------------------------------------------------------
 
-export type VideoOptions = Record<string, unknown>
+export type VideoOptions = MediaModel.Options
 
-export type VideoRoute<Options extends VideoOptions = VideoOptions> = MediaRoute.QueuedRoute<
-  VideoRequestFor<Options>,
-  VideoResponse
->
+export type VideoRoute = MediaRoute.AnyRoute<VideoRequestFor, VideoEvent, VideoResponse>
 
-export class VideoModel<Options extends VideoOptions = VideoOptions> extends MediaModel<VideoRoute<Options>, Options> {
+export class VideoModel<Options extends VideoOptions = VideoOptions> extends MediaModel<VideoRoute, Options> {
   declare protected readonly _VideoModel: void
 
-  static make<Options extends VideoOptions = VideoOptions>(input: MediaModel.Input<VideoRoute<Options>>) {
-    return new VideoModel<Options>(input)
-  }
-
-  /** Compose a queued video protocol with its canonical start path into a model for one deployment. */
-  static fromRoute<Options extends VideoOptions = VideoOptions, Token = unknown>(
-    route: VideoModel.RouteInput<Options, Token>,
+  /** The number of type arguments selects the kind: `<Options>`, `<Options, Frame, State>`, or `<Options, Token>`. */
+  static fromRoute<Options extends VideoOptions>(
+    route: MediaModel.InlineRouteInput<VideoRequestFor<Options>, VideoResponse>,
+    input: MediaRoute.ModelInput,
+  ): VideoModel<Options>
+  static fromRoute<Options extends VideoOptions, Frame, State>(
+    route: MediaModel.StreamRouteInput<VideoRequestFor<Options>, VideoEvent, Frame, State>,
+    input: MediaRoute.ModelInput,
+  ): VideoModel<Options>
+  static fromRoute<Options extends VideoOptions, Token>(
+    route: MediaModel.QueuedRouteInput<VideoRequestFor<Options>, VideoResponse, Token>,
+    input: MediaRoute.ModelInput,
+  ): VideoModel<Options>
+  static fromRoute<Options extends VideoOptions, Frame, State, Token>(
+    route: MediaModel.AnyRouteInput<VideoRequestFor<Options>, VideoEvent, VideoResponse, Frame, State, Token>,
     input: MediaRoute.ModelInput,
   ) {
     return new VideoModel<Options>({
       id: input.id,
-      provider: route.provider,
+      provider: route.protocol.provider,
       http: input.http,
-      route: composeRoute(MediaRoute.queued, route, input),
+      route: composeRoute(route, input, collectResponse) as VideoRoute,
     })
   }
 }
 
-export namespace VideoModel {
-  export type RouteInput<Options extends VideoOptions = VideoOptions, Token = unknown> = MediaModel.RouteInput<
-    VideoRequestFor<Options>,
-    MediaProtocol.Queued<VideoRequestFor<Options>, VideoResponse, Token>
-  >
-}
-
 export const VideoModelSchema = Schema.declare((value): value is VideoModel => value instanceof VideoModel, {
   expected: "Video.Model",
 })
@@ -57,7 +54,7 @@ export const VideoModelSchema = Schema.declare((value): value is VideoModel => v
 export type VideoAspectRatio = Media.AspectRatio
 export const VideoAspectRatio = Media.AspectRatio
 
-export type VideoResolution = "480p" | "720p" | "1080p" | "4k" | (string & {})
+export type VideoResolution = OpenString<"480p" | "720p" | "1080p" | "4k">
 
 /** Pinned frames. Routes that accept only a first frame fail typed when `last` is present. */
 export const VideoFrames = Schema.Struct({
@@ -149,15 +146,19 @@ export const VideoEvent = Object.assign(videoEventTagged, {
 })
 export type VideoEvent = Schema.Schema.Type<typeof videoEventTagged>
 
-/** A completed response expanded into the streaming event shape. */
-export const responseEvents = (response: VideoResponse): ReadonlyArray<VideoEvent> => [
-  ...response.videos.map((video, index) => VideoOutputEvent.make({ index, video })),
-  VideoFinishEvent.make({
-    usage: response.usage,
-    notices: response.notices,
-    providerMetadata: response.providerMetadata,
-  }),
-]
+const collectResponse = (events: ReadonlyArray<VideoEvent>): Effect.Effect<VideoResponse> => {
+  const finish = events.find(VideoEvent.is.finish)
+  // A streaming video protocol's `finish` emits the terminal event or fails, so a completed stream always has one.
+  if (finish === undefined) return Effect.die(new Error("The video stream completed without a finish event"))
+  return Effect.succeed(
+    new VideoResponse({
+      videos: events.filter(VideoEvent.is.video).map((event) => event.video),
+      usage: finish.usage,
+      notices: finish.notices,
+      providerMetadata: finish.providerMetadata,
+    }),
+  )
+}
 
 // ---------------------------------------------------------------------------
 // Request-shaped call API
@@ -171,40 +172,35 @@ export function request(input: VideoRequest | VideoRequestInput) {
   if (input instanceof VideoRequest) return input
   return new VideoRequest({
     ...input,
-    http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+    http: HttpOptions.make(input.http),
   })
 }
 
 const requestEffect = (input: VideoRequest | VideoRequestInput) => tryRequest(() => request(input))
 
 export function start<const Model extends VideoModel>(
-  input: VideoRequestInput<Model>,
+  input: VideoRequest | VideoRequestInput<Model>,
 ): Effect.Effect<Generation<VideoResponse>, AIError, Service>
-export function start(input: VideoRequest): Effect.Effect<Generation<VideoResponse>, AIError, Service>
 export function start(input: VideoRequest | VideoRequestInput) {
   return requestEffect(input).pipe(Effect.flatMap((request) => VideoClient.start(request)))
 }
 
 export function generate<const Model extends VideoModel>(
-  input: VideoRequestInput<Model>,
+  input: VideoRequest | VideoRequestInput<Model>,
   options?: AwaitOptions,
 ): Effect.Effect<VideoResponse, AIError, Service>
-export function generate(input: VideoRequest, options?: AwaitOptions): Effect.Effect<VideoResponse, AIError, Service>
 export function generate(input: VideoRequest | VideoRequestInput, options?: AwaitOptions) {
   return requestEffect(input).pipe(Effect.flatMap((request) => VideoClient.generate(request, options)))
 }
 
 /** Rebuild a generation handle from a persisted `Generation.token`, refreshing its status once. */
-export const resume = <Options extends VideoOptions>(
-  model: VideoModel<Options>,
-  token: unknown,
-): Effect.Effect<Generation<VideoResponse>, AIError, Service> => VideoClient.resume(model, token)
+export const resume = (model: VideoModel, token: unknown): Effect.Effect<Generation<VideoResponse>, AIError, Service> =>
+  VideoClient.resume(model, token)
 
 export function stream<const Model extends VideoModel>(
-  input: VideoRequestInput<Model>,
+  input: VideoRequest | VideoRequestInput<Model>,
   options?: AwaitOptions,
 ): Stream.Stream<VideoEvent, AIError, Service>
-export function stream(input: VideoRequest, options?: AwaitOptions): Stream.Stream<VideoEvent, AIError, Service>
 export function stream(input: VideoRequest | VideoRequestInput, options?: AwaitOptions) {
   return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => VideoClient.stream(request, options))))
 }

packages/ai/test/compile.test.ts

@@ -144,7 +144,7 @@ describe("request option precedence", () => {
           type: "function",
           name: "crm",
           description: "Top-level CRM tool",
-          parameters: {},
+          parameters: { type: "object" },
           strict: false,
         },
         {
@@ -152,15 +152,17 @@ describe("request option precedence", () => {
           name: "crm",
           description: "CRM tools",
           tools: [
-            { type: "function", name: "lookup", description: "new", parameters: {}, strict: false },
-            { type: "function", name: "search", description: "search", parameters: {}, strict: false },
+            { type: "function", name: "lookup", description: "new", parameters: { type: "object" }, strict: false },
+            { type: "function", name: "search", description: "search", parameters: { type: "object" }, strict: false },
           ],
         },
         {
           type: "namespace",
           name: "support",
           description: "Support tools",
-          tools: [{ type: "function", name: "lookup", description: "support", parameters: {}, strict: false }],
+          tools: [
+            { type: "function", name: "lookup", description: "support", parameters: { type: "object" }, strict: false },
+          ],
         },
       ])
     }),

packages/ai/test/exports.test.ts

@@ -54,6 +54,19 @@ import { TestLLM } from "@opencode/ai/testing"
 import { Evaluation, EvaluationClient } from "@opencode/ai/experimental"
 
 describe("public exports", () => {
+  test("modality, provider, and protocol entrypoints load first in a fresh process", async () => {
+    const results = await Promise.all(
+      ["image", "video", "speech", "transcription", "providers", "protocols"].map(async (entry) => {
+        const child = Bun.spawn(
+          [process.execPath, "-e", `await import(${JSON.stringify(`${import.meta.dir}/../src/${entry}.ts`)})`],
+          { stderr: "pipe" },
+        )
+        return { entry, exitCode: await child.exited, stderr: await new Response(child.stderr).text() }
+      }),
+    )
+    expect(results.filter((result) => result.exitCode !== 0)).toEqual([])
+  })
+
   test("root exposes app-facing runtime APIs", () => {
     expect(LLM.request).toBeFunction()
     expect(LLMClient.Service).toBeFunction()

packages/ai/test/fixtures/recordings/openai-responses-websocket/continues-a-tool-call-over-one-socket.json

@@ -30,7 +30,7 @@
         {
           "direction": "client",
           "kind": "text",
-          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"What is the weather in Paris?\"}]}],\"instructions\":\"Call get_weather once, then reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":50}"
+          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"What is the weather in Paris?\"}]}],\"instructions\":\"Call get_weather once, then reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":50}"
         },
         {
           "direction": "server",
@@ -525,7 +525,7 @@
         {
           "direction": "client",
           "kind": "text",
-          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"function_call_output\",\"call_id\":\"call_hejtTYDa1IfLyNIzb3fq9gJs\",\"output\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}],\"instructions\":\"Call get_weather once, then reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":50,\"previous_response_id\":\"resp_0d9a44b6df400533016aa8c8e36de887d1be260913d131b2ca\"}"
+          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"function_call_output\",\"call_id\":\"call_hejtTYDa1IfLyNIzb3fq9gJs\",\"output\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}],\"instructions\":\"Call get_weather once, then reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":50,\"previous_response_id\":\"resp_0d9a44b6df400533016aa8c8e36de887d1be260913d131b2ca\"}"
         },
         {
           "direction": "server",

packages/ai/test/fixtures/recordings/openai-responses-websocket/reconstructs-full-context-after-reconnect.json

@@ -30,7 +30,7 @@
         {
           "direction": "client",
           "kind": "text",
-          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Alpha.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":30}"
+          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Alpha.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":30}"
         },
         {
           "direction": "server",
@@ -109,7 +109,7 @@
         {
           "direction": "client",
           "kind": "text",
-          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Alpha.\"}]},{\"type\":\"reasoning\",\"id\":\"rs_0a6277dd90b94da1016aa8c946e33487d1b725d8e9dc874d82\",\"summary\":[],\"encrypted_content\":\"gAAAAABqqMlHtG6yltzgW_UjUcYxvl2hoMkk7cSEH5SJMe9CR5gKIaCwCh4peUo8XZrd-EU-tPCXthv7JzHxYXGVG1fIgTJ7BjBoOh-jgd_oGlyCHj2jVPj7nVoB763tZHdyw_ovL3V7GpJ6VeLGIsRGqNTnBz47ZuKikTKrbTDupn6fT2wOM_69zwdg4-UVnoF2J9E_jIS0E5XRtRwOidqANl61HCwo7LV-Ut1aqCbXb-59vkrVGWPxD_8n4smf7Qjywc0FCH9zwuEDX4cPdqj3MmjvYPrn0jand9LKkAy9rblaKFJSQfVuritbHrdQrnF7hLxu7QCpehOzNXOkpNEqTmXnAZjfMc53hq-ahH6_KoyYlZpompwyGPngFeI2fKRqP8rlpDilD1BHBsh-bl7kXzI8HQ_jameXwPZ1La6gjtFkThXp53BD6BOx11SB9Nypqolu2at5rR32UYcGrYeGtTu-HmYGp0oHVFkHumTNuHKmGXV14dI9swgryfygLhX8EAJrWrjm3e8rvAkHKpAZ0IkmlCcp15UCFDKNeS560fQVRaKXWnQ7m0Ih3C1xG0ifJ89j27c8GHo1kAhEJk-lSB1-FZr9Ls_w7N772kmZ2a7LLswu3kNW78kPas_CtcOnBOHwE1DhcVh5YpxwNftOHZnK1v8NPNF8EWqio4ArZy1thMCzH5zXBNcFzgd8tePMFukBblSP8QGQoVYRqTne2sFoOZXjslXnDvEe-Ycj8X38zWgRiwAk7guOloFC7Se36KCDP357773Vah86gWCt55mSEyhVW_GF1oTuHvJ18GZsXcyN21scF1PSr8YaCM_jR7ZkU1GYXbQK2Y4oTAV9XDptQA5YzEREnn7muC_6v5ZTAglZF1lhn9Q0NwmylZEAXJdSGHaqXt1Hv-vQlprA_9m22vrreBOTLPnVK946J8absKrwfe-jK_1n_9YQR43uwH8XwFBFND0c4lICCQGbxwM8pX4ACWR0c19aORCYm-M5FrJsxmG29_aDVNhcvkoQ3mlP7ITQeqzkrjfytSwLb2BYpXYZKjEHNfV9j3JoxJobUkK5hrxXBhTvZzbVBnE0LSXQNwR-JAcOliP_jXBEeQ-28B-aGW8TI1vEP2i260QKgzOzPC-pOoFp0-vCvxojNO0kE16ECVTLfDNLNGSMZs9vekdLJP2akBp6PsUXsQUTbWO_wr1E2oNU7ctfMRxoh-yP0ZW2_xz_NjE72O5LF_6zuDVV7Q==\"},{\"type\":\"message\",\"id\":\"msg_0a6277dd90b94da1016aa8c947253887d184c150fcbcbcd8da\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Alpha.\"}],\"phase\":\"final_answer\",\"status\":\"completed\"},{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Beta.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":30}"
+          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Alpha.\"}]},{\"type\":\"reasoning\",\"id\":\"rs_0a6277dd90b94da1016aa8c946e33487d1b725d8e9dc874d82\",\"summary\":[],\"encrypted_content\":\"gAAAAABqqMlHtG6yltzgW_UjUcYxvl2hoMkk7cSEH5SJMe9CR5gKIaCwCh4peUo8XZrd-EU-tPCXthv7JzHxYXGVG1fIgTJ7BjBoOh-jgd_oGlyCHj2jVPj7nVoB763tZHdyw_ovL3V7GpJ6VeLGIsRGqNTnBz47ZuKikTKrbTDupn6fT2wOM_69zwdg4-UVnoF2J9E_jIS0E5XRtRwOidqANl61HCwo7LV-Ut1aqCbXb-59vkrVGWPxD_8n4smf7Qjywc0FCH9zwuEDX4cPdqj3MmjvYPrn0jand9LKkAy9rblaKFJSQfVuritbHrdQrnF7hLxu7QCpehOzNXOkpNEqTmXnAZjfMc53hq-ahH6_KoyYlZpompwyGPngFeI2fKRqP8rlpDilD1BHBsh-bl7kXzI8HQ_jameXwPZ1La6gjtFkThXp53BD6BOx11SB9Nypqolu2at5rR32UYcGrYeGtTu-HmYGp0oHVFkHumTNuHKmGXV14dI9swgryfygLhX8EAJrWrjm3e8rvAkHKpAZ0IkmlCcp15UCFDKNeS560fQVRaKXWnQ7m0Ih3C1xG0ifJ89j27c8GHo1kAhEJk-lSB1-FZr9Ls_w7N772kmZ2a7LLswu3kNW78kPas_CtcOnBOHwE1DhcVh5YpxwNftOHZnK1v8NPNF8EWqio4ArZy1thMCzH5zXBNcFzgd8tePMFukBblSP8QGQoVYRqTne2sFoOZXjslXnDvEe-Ycj8X38zWgRiwAk7guOloFC7Se36KCDP357773Vah86gWCt55mSEyhVW_GF1oTuHvJ18GZsXcyN21scF1PSr8YaCM_jR7ZkU1GYXbQK2Y4oTAV9XDptQA5YzEREnn7muC_6v5ZTAglZF1lhn9Q0NwmylZEAXJdSGHaqXt1Hv-vQlprA_9m22vrreBOTLPnVK946J8absKrwfe-jK_1n_9YQR43uwH8XwFBFND0c4lICCQGbxwM8pX4ACWR0c19aORCYm-M5FrJsxmG29_aDVNhcvkoQ3mlP7ITQeqzkrjfytSwLb2BYpXYZKjEHNfV9j3JoxJobUkK5hrxXBhTvZzbVBnE0LSXQNwR-JAcOliP_jXBEeQ-28B-aGW8TI1vEP2i260QKgzOzPC-pOoFp0-vCvxojNO0kE16ECVTLfDNLNGSMZs9vekdLJP2akBp6PsUXsQUTbWO_wr1E2oNU7ctfMRxoh-yP0ZW2_xz_NjE72O5LF_6zuDVV7Q==\"},{\"type\":\"message\",\"id\":\"msg_0a6277dd90b94da1016aa8c947253887d184c150fcbcbcd8da\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Alpha.\"}],\"phase\":\"final_answer\",\"status\":\"completed\"},{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Beta.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":30}"
         },
         {
           "direction": "server",

packages/ai/test/fixtures/recordings/openai-responses-websocket/recovers-from-explicit-continuation-rejection.json

@@ -30,7 +30,7 @@
         {
           "direction": "client",
           "kind": "text",
-          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Ready.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":30}"
+          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Ready.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":30}"
         },
         {
           "direction": "server",
@@ -109,7 +109,7 @@
         {
           "direction": "client",
           "kind": "text",
-          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Recovered.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":30,\"previous_response_id\":\"resp_01cc0cda24c36acf016aa8ca3c1d3c87d1853283f43675e411\"}"
+          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Recovered.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":30,\"previous_response_id\":\"resp_01cc0cda24c36acf016aa8ca3c1d3c87d1853283f43675e411\"}"
         },
         {
           "direction": "server",
@@ -119,7 +119,7 @@
         {
           "direction": "client",
           "kind": "text",
-          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Ready.\"}]},{\"type\":\"reasoning\",\"id\":\"rs_01cc0cda24c36acf016aa8ca3ced8c87d1a14c5c6a2ced8544\",\"summary\":[],\"encrypted_content\":\"gAAAAABqqMo9M9B15LsV1CLsXpNJpI08GiwCAK97hTheQ2s1lAkKgARMs1HIIXVeAr-tbUq88yN51fiQE8HvGwdF9ZcNI6bZle8D2PS7m8O7UE7C1Z_HX_fz2f0pRHyRfWpVAT2gYQWIDeZu6UdgxbKPBW0lXWzlk_relHG5x6nXkYzZoEeVasqavWoyMMSX7cexe-IYJh6e_3DgRpOchueS8Z-70P0w5R83Ea7UXZQNhMA0yDEYu_td2PmE2Pd2PUTOB3mxF2pb1z7-2t6S0UryhHx0az7Gh2eT60GGUqz9CIZzNE_FX--tszeuO0eI92Cen5tirOUHBTyyDqE0eG26DRl_p_U-xDZwaQONbtYbvkvrj-G7FA2oZXxjJPHuQZsNgBslXS-H0KT1lx3Y8XJ9QMVjFLFaucFG64wCmXPfCH8dYtX_YqfYQR4lwNfiSbyJEX2oDvTVVD_aCJ9NRo7c0aCTtmKBvr6fvvAy3MAFxAp_Sm2nMx4P5GYO4qAmJDByywKw-VK1vHlv3NRmVsAgbArIFgm-axoCs2PLpvZjDqeQGPavaq8zKWTyZYqBsEzKZUtGOZfYjD4mud0Z08I4i2H4K-L00ccVauode3548ZipOIuslbhJxonQXsF6TFdW2Hj8E5JjoEr5IbmwHyI0PBcDWW5AmkjHLwr9v08mFppRoD-2wzPAd5igROAuUbvJhiQd2A-uOaohwMjdpFxrjyUqgGTlI5g7tmI1ceeQWms0bKm8Pd0wIqVM3Nq6YvV7XfEyeogfRMVUQezr_lES42ZMVAoKBSFzMysDwCFkhVNVclcTUpcUUbVp21FChG7Ag-xuq8Cl6OGLA8nWX1C0aCf2HNa-n3dkYr1DtUziurh1MD-UIs5jdGiq3ptrc0VaVZwNdD4jVfAoHB_Ws7GiISXuclfpqsG3DTJEfzlbukI1vxXrt3FArsHiQvQjW5UM7gGel32M6p8AlXRxnez9PgIuU1WrtBUJetk7m39AZwp_aqbqC-AJ-MF70xP1VJZwFN-GeNL3VZsRHePFG4h7Pj---CCZRGlmzuE1-b-sIE7Bn_gbue_qHFMZJhAY55MO25vfZbSoLWHZCGmLMjJVHOYCPoy6l7zyxNmoIcC58QILNWal31KLCDmCsASmZC-xQRjyFwt-kvLbvk38Dc02IKcP3ujhf6WRRr1A0hh1K-gXmv_XI_MUFDcOVIjjhB-rXgjWSCoKfaKI9GCIsb9mnNaBq65BWg==\"},{\"type\":\"message\",\"id\":\"msg_01cc0cda24c36acf016aa8ca3d4a0087d1950121aed4802434\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Ready.\"}],\"phase\":\"final_answer\",\"status\":\"completed\"},{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Recovered.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":30}"
+          "body": "{\"type\":\"response.create\",\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Ready.\"}]},{\"type\":\"reasoning\",\"id\":\"rs_01cc0cda24c36acf016aa8ca3ced8c87d1a14c5c6a2ced8544\",\"summary\":[],\"encrypted_content\":\"gAAAAABqqMo9M9B15LsV1CLsXpNJpI08GiwCAK97hTheQ2s1lAkKgARMs1HIIXVeAr-tbUq88yN51fiQE8HvGwdF9ZcNI6bZle8D2PS7m8O7UE7C1Z_HX_fz2f0pRHyRfWpVAT2gYQWIDeZu6UdgxbKPBW0lXWzlk_relHG5x6nXkYzZoEeVasqavWoyMMSX7cexe-IYJh6e_3DgRpOchueS8Z-70P0w5R83Ea7UXZQNhMA0yDEYu_td2PmE2Pd2PUTOB3mxF2pb1z7-2t6S0UryhHx0az7Gh2eT60GGUqz9CIZzNE_FX--tszeuO0eI92Cen5tirOUHBTyyDqE0eG26DRl_p_U-xDZwaQONbtYbvkvrj-G7FA2oZXxjJPHuQZsNgBslXS-H0KT1lx3Y8XJ9QMVjFLFaucFG64wCmXPfCH8dYtX_YqfYQR4lwNfiSbyJEX2oDvTVVD_aCJ9NRo7c0aCTtmKBvr6fvvAy3MAFxAp_Sm2nMx4P5GYO4qAmJDByywKw-VK1vHlv3NRmVsAgbArIFgm-axoCs2PLpvZjDqeQGPavaq8zKWTyZYqBsEzKZUtGOZfYjD4mud0Z08I4i2H4K-L00ccVauode3548ZipOIuslbhJxonQXsF6TFdW2Hj8E5JjoEr5IbmwHyI0PBcDWW5AmkjHLwr9v08mFppRoD-2wzPAd5igROAuUbvJhiQd2A-uOaohwMjdpFxrjyUqgGTlI5g7tmI1ceeQWms0bKm8Pd0wIqVM3Nq6YvV7XfEyeogfRMVUQezr_lES42ZMVAoKBSFzMysDwCFkhVNVclcTUpcUUbVp21FChG7Ag-xuq8Cl6OGLA8nWX1C0aCf2HNa-n3dkYr1DtUziurh1MD-UIs5jdGiq3ptrc0VaVZwNdD4jVfAoHB_Ws7GiISXuclfpqsG3DTJEfzlbukI1vxXrt3FArsHiQvQjW5UM7gGel32M6p8AlXRxnez9PgIuU1WrtBUJetk7m39AZwp_aqbqC-AJ-MF70xP1VJZwFN-GeNL3VZsRHePFG4h7Pj---CCZRGlmzuE1-b-sIE7Bn_gbue_qHFMZJhAY55MO25vfZbSoLWHZCGmLMjJVHOYCPoy6l7zyxNmoIcC58QILNWal31KLCDmCsASmZC-xQRjyFwt-kvLbvk38Dc02IKcP3ujhf6WRRr1A0hh1K-gXmv_XI_MUFDcOVIjjhB-rXgjWSCoKfaKI9GCIsb9mnNaBq65BWg==\"},{\"type\":\"message\",\"id\":\"msg_01cc0cda24c36acf016aa8ca3d4a0087d1950121aed4802434\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Ready.\"}],\"phase\":\"final_answer\",\"status\":\"completed\"},{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply exactly: Recovered.\"}]}],\"instructions\":\"Follow the user's exact reply instruction.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":30}"
         },
         {
           "direction": "server",

packages/ai/test/fixtures/recordings/openai-responses/openai-responses-gpt-5-5-reasoning-continuation.json

@@ -26,7 +26,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Think briefly, then reply exactly with: Hello!\"}]}],\"instructions\":\"Show concise reasoning when the provider supports visible reasoning summaries.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"low\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":120,\"stream\":true}"
+        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Think briefly, then reply exactly with: Hello!\"}]}],\"instructions\":\"Show concise reasoning when the provider supports visible reasoning summaries.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"low\",\"summary\":\"auto\"},\"max_output_tokens\":120,\"stream\":true}"
       },
       "response": {
         "status": 200,
@@ -44,7 +44,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Think briefly, then reply exactly with: Hello!\"}]},{\"type\":\"reasoning\",\"id\":\"rs_052e7ec551f55289016aa8c8d63eac87d19d6b921611f123e7\",\"summary\":[],\"encrypted_content\":\"gAAAAABqqMjWZ2Eei8_Gf-5FeEFAYp-gSzFL4D4lQBKL_fyyTYXv5iJ-2jql1mOq0wZpqHL8O9MWxebQGW56Ahd-p21qrDD52CyUBqKKlF87eC1d-cTgjXQlFMsPxvwyQeuU6A2l8tanTtJ48sKtzZtHrDuBXZ35u-lONnovjFGMX3Q83xoqG_um_w5rT420TA_SyU4fGt7oiQvOPS1q4PNo97O824oRnI7n_BC1jPYCaJhl2I1rPJg4afuOpjG-u7JcXRD4JPwZdqMa5o2d0uDKHuUYwP25qiPKKDqTTqFka5cDJjZNPF3ZkVHR-cagjZGvMnizXXxgUpPJ9j83gqY4QJLKCkzcaBj9H7mAL-v9yl4I5kn_9_DhpMILs2SZkC8AvIYNgmel3sDV_BG4XZ2JXciZz86ukQ6DwXgQqS4HOB91g-sGHOWMU1ohsZlEvvJBjGkJ_rAdXVMqAbvi2zvE3_NI4sTAGUrIugGJePrQYTe8gqL8f9NsYac6pzHNQL1e_jQNUvp49bu7EsPzCP3KPYVvZCFohDdwe7sMd6wrztrCJwM4CLdAQK61A7sYzU0HyglLtPidmS5QkSmV6U_xgih7JbKnY0oAeCyYw4ADYqdNTi0axmBErh-lbh-XKNG_TnoMa-2IS3X041N8OsDfSdQp3QsAm53fF8seQuLFa27Iaq2etMj3yGeqWVjA-Mae3K34mt2YPGjQ-HbIOMVmYXBLzNr-s2fT35Sp6SDEsFyvzXb0Vij58s1wW5zkuKgaJiroGgkY86NImuaa3_-wpMK3_9O_wwAbRwV4uBCVzT_rY6rDQHR9-VkM0MbGK8drbdtjXwy3KtAzkux4N4g2nadYU0IIIEUNj_JChUFSHC7VRg7L7LpZMgAFGwHmaUyzQt31LyiVix9WFtcKfBgzehoRV6vstln-oBRd-vFjUW-7WLm7R_lFNHQZ0CKUvKCSpQxdIevczpYT0_lQiDU7Rfp1UBBnicndpq4YQwgRppdZX-QHG5IZxxHNWYdIBtn3eO3ooDXmI-rYryyVcFG6VY5xqssf8GgXqgNy84X_SgYfhGmNiPPQTl5wIBa49f1sxAI-7ri1xLr6FJhQMasOoxm_VuZYNkq6NrAXprtKa70cBRpm1wWBNcPdMul4GNMDQatQZRDENcNLe45iMX-HB1YYSvyc-y5rfSJkP4EgKXC-OqcrzxAlRfB3Bm4jOQL_PSsNBbh26CWAdAYSftM88fbnuqZX2w==\"},{\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello!\"}],\"status\":\"completed\"},{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Now reply exactly with: Done.\"}]}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"low\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":40,\"stream\":true}"
+        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Think briefly, then reply exactly with: Hello!\"}]},{\"type\":\"reasoning\",\"id\":\"rs_052e7ec551f55289016aa8c8d63eac87d19d6b921611f123e7\",\"summary\":[],\"encrypted_content\":\"gAAAAABqqMjWZ2Eei8_Gf-5FeEFAYp-gSzFL4D4lQBKL_fyyTYXv5iJ-2jql1mOq0wZpqHL8O9MWxebQGW56Ahd-p21qrDD52CyUBqKKlF87eC1d-cTgjXQlFMsPxvwyQeuU6A2l8tanTtJ48sKtzZtHrDuBXZ35u-lONnovjFGMX3Q83xoqG_um_w5rT420TA_SyU4fGt7oiQvOPS1q4PNo97O824oRnI7n_BC1jPYCaJhl2I1rPJg4afuOpjG-u7JcXRD4JPwZdqMa5o2d0uDKHuUYwP25qiPKKDqTTqFka5cDJjZNPF3ZkVHR-cagjZGvMnizXXxgUpPJ9j83gqY4QJLKCkzcaBj9H7mAL-v9yl4I5kn_9_DhpMILs2SZkC8AvIYNgmel3sDV_BG4XZ2JXciZz86ukQ6DwXgQqS4HOB91g-sGHOWMU1ohsZlEvvJBjGkJ_rAdXVMqAbvi2zvE3_NI4sTAGUrIugGJePrQYTe8gqL8f9NsYac6pzHNQL1e_jQNUvp49bu7EsPzCP3KPYVvZCFohDdwe7sMd6wrztrCJwM4CLdAQK61A7sYzU0HyglLtPidmS5QkSmV6U_xgih7JbKnY0oAeCyYw4ADYqdNTi0axmBErh-lbh-XKNG_TnoMa-2IS3X041N8OsDfSdQp3QsAm53fF8seQuLFa27Iaq2etMj3yGeqWVjA-Mae3K34mt2YPGjQ-HbIOMVmYXBLzNr-s2fT35Sp6SDEsFyvzXb0Vij58s1wW5zkuKgaJiroGgkY86NImuaa3_-wpMK3_9O_wwAbRwV4uBCVzT_rY6rDQHR9-VkM0MbGK8drbdtjXwy3KtAzkux4N4g2nadYU0IIIEUNj_JChUFSHC7VRg7L7LpZMgAFGwHmaUyzQt31LyiVix9WFtcKfBgzehoRV6vstln-oBRd-vFjUW-7WLm7R_lFNHQZ0CKUvKCSpQxdIevczpYT0_lQiDU7Rfp1UBBnicndpq4YQwgRppdZX-QHG5IZxxHNWYdIBtn3eO3ooDXmI-rYryyVcFG6VY5xqssf8GgXqgNy84X_SgYfhGmNiPPQTl5wIBa49f1sxAI-7ri1xLr6FJhQMasOoxm_VuZYNkq6NrAXprtKa70cBRpm1wWBNcPdMul4GNMDQatQZRDENcNLe45iMX-HB1YYSvyc-y5rfSJkP4EgKXC-OqcrzxAlRfB3Bm4jOQL_PSsNBbh26CWAdAYSftM88fbnuqZX2w==\"},{\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello!\"}],\"status\":\"completed\"},{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Now reply exactly with: Done.\"}]}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"low\",\"summary\":\"auto\"},\"max_output_tokens\":40,\"stream\":true}"
       },
       "response": {
         "status": 200,

packages/ai/test/fixtures/recordings/openai-responses/openai-responses-gpt-5-5-reasoning.json

@@ -24,7 +24,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Think briefly, then reply exactly with: Hello!\"}]}],\"instructions\":\"Show concise reasoning when the provider supports visible reasoning summaries.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"low\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":120,\"stream\":true}"
+        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Think briefly, then reply exactly with: Hello!\"}]}],\"instructions\":\"Show concise reasoning when the provider supports visible reasoning summaries.\",\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"low\",\"summary\":\"auto\"},\"max_output_tokens\":120,\"stream\":true}"
       },
       "response": {
         "status": 200,

packages/ai/test/fixtures/recordings/openai-responses/openai-responses-gpt-5-5-tool-loop.json

@@ -25,7 +25,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"What is the weather in Paris?\"}]}],\"instructions\":\"Use the get_weather tool exactly once. After the tool result, reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":80,\"stream\":true}"
+        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"What is the weather in Paris?\"}]}],\"instructions\":\"Use the get_weather tool exactly once. After the tool result, reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":80,\"stream\":true}"
       },
       "response": {
         "status": 200,
@@ -43,7 +43,7 @@
         "headers": {
           "content-type": "application/json"
         },
-        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"What is the weather in Paris?\"}]},{\"type\":\"function_call\",\"id\":\"fc_09525c04931d1487016aa8c8d8e12887d193bd327a0f313bd7\",\"call_id\":\"call_p57PJbKe0bX44nj908fpHdRn\",\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"},{\"type\":\"function_call_output\",\"call_id\":\"call_p57PJbKe0bX44nj908fpHdRn\",\"output\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}],\"instructions\":\"Use the get_weather tool exactly once. After the tool result, reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"text\":{\"verbosity\":\"low\"},\"max_output_tokens\":80,\"stream\":true}"
+        "body": "{\"model\":\"gpt-5.5\",\"input\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"What is the weather in Paris?\"}]},{\"type\":\"function_call\",\"id\":\"fc_09525c04931d1487016aa8c8d8e12887d193bd327a0f313bd7\",\"call_id\":\"call_p57PJbKe0bX44nj908fpHdRn\",\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"},{\"type\":\"function_call_output\",\"call_id\":\"call_p57PJbKe0bX44nj908fpHdRn\",\"output\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}],\"instructions\":\"Use the get_weather tool exactly once. After the tool result, reply exactly: Paris is sunny.\",\"tools\":[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false},\"strict\":false}],\"store\":false,\"include\":[\"reasoning.encrypted_content\"],\"reasoning\":{\"effort\":\"medium\",\"summary\":\"auto\"},\"max_output_tokens\":80,\"stream\":true}"
       },
       "response": {
         "status": 200,

packages/ai/test/image.test.ts

@@ -323,6 +323,23 @@ describe("Image", () => {
     ),
   )
 
+  it.effect("decodes URL images and rejects items with neither data nor a URL", () =>
+    Effect.gen(function* () {
+      const model = XAI.configure({ apiKey: "test", baseURL: "https://api.xai.test/v1" }).image("future-model")
+      const respond = (data: ReadonlyArray<object>) =>
+        layer((input) =>
+          Effect.succeed(input.respond(JSON.stringify({ data }), { headers: { "content-type": "application/json" } })),
+        )
+      const response = yield* Image.generate({ model, prompt: "A kite" }).pipe(
+        Effect.provide(respond([{ url: "https://xai.test/a.png", mime_type: "image/png" }])),
+      )
+      expect(response.images[0].source).toEqual({ type: "url", url: "https://xai.test/a.png", mediaType: "image/png" })
+      const error = yield* Image.generate({ model, prompt: "A kite" }).pipe(Effect.provide(respond([{}])), Effect.flip)
+      expect(error.reason._tag).toBe("InvalidProviderOutput")
+      expect(error.message).toContain("xAI Images result 0 has neither image data nor a URL")
+    }),
+  )
+
   it.effect("lowers ordered Google image inputs into generateContent parts", () =>
     Image.generate({
       model: Google.configure({ apiKey: "test", baseURL: "https://google.test/v1beta" }).image("future-model"),

packages/ai/test/image.types.ts

@@ -7,7 +7,6 @@ import {
   type ImageModelOptions,
   type ImageOptions,
   type ImageRequestFor,
-  type ImageRoute,
 } from "../src/index.js"
 import type { Service } from "../src/image-client.js"
 import { Anthropic, BlackForestLabs, Google, OpenAI, Stability, XAI, ZAI } from "../src/providers.js"
@@ -21,8 +20,7 @@ type GoogleLikeOptions = {
   readonly thinkingLevel?: "LOW" | "HIGH"
 } & Record<string, unknown>
 
-declare const route: ImageRoute<GoogleLikeOptions>
-const google = ImageModel.make<GoogleLikeOptions>({ id: "gemini-image", provider: "google", route })
+declare const google: ImageModel<GoogleLikeOptions>
 // @ts-expect-error Extracted model options retain known provider fields.
 const invalidGoogleOptions: ImageModelOptions<typeof google> = { imageSize: "8K" }
 void invalidGoogleOptions
@@ -152,6 +150,8 @@ Image.generate({ model: zai, prompt: "A lighthouse", providerOptions: { quality:
 Image.generate({ model: zai, prompt: "A lighthouse", providerOptions: { userID: 1 } })
 
 declare const generic: ImageModel<ImageOptions>
+const widenImage = <Options extends ImageOptions>(model: ImageModel<Options>): ImageModel => model
+void widenImage
 Image.generate({ model: generic, prompt: "A lighthouse", providerOptions: { arbitrary: true } })
 const explicitAsset: Media.Asset = Media.url("https://example.com/image.png")
 void explicitAsset

packages/ai/test/llm-option-types.types.ts

@@ -6,6 +6,7 @@ import {
   type LanguageModelProviderOptions,
   type ProviderOptions,
 } from "../src/index.js"
+import { ai } from "../src/promise.js"
 import { OpenAIChat } from "../src/protocols.js"
 
 interface ExampleOptions {
@@ -31,6 +32,10 @@ const generated = LLM.generate(LLM.request({ model, prompt: "Hello" }))
 type GenerateRequirements = Assert<Equal<Requirements<typeof generated>, LLMClientService>>
 const streamed = LLM.stream(LLM.request({ model, prompt: "Hello" }))
 type StreamClientRequirements = Assert<Equal<StreamRequirements<typeof streamed>, LLMClientService>>
+const generatedFromInput = LLM.generate({ model, prompt: "Hello", providerOptions: { mode: "fast" } })
+type InputGenerateRequirements = Assert<Equal<Requirements<typeof generatedFromInput>, LLMClientService>>
+const streamedFromInput = LLM.stream({ model, prompt: "Hello", providerOptions: { mode: "thorough" } })
+type InputStreamRequirements = Assert<Equal<StreamRequirements<typeof streamedFromInput>, LLMClientService>>
 
 LLM.request({
   model,
@@ -39,6 +44,11 @@ LLM.request({
   providerOptions: { mode: "slow" },
 })
 
+// @ts-expect-error Direct input keeps the selected model's provider option types.
+LLM.generate({ model, prompt: "Hello", providerOptions: { mode: "slow" } })
+// @ts-expect-error Stream input keeps the selected model's provider option types.
+LLM.stream({ model, prompt: "Hello", providerOptions: { mode: "slow" } })
+
 const generatedObject = LLM.generateObject({
   model,
   prompt: "Hello",
@@ -69,5 +79,16 @@ const options: LanguageModelProviderOptions<typeof model> = { mode: "fast" }
 void (options satisfies LanguageModelProviderOptions<typeof model>)
 void (true satisfies GenerateRequirements)
 void (true satisfies StreamClientRequirements)
+void (true satisfies InputGenerateRequirements)
+void (true satisfies InputStreamRequirements)
 void (true satisfies GenerateObjectRequirements)
 void (true satisfies GenerateDynamicObjectRequirements)
+
+void ai.llm.generate({ model, prompt: "Hello", providerOptions: { mode: "fast" } })
+void ai.llm.stream({ model, prompt: "Hello", providerOptions: { mode: "thorough" } })
+void ai.llm.generate(ai.llm.request({ model, prompt: "Hello" }))
+void ai.llm.stream(ai.llm.request({ model, prompt: "Hello" }))
+// @ts-expect-error Promise direct input keeps the selected model's provider option types.
+void ai.llm.generate({ model, prompt: "Hello", providerOptions: { mode: "slow" } })
+// @ts-expect-error Promise stream input keeps the selected model's provider option types.
+void ai.llm.stream({ model, prompt: "Hello", providerOptions: { mode: "slow" } })