@opencode/ai 2.0.15 → 2.0.16

package/README.md

@@ -584,6 +584,61 @@ Z.ai does not include trustworthy MIME metadata for output URLs, so generated im
 `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:
 
 ```ts
@@ -602,6 +657,233 @@ 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.
 
+## 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
 
 - **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
@@ -609,11 +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.request` / `Image.generate` / `Image.stream`** — 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.
-- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm` and `image` as Promise / `AsyncIterable` APIs.
+- **`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/generation.d.ts

@@ -12,13 +12,13 @@ export interface Snapshot {
     readonly expiresAt?: number;
 }
 /**
- * Route-owned generation operations. `token` is the route's serializable handle (operation name, task id, response URL)
- * so a generation can be resumed from another process; its shape is opaque to `Generation`.
+ * Route-owned generation operations for one generation. The media route decodes its serializable token once (from the
+ * submission response or a `resume` input) and closes over it, so `Generation` never sees the token's shape.
  */
 export interface Route<Response> {
-    readonly status: (token: unknown) => Effect.Effect<Snapshot, AIError>;
-    readonly result: (token: unknown) => Effect.Effect<Response, AIError>;
-    readonly cancel?: (token: unknown) => Effect.Effect<void, AIError>;
+    readonly status: Effect.Effect<Snapshot, AIError>;
+    readonly result: Effect.Effect<Response, AIError>;
+    readonly cancel?: Effect.Effect<void, AIError>;
     /** Provider polling hint (e.g. `openai-poll-after-ms`) that overrides the default interval for the next poll. */
     readonly pollHint?: (snapshot: Snapshot) => Duration.Duration | undefined;
 }
@@ -28,42 +28,56 @@ export interface Poll {
     /** Full override of the polling schedule; `interval` and `pollHint` are ignored when supplied. */
     readonly schedule?: Schedule.Schedule<unknown, Snapshot>;
 }
+export interface AwaitOptions {
+    readonly poll?: Poll;
+}
 export declare const DEFAULT_POLL_INTERVAL: Duration.Duration;
 export declare const DEFAULT_POLL_TIMEOUT: Duration.Duration;
-export type Event = {
-    readonly type: "generation-queued";
-    readonly id: string;
-    readonly position?: number;
-} | {
-    readonly type: "generation-progress";
-    readonly id: string;
-    readonly progress?: number;
-} | {
+export declare const QueuedEvent: Schema.Struct<{
+    readonly type: Schema.tag<"generation-queued">;
+    readonly id: Schema.String;
+    readonly position: Schema.optional<Schema.Number>;
+}>;
+export declare const ProgressEvent: Schema.Struct<{
+    readonly type: Schema.tag<"generation-progress">;
+    readonly id: Schema.String;
+    readonly progress: Schema.optional<Schema.Number>;
+}>;
+export type Observation = Schema.Schema.Type<typeof QueuedEvent> | Schema.Schema.Type<typeof ProgressEvent>;
+export type Event = Observation | {
     readonly type: "generation-finished";
     readonly id: string;
     readonly status: Status;
 };
 export declare class Generation<Response> {
     readonly route: Route<Response>;
+    /** Route-owned serializable JSON; pass it to the modality's `resume` from another process. */
     readonly token: unknown;
     readonly id: string;
     readonly status: Status;
     readonly progress?: number;
     readonly position?: number;
     readonly expiresAt?: number;
-    constructor(route: Route<Response>, token: unknown, snapshot: Snapshot);
+    constructor(route: Route<Response>, 
+    /** Route-owned serializable JSON; pass it to the modality's `resume` from another process. */
+    token: unknown, snapshot: Snapshot);
     get snapshot(): Snapshot;
     get terminal(): boolean;
     refresh(): Effect.Effect<Generation<Response>, AIError>;
+    /** Fetch the result without polling; non-completed terminal generations fail with the provider's terminal body. */
+    result(): Effect.Effect<Response, AIError>;
     /** Poll until the generation reaches a terminal status, then fetch the result. Fails with a `Timeout` reason on deadline. */
-    await(options?: {
-        readonly poll?: Poll;
-    }): Effect.Effect<Response, AIError>;
+    await(options?: AwaitOptions): Effect.Effect<Response, AIError>;
     cancel(): Effect.Effect<void, AIError>;
-    /** Status observations as a stream, ending after the first terminal observation. */
-    events(options?: {
-        readonly poll?: Poll;
-    }): Stream.Stream<Event, AIError>;
+    /**
+     * Status observations as a stream, ending after the first terminal observation. Each poll is bounded by the time
+     * remaining until `poll.timeout`, so a hung status request fails the stream instead of stalling it. (`Stream.interruptWhen`
+     * would express this directly but deadlocks under `TestClock` when the source completes while the timer sleeps.)
+     */
+    events(options?: AwaitOptions): Stream.Stream<Event, AIError>;
+    private event;
+    private timeoutError;
     private poll;
     private schedule;
 }
+export declare const resultEvents: <Response, A>(generation: Generation<Response>, expand: (response: Response) => ReadonlyArray<A>, options?: AwaitOptions) => Stream.Stream<Observation | A, AIError>;

package/dist/generation.js

@@ -1,8 +1,18 @@
-import { Duration, Effect, Schedule, Schema, Stream } from "effect";
+import { Clock, Duration, Effect, Schedule, Schema, Stream } from "effect";
 import { AIError, TimeoutError } from "./schema/errors.js";
 export const Status = Schema.Literals(["queued", "running", "completed", "failed", "cancelled", "expired"]);
 export const DEFAULT_POLL_INTERVAL = Duration.seconds(5);
 export const DEFAULT_POLL_TIMEOUT = Duration.minutes(10);
+export const QueuedEvent = Schema.Struct({
+    type: Schema.tag("generation-queued"),
+    id: Schema.String,
+    position: Schema.optional(Schema.Number),
+}).annotate({ identifier: "Generation.Event.Queued" });
+export const ProgressEvent = Schema.Struct({
+    type: Schema.tag("generation-progress"),
+    id: Schema.String,
+    progress: Schema.optional(Schema.Number),
+}).annotate({ identifier: "Generation.Event.Progress" });
 const TERMINAL = new Set(["completed", "failed", "cancelled", "expired"]);
 export class Generation {
     route;
@@ -12,7 +22,9 @@ export class Generation {
     progress;
     position;
     expiresAt;
-    constructor(route, token, snapshot) {
+    constructor(route, 
+    /** Route-owned serializable JSON; pass it to the modality's `resume` from another process. */
+    token, snapshot) {
         this.route = route;
         this.token = token;
         this.id = snapshot.id;
@@ -34,7 +46,11 @@ export class Generation {
         return TERMINAL.has(this.status);
     }
     refresh() {
-        return this.route.status(this.token).pipe(Effect.map((snapshot) => new Generation(this.route, this.token, snapshot)));
+        return this.route.status.pipe(Effect.map((snapshot) => new Generation(this.route, this.token, snapshot)));
+    }
+    /** Fetch the result without polling; non-completed terminal generations fail with the provider's terminal body. */
+    result() {
+        return this.route.result;
     }
     /** Poll until the generation reaches a terminal status, then fetch the result. Fails with a `Timeout` reason on deadline. */
     await(options) {
@@ -42,31 +58,43 @@ export class Generation {
         const settled = this.terminal ? Effect.succeed(this) : this.poll(options?.poll);
         return settled.pipe(
         // Non-completed terminal states also go through `result` so the route can surface its provider failure body.
-        Effect.flatMap((generation) => generation.route.result(generation.token)), Effect.timeoutOrElse({
-            duration: timeout,
-            orElse: () => new AIError({
-                reason: new TimeoutError({
-                    message: `Generation ${this.id} did not finish within ${Duration.format(timeout)}`,
-                    timeoutMs: Duration.toMillis(timeout),
-                }),
-            }),
-        }));
+        Effect.flatMap((generation) => generation.result()), Effect.timeoutOrElse({ duration: timeout, orElse: () => this.timeoutError(timeout) }));
     }
     cancel() {
-        return this.route.cancel?.(this.token) ?? Effect.void;
+        return this.route.cancel ?? Effect.void;
     }
-    /** Status observations as a stream, ending after the first terminal observation. */
+    /**
+     * Status observations as a stream, ending after the first terminal observation. Each poll is bounded by the time
+     * remaining until `poll.timeout`, so a hung status request fails the stream instead of stalling it. (`Stream.interruptWhen`
+     * would express this directly but deadlocks under `TestClock` when the source completes while the timer sleeps.)
+     */
     events(options) {
-        const observations = this.terminal
-            ? Stream.make(this)
-            : Stream.fromEffectSchedule(this.refresh(), this.schedule(options?.poll)).pipe(Stream.takeUntil((generation) => generation.terminal));
-        return observations.pipe(Stream.map((generation) => {
-            if (generation.terminal)
-                return { type: "generation-finished", id: generation.id, status: generation.status };
-            if (generation.status === "queued")
-                return { type: "generation-queued", id: generation.id, position: generation.position };
-            return { type: "generation-progress", id: generation.id, progress: generation.progress };
-        }));
+        if (this.terminal)
+            return Stream.make(this.event());
+        const timeout = Duration.fromInputUnsafe(options?.poll?.timeout ?? DEFAULT_POLL_TIMEOUT);
+        return Stream.unwrap(Clock.currentTimeMillis.pipe(Effect.map((start) => {
+            const deadline = start + Duration.toMillis(timeout);
+            const refresh = Clock.currentTimeMillis.pipe(Effect.flatMap((now) => this.refresh().pipe(Effect.timeoutOrElse({
+                duration: Duration.millis(Math.max(0, deadline - now)),
+                orElse: () => this.timeoutError(timeout),
+            }))));
+            return Stream.fromEffectSchedule(refresh, this.schedule(options?.poll)).pipe(Stream.takeUntil((generation) => generation.terminal), Stream.map((generation) => generation.event()));
+        })));
+    }
+    event() {
+        if (this.terminal)
+            return { type: "generation-finished", id: this.id, status: this.status };
+        if (this.status === "queued")
+            return { type: "generation-queued", id: this.id, position: this.position };
+        return { type: "generation-progress", id: this.id, progress: this.progress };
+    }
+    timeoutError(timeout) {
+        return new AIError({
+            reason: new TimeoutError({
+                message: `Generation ${this.id} did not finish within ${Duration.format(timeout)}`,
+                timeoutMs: Duration.toMillis(timeout),
+            }),
+        });
     }
     poll(poll) {
         return this.refresh().pipe(Effect.repeat({ schedule: this.schedule(poll), until: (generation) => generation.terminal }));
@@ -82,3 +110,4 @@ export class Generation {
         return spaced.pipe(Schedule.modifyDelay((metadata) => Effect.succeed(pollHint(metadata.input.snapshot) ?? interval)));
     }
 }
+export const resultEvents = (generation, expand, options) => generation.events(options).pipe(Stream.filter((event) => event.type !== "generation-finished"), Stream.concat(Stream.fromIterableEffect(Effect.map(generation.result(), expand))));

package/dist/image-client.d.ts

@@ -1,21 +1,28 @@
 import { Context, Effect, Layer, Stream } from "effect";
+import type { AwaitOptions, Generation } from "./generation.js";
 import { RequestExecutor } from "./route/executor.js";
 import type { AIError } from "./schema/index.js";
-import { type ImageEvent, type ImageOptions, type ImageRequestFor, type ImageResponse } from "./image.js";
+import { type ImageEvent, type ImageModel, type ImageOptions, type ImageRequestFor, type ImageResponse } from "./image.js";
 export interface Interface {
-    readonly generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<ImageResponse, AIError>;
-    readonly stream: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Stream.Stream<ImageEvent, AIError>;
+    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>;
 }
 declare const Service_base: Context.ServiceClass<Service, "@opencode/ImageClient", Interface>;
 export declare class Service extends Service_base {
 }
-export declare const generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<ImageResponse, AIError, Service>;
-export declare const stream: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Stream.Stream<ImageEvent, AIError, Service>;
+export declare const generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>, options?: AwaitOptions) => Effect.Effect<ImageResponse, AIError, Service>;
+export declare const stream: <Options extends ImageOptions>(request: ImageRequestFor<Options>, options?: AwaitOptions) => Stream.Stream<ImageEvent, AIError, Service>;
+export declare const start: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<Generation<ImageResponse>, AIError, Service>;
+export declare const resume: <Options extends ImageOptions>(model: ImageModel<Options>, token: unknown) => Effect.Effect<Generation<ImageResponse>, AIError, Service>;
 export declare const layer: Layer.Layer<Service, never, RequestExecutor.Service>;
 export declare const ImageClient: {
     readonly Service: typeof Service;
     readonly layer: Layer.Layer<Service, never, RequestExecutor.Service>;
-    readonly generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<ImageResponse, AIError, Service>;
-    readonly stream: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Stream.Stream<ImageEvent, AIError, Service>;
+    readonly generate: <Options extends ImageOptions>(request: ImageRequestFor<Options>, options?: AwaitOptions) => Effect.Effect<ImageResponse, AIError, Service>;
+    readonly stream: <Options extends ImageOptions>(request: ImageRequestFor<Options>, options?: AwaitOptions) => Stream.Stream<ImageEvent, AIError, Service>;
+    readonly start: <Options extends ImageOptions>(request: ImageRequestFor<Options>) => Effect.Effect<Generation<ImageResponse>, AIError, Service>;
+    readonly resume: <Options extends ImageOptions>(model: ImageModel<Options>, token: unknown) => Effect.Effect<Generation<ImageResponse>, AIError, Service>;
 };
 export {};

package/dist/image-client.js

@@ -1,23 +1,37 @@
 import { Context, Effect, Layer, Stream } from "effect";
 import { RequestExecutor } from "./route/executor.js";
+import { MediaRoute } from "./route/media.js";
 import { responseEvents, } from "./image.js";
 export class Service extends Context.Service()("@opencode/ImageClient") {
 }
-export const generate = (request) => Effect.gen(function* () {
+export const generate = (request, options) => Effect.gen(function* () {
     const client = yield* Service;
-    return yield* client.generate(request);
+    return yield* client.generate(request, options);
 });
-export const stream = (request) => Stream.unwrap(Effect.gen(function* () {
+export const stream = (request, options) => Stream.unwrap(Effect.gen(function* () {
     const client = yield* Service;
-    return client.stream(request);
+    return client.stream(request, options);
 }));
+export const start = (request) => Effect.gen(function* () {
+    const client = yield* Service;
+    return yield* client.start(request);
+});
+export const resume = (model, token) => Effect.gen(function* () {
+    const client = yield* Service;
+    return yield* client.resume(model, token);
+});
 export const layer = Layer.effect(Service, Effect.gen(function* () {
     const executor = yield* RequestExecutor.Service;
-    const generate = (request) => request.model.route.generate(request, executor.execute);
+    const dispatch = MediaRoute.dispatch({
+        modality: "image",
+        execute: executor.execute,
+        responseEvents,
+    });
     return Service.of({
-        generate,
-        // Inline routes have no partial frames yet; the stream is the completed response expanded into events.
-        stream: (request) => Stream.unwrap(generate(request).pipe(Effect.map((response) => Stream.fromIterable(responseEvents(response))))),
+        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 = {
@@ -25,4 +39,6 @@ export const ImageClient = {
     layer,
     generate,
     stream,
+    start,
+    resume,
 };