refactor(ai): one media client shape and route types erased over options (#51226)

packages/ai/AGENTS.md

@@ -102,7 +102,7 @@ Media does not fit the SSE-frames-to-event-state-machine LLM route. `MediaRoute.
 
 `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
 

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`
@@ -420,7 +420,7 @@ 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
 

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,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, type OpenString } from "./schema/index.js"
 import { ImageClient, Service } from "./image-client.js"
 
@@ -11,75 +10,39 @@ 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.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",
 })
@@ -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.
@@ -232,36 +186,31 @@ export function request(input: ImageRequest | ImageRequestInput) {
 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/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
@@ -41,48 +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({
-    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/route/media.ts

@@ -5,7 +5,7 @@ import { Endpoint } from "./endpoint.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 } from "../generation.js"
+import { Generation } from "../generation.js"
 import type { Media } from "../media.js"
 import {
   AIError,
@@ -52,7 +52,7 @@ export const deployment = (
 // ---------------------------------------------------------------------------
 
 /** 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
@@ -86,7 +86,7 @@ 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>
 
@@ -119,7 +119,7 @@ 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",
@@ -267,59 +267,6 @@ 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) =>
-    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 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
 // ---------------------------------------------------------------------------

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,8 +1,8 @@
 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, type OpenString } from "./schema/index.js"
 import { SpeechClient, Service } from "./speech-client.js"
 
@@ -10,53 +10,39 @@ 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.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",
 })
@@ -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,
@@ -195,17 +187,15 @@ export function request(input: SpeechRequest | SpeechRequestInput) {
 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.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.
@@ -243,11 +197,7 @@ export function request(input: TranscriptionRequest | TranscriptionRequestInput)
 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/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,7 +3,6 @@ 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, type OpenString } from "./schema/index.js"
 import { VideoClient, Service } from "./video-client.js"
 
@@ -11,41 +10,39 @@ 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.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",
 })
@@ -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
@@ -178,33 +179,28 @@ export function request(input: VideoRequest | VideoRequestInput) {
 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/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/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/promise.test.ts

@@ -127,6 +127,10 @@ describe("AI promise client", () => {
     expect(image.image).toBeInstanceOf(Media.Asset)
     expect(image.image.mediaType).toBe("image/png")
     expect(await ai.run(image.image.bytes())).toEqual(Uint8Array.from([1, 2, 3]))
+    const requested = await ai.image.generate(
+      ai.image.request({ model: openai.image("gpt-image-2"), prompt: "A lighthouse" }),
+    )
+    expect(requested.image.mediaType).toBe("image/png")
 
     const deltas: Array<string> = []
     for await (const event of ai.llm.stream(request)) {
@@ -149,6 +153,7 @@ describe("AI promise client", () => {
       "https://openai.test/v1/chat/completions",
       "https://openai.test/v1/chat/completions",
       "https://openai.test/v1/images/generations",
+      "https://openai.test/v1/images/generations",
       "https://openai.test/v1/chat/completions",
       "https://openai.test/v1/chat/completions",
       "https://openai.test/v1/images/generations",
@@ -277,10 +282,15 @@ describe("AI promise client", () => {
     expect(failure).toBeInstanceOf(AIError)
     expect(failure instanceof AIError && failure.reason.http?.status).toBe(404)
 
-    const invalid = await ai.llm
+    const invalidLLM = await ai.llm
       // @ts-expect-error Invalid input must reject with AIError instead of throwing synchronously.
       .generate({ model: openai.responses("gpt-5"), messages: [{ role: "bogus" }] })
       .catch((error: unknown) => error)
+    expect(invalidLLM instanceof AIError && invalidLLM.reason._tag).toBe("InvalidRequest")
+
+    const invalid = await ai.image
+      .generate({ model: openai.image("gpt-image-2"), prompt: "A lighthouse", n: 1.5 })
+      .catch((error: unknown) => error)
     expect(invalid instanceof AIError && invalid.reason._tag).toBe("InvalidRequest")
 
     const controller = new AbortController()

packages/ai/test/speech.types.ts

@@ -1,5 +1,5 @@
 import type { Stream } from "effect"
-import { Speech, type SpeechEvent } from "../src/index.js"
+import { Speech, SpeechModel, type SpeechEvent, type SpeechOptions } from "../src/index.js"
 import { ElevenLabs, OpenAI, Runway } from "../src/providers.js"
 
 type StreamItem<T> = T extends Stream.Stream<infer A, infer _E, infer _R> ? A : never
@@ -7,6 +7,8 @@ type Equal<A, B> = [A, B] extends [B, A] ? true : false
 type Assert<T extends true> = T
 
 const elevenlabs = ElevenLabs.configure({ apiKey: "test" }).speech("eleven_flash_v2_5")
+const widenSpeech = <Options extends SpeechOptions>(model: SpeechModel<Options>): SpeechModel => model
+void widenSpeech
 
 Speech.generate({
   model: elevenlabs,

packages/ai/test/transcription.types.ts

@@ -1,5 +1,11 @@
 import type { Stream } from "effect"
-import { Media, Transcription, type TranscriptionEvent } from "../src/index.js"
+import {
+  Media,
+  Transcription,
+  TranscriptionModel,
+  type TranscriptionEvent,
+  type TranscriptionOptions,
+} from "../src/index.js"
 import { AssemblyAI, Deepgram, OpenAI } from "../src/providers.js"
 
 type StreamItem<T> = T extends Stream.Stream<infer A, infer _E, infer _R> ? A : never
@@ -8,6 +14,10 @@ type Assert<T extends true> = T
 
 const audio = Media.url("https://example.com/call.mp3")
 const deepgram = Deepgram.configure({ apiKey: "test" }).transcription("nova-3")
+const widenTranscription = <Options extends TranscriptionOptions>(
+  model: TranscriptionModel<Options>,
+): TranscriptionModel => model
+void widenTranscription
 
 Transcription.generate({
   model: deepgram,

packages/ai/test/video.types.ts

@@ -9,7 +9,6 @@ import {
   type VideoModelOptions,
   type VideoOptions,
   type VideoRequestFor,
-  type VideoRoute,
 } from "../src/index.js"
 import type { Service } from "../src/video-client.js"
 import { Anthropic, Fal, Google, OpenAI, Runway, XAI } from "../src/providers.js"
@@ -23,8 +22,7 @@ type VeoLikeOptions = {
   readonly personGeneration?: "allow_all" | "allow_adult"
 } & Record<string, unknown>
 
-declare const route: VideoRoute<VeoLikeOptions>
-const veo = VideoModel.make<VeoLikeOptions>({ id: "veo", provider: "google", route })
+declare const veo: VideoModel<VeoLikeOptions>
 // @ts-expect-error Extracted model options retain known provider fields.
 const invalidVeoOptions: VideoModelOptions<typeof veo> = { personGeneration: "everyone" }
 void invalidVeoOptions
@@ -99,6 +97,8 @@ Video.generate({ model: google, prompt: "A kitten", durationSeconds: "8s" })
 Video.generate({ model: google, prompt: "A kitten", options: { personGeneration: "allow_all" } })
 
 declare const generic: VideoModel<VideoOptions>
+const widenVideo = <Options extends VideoOptions>(model: VideoModel<Options>): VideoModel => model
+void widenVideo
 Video.generate({ model: generic, prompt: "A kitten", providerOptions: { arbitrary: true } })
 
 const request = Video.request({ model: veo, prompt: "A kitten", providerOptions: { personGeneration: "allow_all" } })