@opencode/ai 2.0.14 → 2.0.16

package/README.md

@@ -8,10 +8,10 @@ import { LLM, LLMClient } from "@opencode/ai"
 import { RequestExecutor } from "@opencode/ai/route"
 import { OpenAI } from "@opencode/ai/providers"
 
-const model = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
 
 const request = LLM.request({
-  model,
+  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 },
@@ -29,6 +29,43 @@ await Effect.runPromise(program.pipe(Effect.provide(llmLayer)))
 
 Run `LLMClient.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. 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 models. `Image.request` resolves the provider's image route from the ref and
+returns `Media.Asset`s with lazily decoded bytes:
+
+```ts
+import { NodeFileSystem } from "@effect/platform-node"
+import { Image, ImageClient, Media } from "@opencode/ai"
+
+const image = Effect.gen(function* () {
+  const response = yield* Image.generate({
+    model: openai.image("gpt-image-2"),
+    prompt: "A robot tending a rooftop garden",
+    size: "1024x1024",
+    providerOptions: { quality: "high" }, // typed per image model
+  })
+  yield* Media.write(response.image, "./garden.png")
+})
+
+// `asset.bytes()` / `Media.write` also need the executor, so merge it into the environment instead of hiding it.
+const imageLayer = ImageClient.layer.pipe(Layer.provideMerge(RequestExecutor.fetchLayer))
+
+await Effect.runPromise(image.pipe(Effect.provide(imageLayer), Effect.provide(NodeFileSystem.layer)))
+```
+
+Prefer promises? `@opencode/ai/promise` exposes the same LLM and image APIs over one managed runtime:
+
+```ts
+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 generated = await ai.image.generate({ model: openai.image("gpt-image-2"), prompt: "A lighthouse" })
+for await (const event of ai.llm.stream({ model: openai.responses("gpt-4o-mini"), prompt: "Stream hello." })) {
+  // LLMEvent
+}
+await ai.dispose()
+```
+
 ## Experimental evaluation
 
 Evaluation models compare shared state with typed choice, score, and boolean questions. The API is
@@ -41,7 +78,7 @@ import { TypeSafeAI } from "@opencode/ai/providers"
 
 const model = TypeSafeAI.configure().experimental.evaluation("jev-latest")
 
-const program = Evaluation.evaluate({
+const program = Evaluation.run({
   model,
   state: "I was charged twice. Please refund the duplicate payment.",
   questions: {
@@ -66,7 +103,17 @@ console.log(response.answers.refund.probability)
 ```
 
 `TypeSafeAI` reads `TYPESAFE_API_KEY`. `OpenCodeZen` exposes the same selector and reads
-`OPENCODE_API_KEY`. The common API uses `boolean`; System One routes lower it to native `noul`.
+`OPENCODE_API_KEY`. OpenRouter and Vercel AI Gateway use the same provider shape:
+
+```ts
+import { OpenRouter, VercelAIGateway } from "@opencode/ai/providers"
+
+OpenRouter.configure().experimental.evaluation("typesafe/jev-1.13")
+VercelAIGateway.configure().experimental.evaluation("typesafe-ai/jev")
+```
+
+OpenRouter reads `OPENROUTER_API_KEY`. Vercel reads `AI_GATEWAY_API_KEY`, then `VERCEL_OIDC_TOKEN`.
+The common API uses `boolean`; System One routes lower it to native `noul`.
 Choice and score confidence plus score legends remain available in provider metadata, and the
 provider's rounded probabilities are returned unchanged.
 
@@ -355,23 +402,25 @@ citations or separate result blocks. Retain `response.message` for either API's
 Use `Image.generate` for one-off generation or editing:
 
 ```ts
-import { Image, ImageInput } from "@opencode/ai"
+import { Image, Media } from "@opencode/ai"
 
 const generation = Image.generate({
-  model: meta.image("muse-image-1.0"),
+  model: meta("muse-image-1.0"),
   prompt: "A flat black square on a white background.",
-  options: { n: 1, reasoningStrength: "low" },
+  n: 1,
+  providerOptions: { reasoningStrength: "low" },
 })
 
 const edit = Image.generate({
-  model: meta.image("muse-image-1.0"),
+  model: meta("muse-image-1.0"),
   prompt: "Make the square purple.",
-  images: [ImageInput.bytes(imageBytes, "image/webp")],
-  options: { outputFormat: "png", reasoningStrength: "low" },
+  images: [Media.bytes(imageBytes, "image/webp")],
+  format: "png",
+  providerOptions: { reasoningStrength: "low" },
 })
 ```
 
-The default image format is WEBP; `outputFormat` also accepts PNG/JPEG and `responseFormat: "url"`
+The default image format is WEBP; `format` also accepts PNG/JPEG and `responseFormat: "url"`
 returns a signed URL. `size` is an aspect-ratio hint. For conversational images, select
 `meta.responses("muse-image-1.0")` with `tools: [Meta.imageGeneration({ reasoningStrength: "low" })]`.
 Generated images are provider-executed tool results with file content. Retain `response.message` to
@@ -382,29 +431,40 @@ Meta Responses is explicitly HTTP/SSE-only and does not use WebSockets, even whe
 
 ## Image generation
 
-Use `Image.generate` with an image model for direct asset generation:
+Use `Image.generate` with an image model for direct asset generation. `Image.request` mirrors `LLM.request`: the
+model comes from the facade's `.image(...)` selector (mirroring `.responses(...)`), common fields
+(`images`, `mask`, `n`, `size`, `aspectRatio`, `seed`, `format`) lower natively or fail typed, and
+`providerOptions` is inferred from the selected model:
 
 ```ts
-import { Image, ImageInput } from "@opencode/ai"
+import { Image, Media } from "@opencode/ai"
 import { OpenAI } from "@opencode/ai/providers"
 
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
+
 const program = Effect.gen(function* () {
   const response = yield* Image.generate({
-    model: OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).image("gpt-image-2"),
+    model: openai.image("gpt-image-2"),
     prompt: "A robot tending a rooftop garden",
-    options: {
-      n: 2,
-      size: "1024x1024",
+    n: 2,
+    size: "1024x1024",
+    format: "webp",
+    providerOptions: {
       quality: "high", // inferred from the OpenAI image model
-      outputFormat: "webp",
       future_option: true, // unknown native options pass through unchanged
     },
   })
 
-  return response.images // GeneratedImage[] with owned bytes or a provider URL
+  return response.images // Media.Asset[] with owned bytes or a provider URL
 })
 ```
 
+`Media.Asset` is the one asset type shared by image requests, image responses, LLM messages, and tool results.
+`asset.source` is the serializable `Media.Source` (`bytes`, `base64`, `url`, or `ref`); `asset.bytes()`,
+`asset.base64()`, and `asset.dataUrl()` decode or download lazily and cache; `asset.materialize()` pulls a `url`
+asset into owned bytes before the provider URL expires. Construct assets with `Media.bytes`, `Media.base64`,
+`Media.url`, `Media.ref(provider, id)`, `Media.fromDataUrl`, or `Media.file(path)`.
+
 Pass ordered image inputs to the same method for editing, composition, or image-conditioned generation:
 
 ```ts
@@ -414,49 +474,45 @@ const response =
     model,
     prompt: "Combine these product photos into one studio scene",
     images: [
-      ImageInput.bytes(firstBytes, "image/png"),
-      ImageInput.url("https://example.com/second.webp"),
-      ImageInput.file("file_123"),
+      Media.bytes(firstBytes, "image/png"),
+      Media.url("https://example.com/second.webp"),
+      Media.ref("openai", "file_123"),
     ],
-    options,
+    providerOptions,
     http,
   })
 ```
 
-`ImageInput.fileUri(uri, mediaType)` represents provider file URIs such as Gemini Files. Raw strings are not
-accepted as image inputs, avoiding ambiguity between base64, URLs, and provider IDs. Empty or omitted `images`
-uses text-to-image generation; a non-empty array selects the provider's edit behavior without enforcing provider
-image-count limits locally. `images` is the only common image-editing field. OpenAI uses multipart for byte/data-URL
-edits and its JSON reference body for URL or file-ID edits. Its provider-specific `options.mask` accepts an
-`ImageInput` for inpainting:
+`Media.ref(provider, id)` represents provider file handles such as OpenAI file IDs or Gemini Files URIs; routes
+only forward refs that belong to their own provider. Raw strings are not accepted as image inputs, avoiding
+ambiguity between base64, URLs, and provider IDs. Empty or omitted `images` uses text-to-image generation; a
+non-empty array selects the provider's edit behavior without enforcing provider image-count limits locally. OpenAI
+uses multipart for byte/data-URL edits and its JSON reference body for URL or file-ID edits. The common `mask`
+field selects inpainting; routes that cannot honor it fail with `UnsupportedOperation`:
 
 ```ts
 yield *
   Image.generate({
-    model: OpenAI.configure({ apiKey }).image("gpt-image-2"),
+    model: openai.image("gpt-image-2"),
     prompt,
-    images: [ImageInput.bytes(sourceBytes, "image/png")],
-    options: { mask: ImageInput.bytes(maskBytes, "image/png") },
+    images: [Media.bytes(sourceBytes, "image/png")],
+    mask: Media.bytes(maskBytes, "image/png"),
   })
 ```
 
-The OpenAI adapter extracts this helper value into the edit request's native `mask` field rather than passing the
-tagged `ImageInput` object through as an ordinary option. On multipart requests, `http.body` can override option
-fields but not structural `model`, `prompt`, `image[]`, or `mask` fields, and the transport owns the multipart
-`Content-Type` boundary. For JSON requests, `http.body` remains the final raw-native overlay. Gemini does not fetch
-public HTTP URLs, and hosted Z.ai image generation does not accept image inputs. These cases fail with
-`InvalidRequest` before network I/O.
+On multipart requests, `http.body` can override option fields but not structural `model`, `prompt`, `image[]`,
+or `mask` fields, and the transport owns the multipart `Content-Type` boundary. For JSON requests, `http.body`
+remains the final raw-native overlay. Gemini does not fetch public HTTP URLs, and hosted Z.ai image generation does
+not accept image inputs. These cases fail with a typed `AIError` before network I/O.
 
 Provider-native image options belong to each request. Raw `http.body` fields have final precedence over them:
 
 ```ts
-const model = OpenAI.configure({ apiKey }).image("gpt-image-2")
-
 yield *
   Image.generate({
-    model,
+    model: openai.image("gpt-image-2"),
     prompt,
-    options: { quality: "medium" },
+    providerOptions: { quality: "medium" },
     http,
   })
 ```
@@ -466,11 +522,11 @@ xAI image models use the same request API with xAI-native controls:
 ```ts
 yield *
   Image.generate({
-    model: XAI.configure({ apiKey }).image("any-model-id"),
+    model: XAI.configure({ apiKey })("any-model-id"),
     prompt,
-    options: {
-      n: 2,
-      aspectRatio: "16:9",
+    n: 2,
+    aspectRatio: "16:9",
+    providerOptions: {
       resolution: "1k",
       responseFormat: "b64_json",
       future_option: true,
@@ -486,12 +542,12 @@ import { Google } from "@opencode/ai/providers"
 
 const googleProgram = Effect.gen(function* () {
   const response = yield* Image.generate({
-    model: Google.configure({ apiKey }).image("any-model-id"),
+    model: Google.configure({ apiKey })("any-model-id"),
     prompt: "A robot tending a rooftop garden",
-    options: {
-      aspectRatio: "16:9",
+    aspectRatio: "16:9",
+    seed: 42,
+    providerOptions: {
       imageSize: "2K",
-      seed: 42,
       thinkingLevel: "HIGH",
       includeThoughts: true,
       futureOption: true,
@@ -513,9 +569,9 @@ Z.ai image models infer open Z.ai-native options from the selected model:
 ```ts
 yield *
   Image.generate({
-    model: ZAI.configure({ apiKey }).image("any-model-id"),
+    model: ZAI.configure({ apiKey })("any-model-id"),
     prompt,
-    options: {
+    providerOptions: {
       quality: "hd",
       userID: "user-123",
       future_option: true,
@@ -525,8 +581,63 @@ yield *
 ```
 
 Z.ai does not include trustworthy MIME metadata for output URLs, so generated images use
-`application/octet-stream`. Output URLs expire after 30 days; download and persist them promptly if they must
-remain available.
+`application/octet-stream` until materialized. Output URLs expire after 30 days; call `asset.materialize()` and
+persist the bytes promptly if they must remain available.
+
+### Partial images
+
+OpenAI's GPT image models stream previews. `Image.stream` sends `stream: true` with `partialImages` (0–3, default 2)
+and emits `image-partial` events before each final `image`; `Image.generate` keeps the plain JSON request.
+`dall-e-*` models do not stream and fail typed:
+
+```ts
+yield *
+  Image.stream({
+    model: openai.image("gpt-image-2"),
+    prompt: "A lighthouse at dusk",
+    providerOptions: { partialImages: 2 },
+  }).pipe(Stream.runForEach((event) => (ImageEvent.is.imagePartial(event) ? showPreview(event.image) : Effect.void)))
+```
+
+The provider may send fewer previews than requested when the final image is ready first.
+
+### Queued image providers
+
+Black Forest Labs, fal, Replicate, and Stability's creative upscaler are submit-then-poll routes. `Image.generate`
+and `Image.stream` poll for you (pass `{ poll }` to tune the interval and timeout); `Image.start` returns a
+`Generation` whose `token` is serializable JSON for `Image.resume` in another process:
+
+```ts
+import { BlackForestLabs, Stability } from "@opencode/ai/providers"
+
+const bfl = BlackForestLabs.configure({ apiKey: process.env.BFL_API_KEY })
+
+const generation = yield * Image.start({ model: bfl.image("flux-2-pro"), prompt, size: "1024x768" })
+persist(generation.token)
+
+const resumed = yield * Image.resume(bfl.image("flux-2-pro"), loadToken())
+const response = yield * resumed.await({ poll: { interval: "2 seconds" } })
+```
+
+- **Black Forest Labs** — results are downloaded before returning, because `result.sample` expires in 10 minutes.
+- **Replicate** — inputs are model-defined, so only `prompt` lowers: sizing, count, seed, format, and files go in
+  `providerOptions` under the model's names, with files as `Media.Asset` (data URLs up to 256 KB, larger by URL).
+  Outputs are removed an hour after the prediction completes. `Prefer: wait=60` in `headers` or `http.headers` holds
+  the submission open so a fast prediction costs one result read.
+- **Stability** — `stability.image(id)` generates inline; `stability.upscale()` is the creative upscaler, queued:
+
+```ts
+const stability = Stability.configure({ apiKey: process.env.STABILITY_API_KEY })
+const upscaled =
+  yield *
+  Image.generate(
+    { model: stability.upscale(), prompt: "A lighthouse", images: [yield * Media.file("./small.png")] },
+    { poll: { interval: "5 seconds" } },
+  )
+```
+
+Imagen is not available: Google shut it down on the Gemini API, and Vertex discontinued the Imagen 4 models on
+2026-06-30. `Google.image(...)` uses Gemini-native image models.
 
 Conversational image generation remains part of the LLM interaction. OpenAI Responses exposes it through its hosted image tool:
 
@@ -544,7 +655,234 @@ const program = Effect.gen(function* () {
 })
 ```
 
-The hosted result is represented as a provider-executed tool call and tool result. Its image is a `file` content item with a data URI, so retaining `response.message` preserves the generated image for continuation.
+The hosted result is represented as a provider-executed tool call and tool result, and the generated image is also emitted as a first-class `media` `LLMEvent` (`response.message` then carries a `media` part). Gemini image-capable models emit the same `media` event for inline image output. Retaining `response.message` preserves the generated image for continuation on both routes.
+
+## Video generation
+
+Video mirrors `Image` with one difference: every provider is asynchronous, so the route is a submit-then-poll
+`Generation`. Models come from `.video(...)` selectors on the `Google` (Veo), `XAI`, `Fal`, and `Runway` facades.
+Common fields (`frames`, `references`, `video`, `durationSeconds`, `aspectRatio`, `resolution`, `audio`, `n`, `seed`,
+`negativePrompt`) lower natively or fail with a typed `AIError` before any network call; provider-native controls live
+under `providerOptions`, inferred from the selected model.
+
+```ts
+import { Video, VideoClient } from "@opencode/ai"
+import { Google } from "@opencode/ai/providers"
+
+const google = Google.configure({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY })
+
+// Simple: submit and wait.
+const program = Effect.gen(function* () {
+  const response = yield* Video.generate(
+    {
+      model: google.video("veo-3.1-generate-preview"),
+      prompt: "Panning wide shot of a calico kitten sleeping in the sunshine",
+      aspectRatio: "16:9",
+      resolution: "1080p",
+      durationSeconds: 8,
+      providerOptions: { personGeneration: "allow_adult" },
+    },
+    { poll: { interval: "10 seconds", timeout: "10 minutes" } },
+  )
+  // Veo serves files for two days behind the API key. The asset knows the deadline (`expiresAt`) and carries the
+  // download credentials only on the live instance (`asset.headers`), never in `source` or JSON: materialize
+  // before persisting, or the persisted URL cannot be fetched again.
+  return yield* response.video.materialize()
+})
+
+// Explicit control: keep the handle, persist the token, resume elsewhere.
+const controlled = Effect.gen(function* () {
+  const generation = yield* Video.start({ model: google.video("veo-3.1-generate-preview"), prompt })
+  generation.id // provider operation / task / request id
+  generation.status // "queued" | "running" | "completed" | "failed" | "cancelled" | "expired"
+  generation.token // route-owned JSON: `{ operation }`, `{ requestID }`, `{ taskID }`, or fal's follow-up URLs
+  const saved = JSON.stringify(generation.token)
+
+  const resumed = yield* Video.resume(google.video("veo-3.1-generate-preview"), JSON.parse(saved))
+  return yield* resumed.await({ poll: { interval: "10 seconds" } })
+})
+
+// Progress as a stream: generation-queued | generation-progress | video | finish.
+const events = Video.stream({ model: Runway.configure({ apiKey }).video("gen4.5"), prompt }, { poll })
+```
+
+`VideoClient.layer` needs `RequestExecutor.Service`, and status polls, result fetches, cancels, and asset downloads
+all run through the same executor with the route's auth. `Generation.await` and `Generation.events` fail with a
+`Timeout` reason when `poll.timeout` (default 10 minutes) elapses. Failed,
+cancelled, and expired generations fail typed with the provider's terminal document on `reason.body`; moderation
+outcomes (Veo `raiMediaFilteredReasons`, xAI `respect_moderation`, Runway `SAFETY.*` codes) surface as `notices` when
+a video is still returned and as a `ContentPolicy` reason when nothing is.
+
+Provider notes:
+
+- **Google Veo** takes inline bytes only (materialize `url` assets first); `frames.last` requires `frames.first`;
+  audio is always on, so `audio: false` fails typed; one video per request. Output URLs need the API key to
+  download, which the returned asset holds transiently (see above).
+- **xAI** sends a `video` input to `/videos/edits`, or `/videos/extensions` with `providerOptions.mode: "extend"`.
+  `seed` and `negativePrompt` are not supported.
+- **fal** endpoints are model-specific: `durationSeconds`, `references`, and `frames.last` fail typed and belong in
+  `providerOptions` under the model's own names (`duration: "8s"`, `end_image_url`, …). Auth is
+  `Authorization: Key <FAL_KEY>`.
+- **Runway** expects pixel ratios in `aspectRatio` for most models (`"1280:720"`), pins `X-Runway-Version`, reports
+  `usage: { type: "credits" }`, and its output URLs expire after 24–48 hours.
+
+The promise client exposes the same surface: `ai.video.start(...)` resolves to a handle with `await`, `refresh`,
+`cancel`, and `token`; `ai.video.generate`, `ai.video.resume(model, token)`, and `ai.video.stream` mirror the Effect
+API.
+
+```ts
+import { ai } from "@opencode/ai/promise"
+
+const generation = await ai.video.start({ model, prompt })
+const video = await generation.await({ poll: { interval: 10_000 }, signal })
+```
+
+## Speech generation
+
+Speech (text-to-speech) is one request whose response is parsed incrementally, so every route supports both
+`Speech.generate` (the whole file) and `Speech.stream` (audio chunks as they arrive). Models come from `.speech(...)`
+selectors on the `OpenAI`, `Google` (Gemini TTS), `ElevenLabs`, `Cartesia`, and `Deepgram` facades. Common fields
+(`voice`, `format`, `speed`, `language`, `instructions`, `timestamps`) lower natively or fail with a typed `AIError`
+before any network call; provider-native controls live under `providerOptions`, inferred from the selected model.
+
+```ts
+import { Media, Speech, SpeechClient, SpeechEvent } from "@opencode/ai"
+import { ElevenLabs, OpenAI } from "@opencode/ai/providers"
+
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
+
+// The whole file, written to disk.
+const program = Effect.gen(function* () {
+  const response = yield* Speech.generate({
+    model: openai.speech("gpt-4o-mini-tts"),
+    text: "Hello from OpenCode.",
+    voice: "coral",
+    format: "mp3",
+    instructions: "Warm and unhurried.",
+  })
+  response.audio // Media.Asset with bytes; headerless PCM carries info.encoding / sampleRate / channels
+  response.usage // undefined: OpenAI reports tokens only on SSE streams (Gemini: tokens; ElevenLabs: credits; Deepgram: characters)
+  yield* Media.write(response.audio, "hello.mp3")
+})
+
+// Chunks as they arrive: audio-delta* (interleaved with timestamps) then one finish carrying the assembled asset.
+const events = Speech.stream({
+  model: ElevenLabs.configure({ apiKey }).speech("eleven_flash_v2_5"),
+  text: "Hello from OpenCode.",
+  voice: "JBFqnCBsd6RMkjVDRZzb",
+  format: "pcm",
+  timestamps: true,
+}).pipe(
+  Stream.tap((event) => {
+    if (SpeechEvent.is.audioDelta(event)) return play(event.chunk)
+    if (SpeechEvent.is.timestamps(event)) return highlight(event.items) // { text, startSeconds, endSeconds }[]
+    return Effect.void
+  }),
+)
+```
+
+`voice` is the provider's own identifier — a name on OpenAI and Gemini (`"coral"`, `"Kore"`), a voice id on
+ElevenLabs and Cartesia. `{ id }` selects an OpenAI custom voice (`{ id: "voice_1234" }`) and means the same as the
+plain string elsewhere. There is no cross-provider voice catalog. `format` is the container-level word (`mp3`, `wav`,
+`pcm`, `opus`, `aac`, `flac`); sample rates and bitrates live under `providerOptions`, and a value the route cannot
+produce fails as `UnsupportedOperation`. Streams buffer every chunk so `finish` can carry the whole clip.
+`SpeechClient.layer` needs `RequestExecutor.Service`.
+
+Provider notes:
+
+- **OpenAI** streams over SSE (`stream_format: "sse"`), which is also the only place it reports token usage; `tts-1`
+  and `tts-1-hd` do not support SSE and stream the raw audio body instead. `pcm` is 24 kHz 16-bit mono. `language`
+  and `timestamps` are not supported.
+- **Gemini TTS** returns raw 16-bit PCM only (`audio/L16;codec=pcm;rate=24000`), so any `format` other than `pcm`
+  fails typed; wrap the samples yourself. Style is directed in the text, so `instructions` and `speed` fail typed.
+  Only `gemini-3.1-flash-tts-preview` and later support streaming. Two-speaker audio goes through
+  `providerOptions.speechConfig.multiSpeakerVoiceConfig`.
+- **ElevenLabs** requires `voice` (the path voice id) and authenticates with `xi-api-key`. `format` maps to the
+  `output_format` query parameter (`mp3_44100_128`, `pcm_24000`, `wav_24000`, `opus_48000_64`);
+  `providerOptions.outputFormat` sets the exact string. WAV is only available from `generate`. `timestamps: true`
+  selects the `with-timestamps` endpoints and yields character-level alignment. `instructions` is not supported.
+- **Cartesia** requires `voice` and pins `Cartesia-Version`. `generate` defaults to MP3 from `/tts/bytes`; streams
+  and `timestamps: true` (word-level) use `/tts/sse`, which only serves raw PCM. `providerOptions.sampleRate`,
+  `bitRate`, and `encoding` complete `output_format`. No usage is reported.
+- **Deepgram** Aura's voice is the model id (`aura-2-thalia-en`), so `voice` and `language` fail typed. `format`
+  and `providerOptions` lower to query parameters (`encoding`, `container`, `sample_rate`, `bit_rate`); `pcm` is
+  `linear16` without a container. Auth is `Authorization: Token <DEEPGRAM_API_KEY>`.
+
+The promise client mirrors the Effect API; `ai.speech.stream` is an `AsyncIterable`.
+
+```ts
+import { ai } from "@opencode/ai/promise"
+
+const response = await ai.speech.generate({ model, text: "Hello from OpenCode.", voice: "coral" })
+await Bun.write("hello.mp3", await ai.run(response.audio.bytes()))
+
+for await (const event of ai.speech.stream({ model, text: "Hello from OpenCode.", voice: "coral" })) {
+  if (event.type === "audio-delta") player.write(event.chunk)
+}
+```
+
+## Transcription
+
+Transcription (speech-to-text) is the one modality whose providers use every route kind: OpenAI and Gemini stream,
+Deepgram answers inline, and AssemblyAI is queued. `Transcription.generate` and `Transcription.stream` work on all of
+them; `Transcription.start` / `resume` return a `Generation` on queued routes and fail with `UnsupportedOperation`
+elsewhere. Models come from `.transcription(...)` selectors on the `OpenAI`, `Google`, `Deepgram`, and `AssemblyAI`
+facades. Common fields (`language`, `prompt`, `timestamps: "none" | "segment" | "word"`, `diarize`, `speakers`) lower
+natively or fail with a typed `AIError` before any network call; a route may return more than asked.
+
+```ts
+import { Media, Transcription, TranscriptionEvent } from "@opencode/ai"
+import { AssemblyAI, Deepgram, OpenAI } from "@opencode/ai/providers"
+
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
+
+const program = Effect.gen(function* () {
+  const audio = yield* Media.file("./call.mp3")
+
+  // Speaker-labelled segments; labels are provider-native strings ("A", "0", "spk:0").
+  const response = yield* Transcription.generate({
+    model: Deepgram.configure({ apiKey }).transcription("nova-3"),
+    audio,
+    diarize: true,
+    timestamps: "word",
+  })
+  response.text // "Hello from OpenCode."
+  response.segments // [{ text, startSeconds, endSeconds, speaker: "0" }]
+  response.words // [{ text, startSeconds, endSeconds, speaker, confidence }]
+  response.language // the provider's own value, lowercased ("en", "english", "en_us")
+
+  // Text deltas as the model transcribes, then one finish carrying the whole transcript.
+  yield* Transcription.stream({ model: openai.transcription("gpt-4o-mini-transcribe"), audio }).pipe(
+    Stream.tap((event) => (TranscriptionEvent.is.textDelta(event) ? Console.log(event.delta) : Effect.void)),
+    Stream.runDrain,
+  )
+
+  // Queued: persist the token, resume from another process, and await.
+  const model = AssemblyAI.configure({ apiKey }).transcription("universal-3-5-pro")
+  const generation = yield* Transcription.start({ model, audio })
+  const resumed = yield* Transcription.resume(model, JSON.parse(JSON.stringify(generation.token)))
+  const transcript = yield* resumed.await({ poll: { interval: "3 seconds" } })
+})
+```
+
+Inline routes emit only `finish` from `stream` (no faked deltas); queued routes emit `generation-queued` /
+`generation-progress` before it. `TranscriptionClient.layer` needs `RequestExecutor.Service`.
+
+Provider notes:
+
+- **OpenAI** takes inline audio only; `diarize` needs `gpt-4o-transcribe-diarize`, timestamps need `whisper-1`, and `whisper-1` does not stream.
+- **Gemini** needs a transcribe model (`gemini-3.5-transcribe`); `prompt` and `speakers` fail typed.
+- **Deepgram** detects the language unless `language` is set; vocabulary goes in `providerOptions.keyterm`.
+- **AssemblyAI** uploads inline audio before submitting and is the only route that accepts `speakers`.
+
+The promise client mirrors the Effect API:
+
+```ts
+const text = (await ai.transcription.generate({ model, audio })).text
+for await (const event of ai.transcription.stream({ model, audio })) if (event.type === "text-delta") write(event.delta)
+const generation = await ai.transcription.start({ model: assemblyai, audio })
+const transcript = await generation.await({ poll: { interval: 3_000 } })
+```
 
 ## Public API
 
@@ -553,8 +891,13 @@ The hosted result is represented as a provider-executed tool call and tool resul
 - **`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.
-- **`Image.generate({...})`** — generate images through a provider-neutral image request and response model.
+- **`Image.request` / `generate` / `stream` / `start` / `resume`** — images over inline, streaming (partial previews), and queued routes through a provider-neutral request and response model.
 - **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.
+- **`Media`** — the shared asset type (`Media.Asset`, `Media.Source`) and constructors used by messages, tool results, and media requests.
+- **`Generation`** — provider-neutral handle for an in-flight media generation (`await`, `refresh`, `cancel`, `events`) used by queued media routes.
+- **`Speech.request` / `Speech.generate` / `Speech.stream`** — text-to-speech through a provider-neutral request; `SpeechClient` is its Effect service and layer.
+- **`Transcription.request` / `generate` / `stream` / `start` / `resume`** — speech-to-text over inline, streaming, and queued routes; `TranscriptionClient` is its Effect service and layer.
+- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, and `transcription` as Promise / `AsyncIterable` APIs.
 
 ## Testing
 

package/dist/experimental/evaluation-client.d.ts

@@ -1,6 +1,6 @@
 import { Context, Effect, Layer } from "effect";
 import { RequestExecutor } from "../route/executor.js";
-import { type AIError } from "../schema/index.js";
+import { AIError } from "../schema/index.js";
 import { type EvaluationOptions, type EvaluationQuestions, type EvaluationRequestFor, type EvaluationResponseFor } from "./evaluation.js";
 export type Execute = RequestExecutor.Interface["execute"];
 export interface Interface {