@opencode/ai 0.0.0-dev-20061 → 0.0.0-dev-20065

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
@@ -836,7 +891,7 @@ const transcript = await generation.await({ poll: { interval: 3_000 } })
 - **`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.

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.fromIterableEffect(Effect.map(generate(request), responseEvents)),
+        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,
 };