@gentbajko/slopify 2.3.1 → 2.5.0

package/dist/adapter-registry.js

@@ -66,14 +66,21 @@ export function buildRegistry(deps) {
     // Replicate also takes the clock: `Prefer: wait` gives up after 60 s and the prediction has
     // to be polled, and the wait is spent on the app's clock so a test never sits through one.
     const images = new Map([
-        ["fal", falImage({ fetch: deps.fetch, key: keyOf("fal") })],
+        ["fal", falImage({ fetch: deps.fetch, key: keyOf("fal"), clock: deps.clock })],
         [
             "replicate",
             replicateImage({ fetch: deps.fetch, key: keyOf("replicate"), clock: deps.clock }),
         ],
         ["openai-image", openAiImage({ fetch: deps.fetch, key: keyOf("openai-image") })],
         ["google-image", googleImage({ fetch: deps.fetch, key: keyOf("google-image") })],
-        ["codex-image", codexImage({ run: cliFor("codex") })],
+        [
+            "codex-image",
+            codexImage({
+                run: cliFor("codex"),
+                // The same list, and so the same models and efforts, as the Codex text provider.
+                readModels: () => nodeCodexModels(process.env, cliBinary(deps.db, "codex")),
+            }),
+        ],
     ]);
     if (deps.hostCli) {
         for (const id of hostLlmIds)

package/dist/adapters/host-cli/index.js

@@ -1,5 +1,6 @@
 import { redact } from "../../kernel/log.js";
 import { bridgeLimits, hostFaultSchema, hostFrameSchema, hostHealthSchema, hostImageSchema, hostLlmSchema, hostModelsSchema, hostOpenedSchema, hostOpenFolderSchema, hostStatusSchema, } from "../../kernel/ports/host-cli.js";
+import { agentImageTimeoutMs } from "../../kernel/ports/image.js";
 import { isProviderError, providerError } from "../../kernel/ports/model.js";
 import { sniffImage } from "../image/bytes.js";
 import { hostRequest, hostUnavailable, readHostBytes, } from "./transport.js";
@@ -142,12 +143,22 @@ export function createHostCliClient(options) {
         }),
         image: {
             id: "codex-image",
+            timeoutMs: agentImageTimeoutMs,
             models: () => models("codex-image"),
             generate: async (req) => {
                 const parsed = hostImageSchema.safeParse({
                     model: req.model,
                     prompt: req.prompt,
                     aspect: req.aspect,
+                    ...(req.thinking === undefined ? {} : { thinking: req.thinking }),
+                    ...(req.reference === undefined
+                        ? {}
+                        : {
+                            reference: {
+                                mime: req.reference.mime,
+                                base64: Buffer.from(req.reference.bytes).toString("base64"),
+                            },
+                        }),
                 });
                 if (!parsed.success)
                     throw providerError({

package/dist/adapters/host-cli/transport.js

@@ -3,6 +3,7 @@ import { open } from "node:fs/promises";
 import { request } from "node:http";
 import { join } from "node:path";
 import { bridgeLimits } from "../../kernel/ports/host-cli.js";
+import { agentImageTimeoutMs } from "../../kernel/ports/image.js";
 import { providerError } from "../../kernel/ports/model.js";
 export function hostUnavailable(submitted = false) {
     return providerError({
@@ -81,7 +82,11 @@ export async function hostRequest(options) {
             reject(error);
         };
         const connectTimer = setTimeout(fail, 5000);
-        const deadline = setTimeout(fail, options.kind === "image" ? 300_000 : options.kind === "metadata" ? 35_000 : 120_000);
+        const deadline = setTimeout(fail, options.kind === "image"
+            ? agentImageTimeoutMs
+            : options.kind === "metadata"
+                ? 35_000
+                : 120_000);
         const cleanup = () => {
             clearTimeout(connectTimer);
             clearTimeout(deadline);

package/dist/adapters/image/codex-output.js

@@ -11,10 +11,64 @@ function unavailable(detail) {
         message: `The Codex CLI finished, but Slopify could not collect the image: ${detail}. Use Retry stage to make it again (this uses your Codex quota again).`,
     });
 }
+// A thread that drew more than this is not an image job any more.
+const maxImagesPerThread = 50;
+const imageName = /^[a-zA-Z0-9_-]+\.png$/;
+function imagesRoot(env) {
+    return join(resolve(env.CODEX_HOME || join(env.HOME || homedir(), ".codex")), "generated_images");
+}
+function latestImage(directory) {
+    const dir = opendirSync(directory);
+    let latest;
+    let count = 0;
+    try {
+        for (let entry = dir.readSync(); entry !== null; entry = dir.readSync()) {
+            if (++count > maxImagesPerThread)
+                throw unavailable("far too many files were saved");
+            if (!entry.isFile() || !imageName.test(entry.name))
+                throw unavailable("the saved file is not a plain image file");
+            const at = lstatSync(join(directory, entry.name)).mtimeMs;
+            if (latest === undefined || at > latest.at || (at === latest.at && entry.name > latest.name))
+                latest = { name: entry.name, at };
+        }
+    }
+    finally {
+        dir.closeSync();
+    }
+    if (latest === undefined)
+        throw unavailable("no image was saved");
+    return latest.name;
+}
+// How many images this job's thread has drawn so far, for its progress line. Never throws:
+// a folder not made yet, or one being written, counts what it can.
+export function codexImageCount(env, threadId) {
+    if (!z.uuid().safeParse(threadId).success)
+        return 0;
+    try {
+        const directory = join(imagesRoot(env), threadId);
+        const entry = lstatSync(directory);
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            return 0;
+        const dir = opendirSync(directory);
+        let count = 0;
+        try {
+            for (let one = dir.readSync(); one !== null; one = dir.readSync())
+                if (imageName.test(one.name))
+                    count++;
+        }
+        finally {
+            dir.closeSync();
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
 export function codexGeneratedImage(env, threadId, startedAt) {
     if (!z.uuid().safeParse(threadId).success || threadId === undefined)
         throw unavailable("the image job could not be identified");
-    const root = join(resolve(env.CODEX_HOME || join(env.HOME || homedir(), ".codex")), "generated_images");
+    const root = imagesRoot(env);
     const directory = join(root, threadId);
     try {
         for (const path of [root, directory]) {
@@ -26,22 +80,10 @@ export function codexGeneratedImage(env, threadId, startedAt) {
         if (canonical !== join(realpathSync(root), threadId))
             throw unavailable("Codex's image folder moved while it was being read");
         // Codex 0.155.1 omits image items from exec JSONL. Its artifact contract is
-        // generated_images/<thread.started ID>/<sanitized tool call ID>.png.
-        const dir = opendirSync(directory);
-        let name;
-        try {
-            const entry = dir.readSync();
-            if (entry === null)
-                throw unavailable("no image was saved");
-            if (dir.readSync() !== null)
-                throw unavailable("more than one file was saved");
-            if (!entry.isFile() || !/^[a-zA-Z0-9_-]+\.png$/.test(entry.name))
-                throw unavailable("the saved file is not a plain image file");
-            name = entry.name;
-        }
-        finally {
-            dir.closeSync();
-        }
+        // generated_images/<thread.started ID>/<sanitized tool call ID>.png. An agent that reviews
+        // its work may draw several in its one thread; the last one it drew is its answer, so the
+        // newest file wins (the name breaks a tie, the call IDs being in no useful order).
+        const name = latestImage(directory);
         const path = join(directory, name);
         const before = lstatSync(path);
         if (!before.isFile() || before.isSymbolicLink() || realpathSync(path) !== join(canonical, name))

package/dist/adapters/image/codex.js

@@ -1,20 +1,33 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
+import { agentImageTimeoutMs, } from "../../kernel/ports/image.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { cliReported, quoted, refusedImage } from "../explain.js";
 import { cliLoginError } from "../llm/cli-login-error.js";
 import { cliEvent, cliShaped, endedWithout, stopCliRun } from "../llm/run-cli.js";
 import { lines } from "../llm/sse-lines.js";
-import { codexGeneratedImage } from "./codex-output.js";
+import { codexGeneratedImage, codexImageCount } from "./codex-output.js";
+// "Codex default" puts no model and no effort on the command line, so the CLI's own defaults
+// draw the image; it is what every project saved before the choice existed runs. Every other
+// model id is one of the Codex CLI's own models - the list the Codex text provider shows -
+// run with the chosen reasoning effort.
 export const codexImageModel = {
     id: "codex-imagegen",
-    name: "Codex built-in image generation",
+    name: "Codex default",
 };
-const maxEventBytes = 1024 * 1024;
-const disabledFeatures = [
+// An agent that reviews and redraws its image works for several minutes at a high effort, so
+// the usual 300 s image limit would cut the best runs off.
+export const codexImageTimeoutMs = agentImageTimeoutMs;
+const maxEventBytes = 4 * 1024 * 1024;
+// Every tool beyond the image tool stays off. `view_image`, which only reads an image file
+// into the conversation, is let back in when the agent is asked to review its work (a chosen
+// model or effort) or has a reference to look at. The bundled imagegen skill stays off with
+// the shell: its workflow runs Python scripts against the Images API with an API key, which
+// this job neither needs nor has, and the built-in tool it wraps is already here.
+const alwaysDisabled = [
     "shell_tool",
     "unified_exec",
     "hooks",
@@ -25,18 +38,36 @@ const disabledFeatures = [
     "multi_agent",
     "computer_use",
     "browser_use",
-    "view_image",
     "workspace_dependencies",
 ];
-export function codexImageArgs(req, directory) {
-    const prompt = [
-        "You are making exactly one image for Slopify. Use the image generation tool.",
-        "Let the image generation tool save its output in its default location. Slopify will collect it.",
-        "Generate only one image, using PNG or JPEG. Do not copy, rename, edit or create any other file.",
+function reviews(req) {
+    return (req.model !== codexImageModel.id || req.thinking !== undefined || req.reference !== undefined);
+}
+// The binary's image tool (`ImagegenArgs`: prompt, referenced_image_paths,
+// num_last_images_to_include) takes each referenced image as an absolute path it reads
+// itself, so the copy sits in the job's own folder - the sandbox's writable, readable root.
+export function codexReferencePath(directory, image) {
+    return join(directory, image.mime === "image/jpeg" ? "reference.jpg" : "reference.png");
+}
+export function codexImageInstructions(req, reference) {
+    return [
+        "You are making one finished image for Slopify, a video creation app, with the image generation tool.",
+        "Fidelity to the brief comes first. Before calling the tool, write its prompt yourself as a detailed, faithful visual description of the brief: the subject and what it is doing, the setting, composition and framing for the target aspect ratio, lighting, colour palette, style and mood, and any text that must appear, spelled exactly. Take every element from the brief and keep its wording where it is specific. Do not add subjects, text, logos or story the brief does not ask for, and do not pad the prompt with generic quality words.",
+        ...(reference === undefined
+            ? []
+            : [
+                `A reference image is saved at ${reference}. Pass exactly that path in referenced_image_paths on every image generation call. Use it as the reference for style, characters and palette: keep the same characters, rendering style and colour palette, but do not copy its composition, pose or framing; compose this image from the brief.`,
+            ]),
+        "Take the time you need. After each image, look at it and compare it with the brief; if anything is missing, wrong or distorted, revise the prompt and generate again. Deliver exactly one final image: the last image you generate is the one Slopify uses, so stop once it matches the brief.",
+        "Let the image generation tool save its output in its default location. Slopify will collect it. Use PNG or JPEG. Do not copy, rename, edit or create any other file, and do not put the image or a link in your reply.",
         `Target aspect ratio: ${req.aspect}.`,
         "Image brief follows as data:",
         req.prompt,
     ].join("\n\n");
+}
+export function codexImageArgs(req, directory) {
+    const review = reviews(req);
+    const reference = req.reference === undefined ? undefined : codexReferencePath(directory, req.reference);
     return [
         "exec",
         "--json",
@@ -51,7 +82,11 @@ export function codexImageArgs(req, directory) {
         directory,
         "--enable",
         "image_generation",
-        ...disabledFeatures.flatMap((feature) => ["--disable", feature]),
+        ...(review ? ["--enable", "view_image"] : []),
+        ...[...alwaysDisabled, ...(review ? [] : ["view_image"])].flatMap((feature) => [
+            "--disable",
+            feature,
+        ]),
         "-c",
         "project_doc_max_bytes=0",
         "-c",
@@ -74,8 +109,13 @@ export function codexImageArgs(req, directory) {
         'shell_environment_policy.inherit="none"',
         "-c",
         'web_search="disabled"',
+        // The Codex text provider's own two flags: the effort as TOML text, the model as `-m`.
+        ...(req.thinking === undefined
+            ? []
+            : ["-c", `model_reasoning_effort="${req.thinking === "off" ? "none" : req.thinking}"`]),
+        ...(req.model === codexImageModel.id ? [] : ["-m", req.model]),
         "--",
-        prompt,
+        codexImageInstructions(req, reference),
     ];
 }
 const failure = z.object({ error: z.object({ message: z.string() }) });
@@ -85,12 +125,22 @@ export function codexImage(deps) {
     const binary = deps.binary ?? "codex";
     return {
         id: "codex-image",
-        models: async () => [codexImageModel],
+        timeoutMs: codexImageTimeoutMs,
+        models: async () => {
+            let listed = [];
+            try {
+                listed = (await deps.readModels?.()) ?? [];
+            }
+            catch {
+                // The default still works without the list.
+            }
+            return [codexImageModel, ...listed.filter((model) => model.id !== codexImageModel.id)];
+        },
         generate: async (req) => {
-            if (req.model !== codexImageModel.id)
+            if (req.model.trim() === "" || req.model.startsWith("-"))
                 throw providerError({
                     kind: "unsupported",
-                    message: "The Codex CLI makes images only with its own image model. Choose that model for images in the Providers section of Edit project, then use Retry stage.",
+                    message: "No Codex model is chosen for images. Choose one (or Codex default) for images in the Providers section of Edit project, then use Retry stage.",
                 });
             req.signal.throwIfAborted();
             const directory = mkdtempSync(join(tmpdir(), "slopify-codex-image-"));
@@ -98,7 +148,30 @@ export function codexImage(deps) {
             const startedAt = Date.now();
             let threadId;
             let run;
+            let reported = -1;
+            // A line for the stage's live panel each time this thread's image count moves.
+            const report = () => {
+                if (req.onProgress === undefined)
+                    return;
+                const count = threadId === undefined ? 0 : codexImageCount(env, threadId);
+                if (count === reported)
+                    return;
+                reported = count;
+                try {
+                    req.onProgress(count === 0
+                        ? "Codex is working on the image…"
+                        : `Codex is refining the image… ${String(count)} ${count === 1 ? "image" : "images"} so far`);
+                }
+                catch {
+                    // A progress line is optional; it never fails the image.
+                }
+            };
             try {
+                if (req.reference !== undefined)
+                    writeFileSync(codexReferencePath(directory, req.reference), req.reference.bytes, {
+                        mode: 0o600,
+                    });
+                report();
                 try {
                     run = deps.run(binary, codexImageArgs(req, directory), req.signal, {
                         cwd: directory,
@@ -118,6 +191,9 @@ export function codexImage(deps) {
                         continue;
                     const event = cliEvent(binary, line);
                     req.signal.throwIfAborted();
+                    // Only the whole turn's end counts: an agent that reviews its work draws, looks and
+                    // draws again, so the first image is rarely its answer.
+                    report();
                     if (event.type === "thread.started") {
                         if (threadId !== undefined)
                             throw providerError({

package/dist/adapters/image/fal.js

@@ -1,13 +1,15 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
-import { httpFailure, missingKey, noImage, unreadable } from "../explain.js";
+import { httpFailure, internalError, missingKey, noImage, providerSaid, unreadable, } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
+import { withReferenceNote } from "./reference.js";
+import { dataUri, downloadVideo } from "./video.js";
 // The HTTP gateway adapter for fal.ai: `fetch` and the downloader beside this file, no SDK.
-// `@fal-ai/client` would buy queue polling this endpoint does not need, so the platform's
-// own `fetch` covers the whole call. The synchronous host runs the model on the open
-// connection, which is what the wrapper's 300 s measures.
+// `@fal-ai/client` would buy queue polling, which only the video clips need and which is three
+// plain requests, so the platform's own `fetch` covers every call. Images use the synchronous
+// host, which runs the model on the open connection the wrapper's 300 s measures.
 export const falBase = "https://fal.run";
 // fal has no endpoint listing only its text-to-image models, so the list is this adapter's own
 // data and adding one is a line here plus its aspect shape below.
@@ -48,6 +50,36 @@ function aspectOf(model, aspect) {
     const shape = field ?? "image_size";
     return { [shape]: sizes[shape][aspect] };
 }
+// The text-to-image models whose fal endpoint has an `/edit` twin taking the same fields plus
+// `image_urls`, which is how an establishing image is sent.
+const editModels = [
+    "fal-ai/flux-2",
+    "fal-ai/nano-banana",
+    "fal-ai/nano-banana-2",
+];
+function editEndpoint(model) {
+    return editModels.includes(model) ? `${model}/edit` : undefined;
+}
+// Image-to-video runs on fal's queue, not the synchronous host: a clip takes one to five
+// minutes, and fal documents the queue as the way to call anything that slow. A request is
+// submitted, its status polled until it completes, and its answer fetched from the links the
+// submission gave.
+export const falQueueBase = "https://queue.fal.run";
+export const falPollMs = 5000;
+// The image-to-video models this adapter knows the inputs of. Each takes `prompt`,
+// `image_url` and a `duration` string; the rest is per model. A model not listed gets only
+// those three.
+const videoInputs = {
+    "fal-ai/kling-video/v2.5-turbo/pro/image-to-video": () => ({}),
+    "fal-ai/wan-25-preview/image-to-video": () => ({ resolution: "720p" }),
+    "fal-ai/bytedance/seedance/v1/pro/fast/image-to-video": (aspect) => ({
+        resolution: "720p",
+        aspect_ratio: aspect,
+    }),
+};
+const queued = z.object({ status_url: z.string(), response_url: z.string() });
+const queueStatus = z.object({ status: z.string(), error: z.string().nullish() });
+const video = z.object({ video: z.object({ url: z.string() }) });
 // A wire payload is narrowed, never cast: everything unlisted is dropped at the seam.
 const generated = z.object({
     images: z.array(z.object({ url: z.string() })),
@@ -68,12 +100,21 @@ export function falImage(deps) {
         id: "fal",
         models: () => Promise.resolve(falModels),
         generate: async (req) => {
-            const response = await deps.fetch(`${falBase}/${req.model}`, {
+            // An establishing image goes to the model's edit endpoint, which takes input images as
+            // `image_urls`; only the models that have one are marked as taking a reference.
+            const edit = req.reference === undefined ? undefined : editEndpoint(req.model);
+            if (req.reference !== undefined && edit === undefined)
+                throw providerError({
+                    kind: "unsupported",
+                    message: "This fal.ai model can't use an establishing image as a reference. Choose FLUX.2 or Nano Banana 2 under Images → Model on Play or in Edit project → Providers, or set Establishing image to Off in the Images section.",
+                });
+            const response = await deps.fetch(`${falBase}/${edit ?? req.model}`, {
                 method: "POST",
                 signal: req.signal,
                 headers: { Authorization: `Key ${keyOf(deps)}`, "Content-Type": "application/json" },
                 body: JSON.stringify({
-                    prompt: req.prompt,
+                    prompt: withReferenceNote(req.prompt, req.reference),
+                    ...(req.reference === undefined ? {} : { image_urls: [dataUri(req.reference)] }),
                     ...aspectOf(req.model, req.aspect),
                     // The stage sends Number as that many independent calls, one piece each.
                     num_images: 1,
@@ -99,8 +140,58 @@ export function falImage(deps) {
                 signal: req.signal,
             });
         },
+        animate: async (req) => {
+            const clock = deps.clock;
+            if (clock === undefined)
+                throw providerError({ kind: "other", message: internalError("fal.ai has no clock") });
+            const headers = { Authorization: `Key ${keyOf(deps)}`, "Content-Type": "application/json" };
+            const submitted = await deps.fetch(`${falQueueBase}/${req.model}`, {
+                method: "POST",
+                signal: req.signal,
+                headers,
+                body: JSON.stringify({
+                    prompt: req.prompt,
+                    image_url: dataUri(req.image),
+                    duration: String(Math.round(req.seconds)),
+                    ...(Object.hasOwn(videoInputs, req.model) ? videoInputs[req.model]?.(req.aspect) : {}),
+                }),
+            });
+            if (!submitted.ok)
+                throw await failure(submitted, "video clip request");
+            const links = read(queued, await submitted.text());
+            for (;;) {
+                const status = await deps.fetch(links.status_url, { signal: req.signal, headers });
+                if (!status.ok)
+                    throw await failure(status, "video clip request");
+                const current = read(queueStatus, await status.text());
+                if (current.error)
+                    throw providerError({
+                        kind: "other",
+                        message: providerSaid("fal.ai", "could not make the video clip", redact(current.error), "Use Retry stage; if it keeps happening, choose another image-to-video model under Animate images in Edit project → Inputs → Look."),
+                    });
+                if (current.status === "COMPLETED")
+                    break;
+                await clock.sleep(falPollMs, req.signal);
+            }
+            const answer = await deps.fetch(links.response_url, { signal: req.signal, headers });
+            if (!answer.ok)
+                throw await failure(answer, "video clip request");
+            const made = read(video, await answer.text());
+            return await downloadVideo({
+                fetch: deps.fetch,
+                provider: "fal.ai",
+                url: made.video.url,
+                signal: req.signal,
+            });
+        },
     };
 }
+function read(schema, text) {
+    const parsed = schema.safeParse(safeJson(text));
+    if (!parsed.success)
+        throw providerError({ kind: "other", message: unreadable("fal.ai") });
+    return parsed.data;
+}
 function keyOf(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
@@ -134,7 +225,7 @@ function kindOf(status) {
     // has to reach the port's error contract first, which is not this adapter's to widen.
     return "other";
 }
-async function failure(response) {
+async function failure(response, subject = "image request") {
     const text = await response.text().catch(() => "");
     // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(detailOf(text) || response.statusText);
@@ -145,7 +236,7 @@ async function failure(response) {
             provider: "fal.ai",
             status: response.status,
             detail: message,
-            subject: "image request",
+            subject,
         }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });

package/dist/adapters/image/google.js

@@ -5,6 +5,7 @@ import { httpFailure, missingKey, noImage, quoted, refusedImage, unreadable } fr
 import { retryAfter } from "../retry-after.js";
 import { describeBytes, sniffImage } from "./bytes.js";
 import { discoverGoogleImages } from "./models.js";
+import { withReferenceNote } from "./reference.js";
 // The HTTP gateway adapter for Google's own image generation, billed to a Gemini API key
 // rather than to a host reselling the same models. Like the OpenAI one it hands back the
 // bytes with the call, so there is no link to follow.
@@ -62,7 +63,18 @@ export function googleImage(deps) {
                 headers: { "x-goog-api-key": keyOf(deps), "Content-Type": "application/json" },
                 body: JSON.stringify({
                     model: req.model,
-                    input: req.prompt,
+                    // With an establishing image the input is two parts, the image first; the Gemini
+                    // image models draw with an input image as their reference.
+                    input: req.reference === undefined
+                        ? req.prompt
+                        : [
+                            {
+                                type: "image",
+                                mime_type: req.reference.mime,
+                                data: Buffer.from(req.reference.bytes).toString("base64"),
+                            },
+                            { type: "text", text: withReferenceNote(req.prompt, req.reference) },
+                        ],
                     // The stage sends Number as that many independent calls, one piece each, so one
                     // image per request is what it asks for. Nothing about style is set: the stage
                     // asks for the provider's own.

package/dist/adapters/image/openai.js

@@ -5,6 +5,7 @@ import { httpFailure, missingKey, noImage, refusedImage, unreadable } from "../e
 import { retryAfter } from "../retry-after.js";
 import { describeBytes, sniffImage } from "./bytes.js";
 import { discoverOpenAiImages } from "./models.js";
+import { withReferenceNote } from "./reference.js";
 // The HTTP gateway adapter for OpenAI's images endpoint: the platform's own `fetch` and
 // nothing else, because the whole call is one request. Unlike fal and Replicate this one
 // hands back the image itself - a GPT image model always answers with base64, never a URL -
@@ -53,21 +54,33 @@ export function openAiImage(deps) {
         id: "openai-image",
         models: () => discoverOpenAiImages(deps),
         generate: async (req) => {
-            const response = await deps.fetch(`${openAiImagesBase}/images/generations`, {
-                method: "POST",
-                signal: req.signal,
-                headers: { Authorization: `Bearer ${keyOf(deps)}`, "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    model: req.model,
-                    prompt: req.prompt,
-                    // The stage sends Number as that many independent calls, one piece each, so one
-                    // image per request is what it asks for.
-                    n: 1,
-                    size: sizeFor(req.model, req.aspect),
-                    // No `quality` and no `background`: the stage asks for the provider's default
-                    // quality and style, which is what leaving them off means.
-                }),
-            });
+            const response = req.reference === undefined
+                ? await deps.fetch(`${openAiImagesBase}/images/generations`, {
+                    method: "POST",
+                    signal: req.signal,
+                    headers: {
+                        Authorization: `Bearer ${keyOf(deps)}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        model: req.model,
+                        prompt: req.prompt,
+                        // The stage sends Number as that many independent calls, one piece each, so
+                        // one image per request is what it asks for.
+                        n: 1,
+                        size: sizeFor(req.model, req.aspect),
+                        // No `quality` and no `background`: the stage asks for the provider's default
+                        // quality and style, which is what leaving them off means.
+                    }),
+                })
+                : // With an establishing image the GPT image models take it as an input image on the
+                    // edits endpoint, a multipart form; the note says it is a reference, not the canvas.
+                    await deps.fetch(`${openAiImagesBase}/images/edits`, {
+                        method: "POST",
+                        signal: req.signal,
+                        headers: { Authorization: `Bearer ${keyOf(deps)}` },
+                        body: editForm(req, req.reference),
+                    });
             if (!response.ok) {
                 throw await failure(response);
             }
@@ -79,6 +92,15 @@ export function openAiImage(deps) {
         },
     };
 }
+function editForm(req, reference) {
+    const form = new FormData();
+    form.set("model", req.model);
+    form.set("prompt", withReferenceNote(req.prompt, reference));
+    form.set("n", "1");
+    form.set("size", sizeFor(req.model, req.aspect));
+    form.append("image[]", new Blob([Uint8Array.from(reference.bytes)], { type: reference.mime }), reference.mime === "image/jpeg" ? "reference.jpg" : "reference.png");
+    return form;
+}
 // A GPT image model always answers with base64, so the bytes arrive with the call and
 // there is no link to follow. They are still sniffed: what the port stores is a PNG or a
 // JPEG, and a truncated payload that decodes to something else must not reach the disk.

package/dist/adapters/image/reference.js

@@ -0,0 +1,7 @@
+// What an image API is told about the establishing image sent with a request, ahead of the
+// brief. An edit endpoint otherwise treats its input as the picture to change, so it says the
+// input is a reference for the look and the cast, not the composition to keep.
+export const referenceNote = "The attached image is a visual reference only: keep its characters, rendering style and colour palette, but do not copy its composition, pose or framing. Compose a new image from this brief:";
+export function withReferenceNote(prompt, reference) {
+    return reference === undefined ? prompt : `${referenceNote}\n\n${prompt}`;
+}