@opencode/ai 2.0.16 → 2.0.17

package/README.md

@@ -1,40 +1,38 @@
 # @opencode/ai
 
-Schema-first language model and image-generation APIs built with Effect.
+Schema-first APIs for text, images, video, speech, and transcription, built with Effect.
 
 ```ts
-import { Effect, Layer } from "effect"
-import { LLM, LLMClient } from "@opencode/ai"
-import { RequestExecutor } from "@opencode/ai/route"
+import { Effect } from "effect"
+import { AIClient, LLM } from "@opencode/ai"
 import { OpenAI } from "@opencode/ai/providers"
 
 const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
 
-const request = LLM.request({
-  model: openai.responses("gpt-4o-mini"), // `.chat(...)` selects the Chat Completions API instead
-  system: "You are concise.",
-  prompt: "Say hello in one short sentence.",
-  generation: { maxTokens: 40 },
-})
-
 const program = Effect.gen(function* () {
-  const response = yield* LLMClient.generate(request)
+  const response = yield* LLM.generate({
+    model: openai.responses("gpt-4o-mini"), // `.chat(...)` selects the Chat Completions API instead
+    system: "You are concise.",
+    prompt: "Say hello in one short sentence.",
+    generation: { maxTokens: 40 },
+  })
   console.log(response.text)
 })
 
-const llmLayer = LLMClient.layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
-
-await Effect.runPromise(program.pipe(Effect.provide(llmLayer)))
+// Every modality client plus the HTTP request executor; `AIClient.layerWith(executor)` swaps the executor.
+await Effect.runPromise(program.pipe(Effect.provide(AIClient.layer)))
 ```
 
-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.
+Run `LLM.stream(...)` instead of `generate` when you want incremental `LLMEvent`s. Both accept input or a prebuilt
+`LLM.request(...)`. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses,
+Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
 
-The same configured facade names image models. `Image.request` resolves the provider's image route from the ref and
-returns `Media.Asset`s with lazily decoded bytes:
+The same configured facade names image, video, speech, and transcription models. `Image.generate` resolves the
+provider's image route from the model and returns `Media.Asset`s with lazily decoded bytes:
 
 ```ts
 import { NodeFileSystem } from "@effect/platform-node"
-import { Image, ImageClient, Media } from "@opencode/ai"
+import { Image, Media } from "@opencode/ai"
 
 const image = Effect.gen(function* () {
   const response = yield* Image.generate({
@@ -46,21 +44,38 @@ const image = Effect.gen(function* () {
   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))
+// `Media.file` / `Media.write` use the Effect `FileSystem` service; provide your platform's layer.
+await Effect.runPromise(image.pipe(Effect.provide(AIClient.layer), Effect.provide(NodeFileSystem.layer)))
+```
+
+Advanced: each client also has its own `layer`, which requires `RequestExecutor.Service`. Compose client layers with
+`Layer.provideMerge`, not `Layer.provide`: `asset.bytes()`, `Media.write`, and Gemini's `media` output parts need the
+executor too, and hiding it fails type-checking with `RequestExecutorService` left in the requirements.
+
+To share a policy such as logging across every client, wrap the executor once with `RequestExecutor.middleware`:
+
+```ts
+import { RequestExecutor } from "@opencode/ai/route"
+
+const logged = RequestExecutor.middleware((request, next) =>
+  Effect.log(`${request.method} ${request.url}`).pipe(Effect.andThen(next(request))),
+)
 
-await Effect.runPromise(image.pipe(Effect.provide(imageLayer), Effect.provide(NodeFileSystem.layer)))
+const everything = AIClient.layerWith(logged) // or AI.make({ layer: logged })
 ```
 
-Prefer promises? `@opencode/ai/promise` exposes the same LLM and image APIs over one managed runtime:
+Prefer promises? `@opencode/ai/promise` exposes the same LLM and media APIs over one managed runtime, plus asset
+helpers; `ai.file` and `ai.write` load `node:fs/promises` on first use, so no Effect `FileSystem` is needed:
 
 ```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 input = { model: openai.responses("gpt-4o-mini"), prompt: "Say hello." }
+const text = await ai.llm.generate(input)
 const generated = await ai.image.generate({ model: openai.image("gpt-image-2"), prompt: "A lighthouse" })
-for await (const event of ai.llm.stream({ model: openai.responses("gpt-4o-mini"), prompt: "Stream hello." })) {
+await ai.write(generated.image, "./lighthouse.png") // also ai.file(path), ai.bytes(asset), ai.base64(asset), ai.materialize(asset)
+for await (const event of ai.llm.stream(ai.llm.request(input))) {
   // LLMEvent
 }
 await ai.dispose()
@@ -322,10 +337,9 @@ and `moonshot/responses`; each exports `model(modelID, settings)`.
 MiniMax defaults to its Messages API and reads `MINIMAX_API_KEY` when `apiKey` is omitted:
 
 ```ts
-import { Effect, Layer } from "effect"
-import { LLM, LLMClient } from "@opencode/ai"
+import { Effect } from "effect"
+import { AIClient, LLM } from "@opencode/ai"
 import { MiniMax } from "@opencode/ai/providers"
-import { RequestExecutor } from "@opencode/ai/route"
 
 const minimax = MiniMax.configure({ apiKey: process.env.MINIMAX_API_KEY })
 const request = LLM.request({
@@ -335,8 +349,7 @@ const request = LLM.request({
   generation: { maxTokens: 1536 },
 })
 
-const layer = LLMClient.layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
-const response = await Effect.runPromise(LLMClient.generate(request).pipe(Effect.provide(layer)))
+const response = await Effect.runPromise(LLM.generate(request).pipe(Effect.provide(AIClient.layer)))
 console.log(response.text)
 ```
 
@@ -405,14 +418,14 @@ Use `Image.generate` for one-off generation or editing:
 import { Image, Media } from "@opencode/ai"
 
 const generation = Image.generate({
-  model: meta("muse-image-1.0"),
+  model: meta.image("muse-image-1.0"),
   prompt: "A flat black square on a white background.",
   n: 1,
   providerOptions: { reasoningStrength: "low" },
 })
 
 const edit = Image.generate({
-  model: meta("muse-image-1.0"),
+  model: meta.image("muse-image-1.0"),
   prompt: "Make the square purple.",
   images: [Media.bytes(imageBytes, "image/webp")],
   format: "png",
@@ -459,6 +472,25 @@ const program = Effect.gen(function* () {
 })
 ```
 
+Common fields are portable in shape, not in support. Unsupported fields fail with a typed `AIError` before any network
+call rather than being dropped, so check this table before swapping only the `model`:
+
+| Provider              | `n` | `size`    | `aspectRatio` | `seed` | `format` | `images`                         | `mask`              |
+| --------------------- | --- | --------- | ------------- | ------ | -------- | -------------------------------- | ------------------- |
+| OpenAI                | ✓¹  | ✓         | ✗             | ✗      | ✓        | ✓                                | ✓                   |
+| Google (Gemini)       | 1   | ✗         | ✓             | ✓      | ✗        | ✓ (no public URLs)               | ✗                   |
+| xAI                   | ✓   | ✗         | ✓             | ✗      | ✗        | ✓                                | ✗                   |
+| Z.ai                  | ✗   | ✓         | ✗             | ✗      | ✗        | ✗                                | ✗                   |
+| Meta                  | ✓   | ✓ (hint)  | ✗             | ✗      | ✓        | ✓                                | ✗                   |
+| Black Forest Labs     | 1   | per model | per model     | ✓      | ✓        | per model (1–8)                  | `flux-pro-1.0-fill` |
+| fal                   | ✓   | per model | per model     | ✓      | ✓        | 1 (several on `/edit`, `/multi`) | ✓                   |
+| Replicate             | ✗   | ✗         | ✗             | ✗      | ✗        | ✗ (use `providerOptions`)        | ✗                   |
+| Stability `image`     | 1   | ✗         | ✓             | ✓      | ✓        | 1 (not on `core`)                | ✗                   |
+| Stability `upscale()` | ✗   | ✗         | ✗             | ✓      | ✓        | exactly 1 (required)             | ✗                   |
+
+✓ lowers natively; ✗ fails whenever the field is set (including `n: 1`); `1` means `n > 1` fails. ¹ `Image.stream` on OpenAI generates one image. fal
+rejects `size` and `aspectRatio` together; which one a fal or BFL model takes depends on the model.
+
 `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`
@@ -468,9 +500,8 @@ asset into owned bytes before the provider URL expires. Construct assets with `M
 Pass ordered image inputs to the same method for editing, composition, or image-conditioned generation:
 
 ```ts
-const response =
-  yield *
-  Image.generate({
+const composed = Effect.gen(function* () {
+  const response = yield* Image.generate({
     model,
     prompt: "Combine these product photos into one studio scene",
     images: [
@@ -481,23 +512,25 @@ const response =
     providerOptions,
     http,
   })
+  return response.images
+})
 ```
 
 `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
+only forward refs that belong to their own provider (OpenAI, xAI, and Gemini images accept them). No shipped route
+returns a ref yet, and `asset.bytes()` / `materialize()` on a ref fail by design. 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 (see the table above for routes that limit the count). 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.image("gpt-image-2"),
-    prompt,
-    images: [Media.bytes(sourceBytes, "image/png")],
-    mask: Media.bytes(maskBytes, "image/png"),
-  })
+const inpainted = Image.generate({
+  model: openai.image("gpt-image-2"),
+  prompt,
+  images: [Media.bytes(sourceBytes, "image/png")],
+  mask: Media.bytes(maskBytes, "image/png"),
+})
 ```
 
 On multipart requests, `http.body` can override option fields but not structural `model`, `prompt`, `image[]`,
@@ -508,31 +541,31 @@ not accept image inputs. These cases fail with a typed `AIError` before network
 Provider-native image options belong to each request. Raw `http.body` fields have final precedence over them:
 
 ```ts
-yield *
-  Image.generate({
-    model: openai.image("gpt-image-2"),
-    prompt,
-    providerOptions: { quality: "medium" },
-    http,
-  })
+const medium = Image.generate({
+  model: openai.image("gpt-image-2"),
+  prompt,
+  providerOptions: { quality: "medium" },
+  http,
+})
 ```
 
 xAI image models use the same request API with xAI-native controls:
 
 ```ts
-yield *
-  Image.generate({
-    model: XAI.configure({ apiKey })("any-model-id"),
-    prompt,
-    n: 2,
-    aspectRatio: "16:9",
-    providerOptions: {
-      resolution: "1k",
-      responseFormat: "b64_json",
-      future_option: true,
-    },
-    http,
-  })
+import { XAI } from "@opencode/ai/providers"
+
+const xai = Image.generate({
+  model: XAI.configure({ apiKey }).image("any-model-id"),
+  prompt,
+  n: 2,
+  aspectRatio: "16:9",
+  providerOptions: {
+    resolution: "1k",
+    responseFormat: "b64_json",
+    future_option: true,
+  },
+  http,
+})
 ```
 
 Google's current Gemini image models use the same direct API:
@@ -542,7 +575,7 @@ import { Google } from "@opencode/ai/providers"
 
 const googleProgram = Effect.gen(function* () {
   const response = yield* Image.generate({
-    model: Google.configure({ apiKey })("any-model-id"),
+    model: Google.configure({ apiKey }).image("any-model-id"),
     prompt: "A robot tending a rooftop garden",
     aspectRatio: "16:9",
     seed: 42,
@@ -567,17 +600,18 @@ their mapped aliases, and `http.body` is the final deep overlay. The selected mo
 Z.ai image models infer open Z.ai-native options from the selected model:
 
 ```ts
-yield *
-  Image.generate({
-    model: ZAI.configure({ apiKey })("any-model-id"),
-    prompt,
-    providerOptions: {
-      quality: "hd",
-      userID: "user-123",
-      future_option: true,
-    },
-    http,
-  })
+import { ZAI } from "@opencode/ai/providers"
+
+const zai = Image.generate({
+  model: ZAI.configure({ apiKey }).image("any-model-id"),
+  prompt,
+  providerOptions: {
+    quality: "hd",
+    userID: "user-123",
+    future_option: true,
+  },
+  http,
+})
 ```
 
 Z.ai does not include trustworthy MIME metadata for output URLs, so generated images use
@@ -587,16 +621,17 @@ 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:
+and emits `image-partial` events before each final `image`; `Image.generate` keeps the plain JSON request:
 
 ```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)))
+import { Stream } from "effect"
+import { ImageEvent } from "@opencode/ai"
+
+const previews = 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.
@@ -612,13 +647,20 @@ 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 submit = Effect.gen(function* () {
+  const generation = yield* Image.start({ model: bfl.image("flux-2-pro"), prompt, size: "1024x768" })
+  persist({ provider: "black-forest-labs", modelID: "flux-2-pro", token: generation.token })
+})
 
-const resumed = yield * Image.resume(bfl.image("flux-2-pro"), loadToken())
-const response = yield * resumed.await({ poll: { interval: "2 seconds" } })
+const finish = Effect.gen(function* () {
+  const saved = load()
+  const resumed = yield* Image.resume(bfl.image(saved.modelID), saved.token)
+  return yield* resumed.await({ poll: { interval: "2 seconds" } })
+})
 ```
 
+The token carries no route identity, so persist the provider and model ID alongside it: `resume` needs the model.
+
 - **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).
@@ -628,12 +670,13 @@ const response = yield * resumed.await({ poll: { interval: "2 seconds" } })
 
 ```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")] },
+const upscaled = Effect.gen(function* () {
+  const small = yield* Media.file("./small.png")
+  return yield* Image.generate(
+    { model: stability.upscale(), prompt: "A lighthouse", images: [small] },
     { poll: { interval: "5 seconds" } },
   )
+})
 ```
 
 Imagen is not available: Google shut it down on the Gemini API, and Vertex discontinued the Imagen 4 models on
@@ -655,7 +698,7 @@ const program = Effect.gen(function* () {
 })
 ```
 
-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.
+The hosted result is represented as a provider-executed tool call and a tool result whose content carries the generated image as a file. Gemini image-capable models instead emit a first-class `media` `LLMEvent` for inline image output (`response.message` then carries a `media` part). Retaining `response.message` preserves the generated image for continuation on both routes.
 
 ## Video generation
 
@@ -666,8 +709,8 @@ Common fields (`frames`, `references`, `video`, `durationSeconds`, `aspectRatio`
 under `providerOptions`, inferred from the selected model.
 
 ```ts
-import { Video, VideoClient } from "@opencode/ai"
-import { Google } from "@opencode/ai/providers"
+import { Video } from "@opencode/ai"
+import { Google, Runway } from "@opencode/ai/providers"
 
 const google = Google.configure({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY })
 
@@ -696,6 +739,7 @@ const controlled = Effect.gen(function* () {
   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
+  // The token carries no route identity: persist the provider and model ID alongside it, since `resume` needs the model.
   const saved = JSON.stringify(generation.token)
 
   const resumed = yield* Video.resume(google.video("veo-3.1-generate-preview"), JSON.parse(saved))
@@ -706,8 +750,8 @@ const controlled = Effect.gen(function* () {
 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
+Status polls, result fetches, cancels, and asset downloads all run through the same request 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
@@ -726,15 +770,18 @@ Provider notes:
 - **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.
+The promise client exposes the same surface: `ai.video.start(...)` resolves to a handle with `await`, `events`,
+`result`, `refresh`, `cancel`, and `token`; `ai.video.generate`, `ai.video.resume(model, token)`, and
+`ai.video.stream` mirror the Effect API. The handle's `status` and `progress` are a snapshot from when it was
+created; `refresh()` resolves to a new handle.
 
 ```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 })
+for await (const event of generation.events({ poll: { interval: 10_000 } })) console.log(event.type)
+const video = await generation.result({ signal })
+await ai.write(video.video, "./kite.mp4")
 ```
 
 ## Speech generation
@@ -786,16 +833,16 @@ ElevenLabs and Cartesia. `{ id }` selects an OpenAI custom voice (`{ id: "voice_
 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
+- **Gemini TTS** returns the provider's default output: WAV for Gemini 3.8 TTS `generate`, raw 16-bit PCM
+  (`audio/L16;codec=pcm;rate=24000`) otherwise. `pcm` is the only explicit `format` it accepts, and it fails typed on
+  Gemini 3.8 `generate`; the route never wraps PCM as WAV. 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`);
@@ -814,7 +861,7 @@ The promise client mirrors the Effect API; `ai.speech.stream` is an `AsyncIterab
 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()))
+await ai.write(response.audio, "hello.mp3")
 
 for await (const event of ai.speech.stream({ model, text: "Hello from OpenCode.", voice: "coral" })) {
   if (event.type === "audio-delta") player.write(event.chunk)
@@ -831,6 +878,7 @@ facades. Common fields (`language`, `prompt`, `timestamps: "none" | "segment" |
 natively or fail with a typed `AIError` before any network call; a route may return more than asked.
 
 ```ts
+import { Console, Effect, Stream } from "effect"
 import { Media, Transcription, TranscriptionEvent } from "@opencode/ai"
 import { AssemblyAI, Deepgram, OpenAI } from "@opencode/ai/providers"
 
@@ -857,7 +905,7 @@ const program = Effect.gen(function* () {
     Stream.runDrain,
   )
 
-  // Queued: persist the token, resume from another process, and await.
+  // Queued: persist the token with the provider and model ID (the token alone cannot pick the model), resume, 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)))
@@ -866,7 +914,7 @@ const program = Effect.gen(function* () {
 ```
 
 Inline routes emit only `finish` from `stream` (no faked deltas); queued routes emit `generation-queued` /
-`generation-progress` before it. `TranscriptionClient.layer` needs `RequestExecutor.Service`.
+`generation-progress` before it.
 
 Provider notes:
 
@@ -878,6 +926,7 @@ Provider notes:
 The promise client mirrors the Effect API:
 
 ```ts
+const audio = await ai.file("./call.mp3")
 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 })
@@ -887,7 +936,7 @@ const transcript = await generation.await({ poll: { interval: 3_000 } })
 ## Public API
 
 - **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
-- **`LLM.generate` / `LLM.stream`** — re-exported from `LLMClient` for one-import use.
+- **`LLM.generate` / `LLM.stream`** — run direct input or an `LLMRequest` through `LLMClient` for one-import use.
 - **`Message.user(...)` / `Message.assistant(...)` / `Message.tool(...)`** — message constructors from the canonical schema model.
 - **`LanguageModel.make(...)` / `ToolCallPart.make(...)` / `ToolResultPart.make(...)` / `ToolDefinition.make(...)`** — model and tool-related constructors from the canonical schema model.
 - **`LLMEvent.is.*`** — typed guards (`is.textDelta`, `is.toolCall`, `is.finish`, …) for filtering streams.
@@ -895,9 +944,11 @@ const transcript = await generation.await({ poll: { interval: 3_000 } })
 - **`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.
+- **`Video.request` / `generate` / `stream` / `start` / `resume`** — queued video generation through a provider-neutral request; `VideoClient` is its Effect service and layer.
 - **`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.
+- **`AIClient.layer` / `AIClient.layerWith(executor)`** — every modality client plus the request executor in one layer.
+- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, and `transcription` as Promise / `AsyncIterable` APIs, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets.
 
 ## Testing
 
@@ -960,11 +1011,13 @@ This is different from prompt caching, server-side history storage, or truncatio
 Prefer this operation, where supported, when the application owns compaction policy and durable context updates.
 
 ```ts
-const result = yield * LLMClient.compact(request)
-const next = LLMRequest.update(request, {
-  messages: result.replacement,
+const compacted = Effect.gen(function* () {
+  const result = yield* LLMClient.compact(request)
+  const next = LLMRequest.update(request, {
+    messages: result.replacement,
+  })
+  return yield* LLMClient.generate(next)
 })
-const response = yield * LLMClient.generate(next)
 ```
 
 `replacement` replaces the complete input window. Do not append it to the original transcript or extract only the encrypted item: the provider may retain additional messages in its output. Retained user and assistant messages remain ordinary messages with typed text, media, or reasoning parts, in their original order. Provider-specific message IDs, status, and phase use `providerMetadata`, not a raw output array hidden in an assistant message. Unsupported returned item types fail explicitly.
@@ -980,16 +1033,16 @@ The input must still fit the model's context window. Explicit compaction is not
 OpenAI Responses also exposes a separate, explicitly selected mechanism:
 
 ```ts
-const result =
-  yield *
-  LLMClient.compact(request, {
+const checkpoint = Effect.gen(function* () {
+  const result = yield* LLMClient.compact(request, {
     mechanism: "trigger",
     webSocket, // Optional: without it, the request uses HTTP/SSE.
   })
 
-result.checkpoint // Successful encrypted CompactionPart.
-result.responseID
-result.usage
+  result.checkpoint // Successful encrypted CompactionPart.
+  result.responseID
+  result.usage
+})
 ```
 
 This appends a native `compaction_trigger` control item to the full input and sends a normal Responses request, with tools and instructions retained, `stream: true`, `store: false`, and parallel tool calls enabled. It removes normal-answer text/output-format controls, forced tool choices, output-token/tool-call limits, and automatic `context_management`. Body overlays cannot replace `input` or supply `previous_response_id`/`conversation`; the complete canonical history is required for safe stateless replay. Request metadata, auth, headers, query parameters, service tier, and supported prompt-cache settings are preserved.
@@ -1003,9 +1056,11 @@ The supplied WebSocket executor can reuse a compatible append baseline for the c
 Trigger support is separate from endpoint support. Only the OpenAI Responses route advertises it; Azure, xAI, Chat, and compatible Responses routes do not inherit it. Untyped calls still fail before sending: missing route capabilities return `UnsupportedOperation`, while unknown mechanism names and invalid inputs return `InvalidRequest`. Dynamic callers must narrow for the selected mechanism:
 
 ```ts
-if (LLMClient.canCompact(request, { mechanism: "trigger" })) {
-  const result = yield * LLMClient.compact(request, { mechanism: "trigger" })
-}
+const narrowed = Effect.gen(function* () {
+  if (LLMClient.canCompact(request, { mechanism: "trigger" })) {
+    const result = yield* LLMClient.compact(request, { mechanism: "trigger" })
+  }
+})
 ```
 
 This capability describes protocol implementation, **not universal availability on OpenAI API deployments**. The host application owns subscription/deployment eligibility, OAuth, endpoint selection, and deployment-specific headers. Local protocol/socket tests do not establish live provider support.
@@ -1014,9 +1069,10 @@ This capability describes protocol implementation, **not universal availability
 
 `providerOptions.contextManagement` lets the provider decide when to compact during an ordinary `generate` or `stream` call. This is an advanced option for callers that own persistence and recovery: persist the complete assistant message, including its checkpoint, before continuing. Enabling the option does not provide durable checkpoint storage, interruption recovery, or model-switch policy. Keep the prior context until a successful checkpoint has been persisted.
 
-Inside an `Effect.gen`, enable OpenAI compaction with typed provider options:
+Enable OpenAI compaction with typed provider options:
 
 ```ts
+import { Effect } from "effect"
 import { LLM, LLMClient, LLMRequest, Message } from "@opencode/ai"
 import { OpenAI } from "@opencode/ai/providers"
 
@@ -1027,9 +1083,11 @@ const request = LLM.request({
     contextManagement: [{ type: "compaction", compactThreshold: 200_000 }],
   },
 })
-const response = yield * LLMClient.generate(request)
-const next = LLMRequest.update(request, {
-  messages: [...request.messages, response.message, Message.user("Continue")],
+const continued = Effect.gen(function* () {
+  const response = yield* LLMClient.generate(request)
+  return LLMRequest.update(request, {
+    messages: [...request.messages, response.message, Message.user("Continue")],
+  })
 })
 ```
 
@@ -1257,7 +1315,7 @@ Compose a route with `Route.make({ protocol, endpoint, auth, framing, ... })`. T
 
 ## Effect
 
-This package is built on Effect. Public methods return `Effect` or `Stream`; provide `LLMClient.layer` for LLM dispatch and `ImageClient.layer` for image dispatch, then import the provider/protocol modules for the routes you use. The example at `example/tutorial.ts` is a runnable walkthrough.
+This package is built on Effect. Public methods return `Effect` or `Stream`; provide `AIClient.layer` (or `AIClient.layerWith(executor)`) for every modality, then import the provider/protocol modules for the routes you use. The example at `example/tutorial.ts` is a runnable walkthrough.
 
 ## See also
 

package/dist/ai-client.d.ts

@@ -0,0 +1,8 @@
+import { Layer } from "effect";
+import { RequestExecutor } from "./route/executor.js";
+/** Every modality client over `executor`, which stays in the output so `asset.bytes()` and `Media.write` resolve. */
+export declare const layerWith: <E, R>(executor: Layer.Layer<RequestExecutor.Service, E, R>) => Layer.Layer<import("./route/executor-service.js").RequestExecutorService | import("./route/client.js").LLMClientService | import("./image-client.js").ImageClientService | import("./speech-client.js").SpeechClientService | import("./transcription-client.js").TranscriptionClientService | import("./video-client.js").VideoClientService, E, R>;
+/** Every modality client plus the executor over `RequestExecutor.fetchLayer`: the one layer most programs need. */
+export declare const layer: Layer.Layer<import("./route/executor-service.js").RequestExecutorService | import("./route/client.js").LLMClientService | import("./image-client.js").ImageClientService | import("./speech-client.js").SpeechClientService | import("./transcription-client.js").TranscriptionClientService | import("./video-client.js").VideoClientService, never, never>;
+export type Services = Layer.Success<typeof layer>;
+export * as AIClient from "./ai-client.js";

package/dist/ai-client.js

@@ -0,0 +1,12 @@
+import { Layer } from "effect";
+import { ImageClient } from "./image-client.js";
+import { LLMClient } from "./route/client.js";
+import { RequestExecutor } from "./route/executor.js";
+import { SpeechClient } from "./speech-client.js";
+import { TranscriptionClient } from "./transcription-client.js";
+import { VideoClient } from "./video-client.js";
+/** Every modality client over `executor`, which stays in the output so `asset.bytes()` and `Media.write` resolve. */
+export const layerWith = (executor) => Layer.mergeAll(LLMClient.layer, ImageClient.layer, VideoClient.layer, SpeechClient.layer, TranscriptionClient.layer).pipe(Layer.provideMerge(executor));
+/** Every modality client plus the executor over `RequestExecutor.fetchLayer`: the one layer most programs need. */
+export const layer = layerWith(RequestExecutor.fetchLayer);
+export * as AIClient from "./ai-client.js";