@gentbajko/slopify 2.4.0 → 3.0.0

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

@@ -8,13 +8,67 @@ const maxOutputBytes = 32 * 1024 * 1024;
 function unavailable(detail) {
     return providerError({
         kind: "unavailable",
-        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).`,
+        message: `The Codex CLI finished, but Slopify could not collect the image: ${detail}. Use Try again 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,36 @@
-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 { codexLimitError, readingOf } from "../llm/codex.js";
+import { codexPlanLimit } from "../llm/codex-limits.js";
+import { cliEvent, cliShaped, endedKind, 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";
+import { referencePictures } from "./reference.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 +41,64 @@ 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 ||
+        referencePictures(req).length > 0);
+}
+// 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");
+}
+// Every picture the request carries, each at its own path: the establishing image keeps the
+// name it always had, the cast pictures follow it as reference-2, reference-3 and so on.
+export function codexReferencePaths(directory, req) {
+    return referencePictures(req).map((picture, index) => ({
+        picture,
+        path: index === 0
+            ? codexReferencePath(directory, picture.image)
+            : join(directory, `reference-${String(index + 1)}${picture.image.mime === "image/jpeg" ? ".jpg" : ".png"}`),
+    }));
+}
+function castInstructions(req, directory) {
+    const paths = codexReferencePaths(directory, req);
+    return [
+        `Reference images are saved at these paths. Pass all of them in referenced_image_paths on every image generation call: ${paths.map((row) => row.path).join(", ")}.`,
+        ...paths.map((row) => row.picture.member === undefined
+            ? `${row.path} is the establishing image: keep its characters, rendering style and colour palette.`
+            : `${row.path} shows ${row.picture.member}${describeMember(req, row.picture.member)}: draw ${row.picture.member} to look exactly like this.`),
+        "Use them as references only: do not copy their composition, pose or framing; compose this image from the brief.",
+    ].join(" ");
+}
+function describeMember(req, name) {
+    const description = req.cast?.find((member) => member.name === name)?.description.trim() ?? "";
+    return description === "" ? "" : ` (${description})`;
+}
+export function codexImageInstructions(req, reference, directory) {
+    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.",
+        ...(req.cast !== undefined && req.cast.length > 0 && directory !== undefined
+            ? [castInstructions(req, directory)]
+            : 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 +113,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,23 +140,47 @@ 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, directory),
     ];
 }
 const failure = z.object({ error: z.object({ message: z.string() }) });
+const turnUsage = z.object({
+    usage: z
+        .object({
+        input_tokens: z.number(),
+        output_tokens: z.number(),
+        cached_input_tokens: z.number().optional(),
+    })
+        .nullish(),
+});
 const errorEvent = z.object({ message: z.string() });
 const item = z.object({ item: z.object({ type: z.string(), text: z.string().optional() }) });
 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 Try again.",
                 });
             req.signal.throwIfAborted();
             const directory = mkdtempSync(join(tmpdir(), "slopify-codex-image-"));
@@ -98,7 +188,30 @@ export function codexImage(deps) {
             const startedAt = Date.now();
             let threadId;
             let run;
+            let reported = -1;
+            let usage;
+            const before = deps.readLimits?.().catch(() => null);
+            // 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 {
+                for (const { path, picture } of codexReferencePaths(directory, req))
+                    writeFileSync(path, picture.image.bytes, { mode: 0o600 });
+                report();
                 try {
                     run = deps.run(binary, codexImageArgs(req, directory), req.signal, {
                         cwd: directory,
@@ -108,7 +221,7 @@ export function codexImage(deps) {
                 catch {
                     throw providerError({
                         kind: "unsupported",
-                        message: "The Codex CLI could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.",
+                        message: "The Codex CLI could not be started. Check it is installed and set up in Settings → Providers, then use Try again.",
                     });
                 }
                 let completed = false;
@@ -118,21 +231,37 @@ 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({
                                 kind: "unavailable",
-                                message: "The Codex CLI started more than one image job for one image, so Slopify cannot tell which result is right (both may have used your quota). Use Retry stage to make the image again.",
+                                message: "The Codex CLI started more than one image job for one image, so Slopify cannot tell which result is right (both may have used your quota). Use Try again to make the image again.",
                             });
                         threadId = cliShaped(binary, z.object({ thread_id: z.string() }), event.value).thread_id;
                     }
-                    else if (event.type === "turn.completed")
+                    else if (event.type === "turn.completed") {
                         completed = true;
+                        const counted = turnUsage.safeParse(event.value);
+                        if (counted.success && counted.data.usage)
+                            usage = {
+                                inputTokens: counted.data.usage.input_tokens,
+                                outputTokens: counted.data.usage.output_tokens,
+                                ...(counted.data.usage.cached_input_tokens
+                                    ? { cachedInputTokens: counted.data.usage.cached_input_tokens }
+                                    : {}),
+                            };
+                    }
                     else if (event.type === "turn.failed") {
                         const message = cliShaped(binary, failure, event.value).error.message;
                         const login = cliLoginError("codex", message);
                         if (login)
                             throw login;
+                        const planLimit = codexPlanLimit(message, new Date());
+                        if (planLimit !== undefined)
+                            throw codexLimitError(message, planLimit);
                         throw providerError({
                             kind: /refus|content.policy|safety/i.test(message) ? "refusal" : "other",
                             message: /refus|content.policy|safety/i.test(message)
@@ -145,6 +274,9 @@ export function codexImage(deps) {
                         const login = cliLoginError("codex", message);
                         if (login)
                             throw login;
+                        const planLimit = codexPlanLimit(message, new Date());
+                        if (planLimit !== undefined)
+                            throw codexLimitError(message, planLimit);
                         throw providerError({
                             kind: /image.generation|image tool|feature.*unavailable/i.test(message)
                                 ? "unsupported"
@@ -167,12 +299,15 @@ export function codexImage(deps) {
                 if (ended.error !== null)
                     throw providerError({
                         kind: "unsupported",
-                        message: "The Codex CLI could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.",
+                        message: "The Codex CLI could not be started. Check it is installed and set up in Settings → Providers, then use Try again.",
                     });
+                const stderrLimit = codexPlanLimit(run.stderr(), new Date());
+                if ((ended.code !== 0 || !completed) && stderrLimit !== undefined)
+                    throw codexLimitError(run.stderr().trim(), stderrLimit);
                 if (ended.code !== 0 || !completed)
                     throw (cliLoginError("codex", run.stderr()) ??
                         providerError({
-                            kind: unavailable ? "unsupported" : "other",
+                            kind: unavailable ? "unsupported" : endedKind(ended),
                             message: endedWithout(binary, ended, run.stderr()),
                         }));
                 if (unavailable)
@@ -180,7 +315,13 @@ export function codexImage(deps) {
                         kind: "unsupported",
                         message: `The Codex CLI cannot make images. ${cannotDraw}`,
                     });
-                return codexGeneratedImage(env, threadId, startedAt);
+                const image = codexGeneratedImage(env, threadId, startedAt);
+                const limits = await readingOf(before, deps.readLimits);
+                return {
+                    ...image,
+                    ...(usage === undefined ? {} : { usage }),
+                    ...(limits === undefined ? {} : { limits }),
+                };
             }
             catch (error) {
                 req.signal.throwIfAborted();
@@ -205,12 +346,12 @@ async function* bounded(source, maximum) {
         if (size > maximum)
             throw providerError({
                 kind: "other",
-                message: "The Codex CLI sent far more output than an image job should, so Slopify stopped it. Use Retry stage; if it keeps happening, update the Codex CLI to the latest version.",
+                message: "The Codex CLI sent far more output than an image job should, so Slopify stopped it. Use Try again; if it keeps happening, update the Codex CLI to the latest version.",
             });
         yield chunk;
     }
 }
-const imageNext = "Use Retry stage; if it keeps failing, run codex in a terminal to check it works and is signed in, or choose another image provider in the Providers section of Edit project.";
+const imageNext = "Use Try again; if it keeps failing, run codex in a terminal to check it works and is signed in, or choose another image provider in the Providers section of Edit project.";
 const cannotDraw = "Update the Codex CLI and check your ChatGPT plan includes image generation, or choose another image provider in the Providers section of Edit project.";
 function imageEnvironment(directory, source) {
     const env = { PWD: directory };

package/dist/adapters/image/fal.js

@@ -4,6 +4,7 @@ import { providerError } from "../../kernel/ports/model.js";
 import { httpFailure, internalError, missingKey, noImage, providerSaid, unreadable, } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
+import { referencePictures, withReferences } 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, which only the video clips need and which is three
@@ -49,6 +50,16 @@ 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
@@ -89,12 +100,26 @@ 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.
+            // Cast pictures ride the same list; a model without an edit endpoint gets the cast in
+            // words instead, since only the establishing image is something the user turned on.
+            const pictures = referencePictures(req);
+            const edit = pictures.length === 0 ? 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: withReferences(req.prompt, req, edit === undefined ? 0 : pictures.length),
+                    ...(edit === undefined
+                        ? {}
+                        : { image_urls: pictures.map((picture) => dataUri(picture.image)) }),
                     ...aspectOf(req.model, req.aspect),
                     // The stage sends Number as that many independent calls, one piece each.
                     num_images: 1,
@@ -147,7 +172,7 @@ export function falImage(deps) {
                 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."),
+                        message: providerSaid("fal.ai", "could not make the video clip", redact(current.error), "Use Try again; if it keeps happening, choose another image-to-video model under Animate images in Edit project → Inputs → Look."),
                     });
                 if (current.status === "COMPLETED")
                     break;
@@ -203,6 +228,9 @@ function kindOf(status) {
     // ceiling: everything else is `other` and is retried, so a 422 naming an input this model
     // does not take fails the same way four times over. A terminal "this will never work" kind
     // has to reach the port's error contract first, which is not this adapter's to widen.
+    // The provider's own server failed; the same request may well succeed later.
+    if (status >= 500)
+        return "dropped";
     return "other";
 }
 async function failure(response, subject = "image request") {

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 { referencePictures, withReferences } 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: referencePictures(req).length === 0
+                        ? req.prompt
+                        : [
+                            ...referencePictures(req).map(({ image }) => ({
+                                type: "image",
+                                mime_type: image.mime,
+                                data: Buffer.from(image.bytes).toString("base64"),
+                            })),
+                            { type: "text", text: withReferences(req.prompt, req) },
+                        ],
                     // 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.
@@ -105,7 +117,7 @@ function decode(part) {
         const claimed = part.mime_type ?? "nothing";
         throw providerError({
             kind: "other",
-            message: `Google sent back something that is not a PNG or JPEG image (labelled ${claimed}, but ${describeBytes(bytes)}). Use Retry stage; if it keeps happening, choose another image model in the Providers section of Edit project.`,
+            message: `Google sent back something that is not a PNG or JPEG image (labelled ${claimed}, but ${describeBytes(bytes)}). Use Try again; if it keeps happening, choose another image model in the Providers section of Edit project.`,
         });
     }
     return { bytes, mime };
@@ -143,6 +155,9 @@ function kindOf(status, named, message) {
     // ceiling: everything else is `other` and is retried, so a prompt past the model's limit
     // fails the same way four times over. A terminal "this will never work" kind has to reach
     // the port's error contract first, which is not this adapter's to widen.
+    // The provider's own server failed; the same request may well succeed later.
+    if (status >= 500)
+        return "dropped";
     return "other";
 }
 async function failure(response) {

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 { referencePictures, withReferences } 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,34 @@ 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 pictures = referencePictures(req);
+            const response = pictures.length === 0
+                ? 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, pictures),
+                    });
             if (!response.ok) {
                 throw await failure(response);
             }
@@ -79,6 +93,18 @@ export function openAiImage(deps) {
         },
     };
 }
+// The edits endpoint takes several input images as repeated `image[]` parts: the establishing
+// image first, then the cast pictures.
+function editForm(req, pictures) {
+    const form = new FormData();
+    form.set("model", req.model);
+    form.set("prompt", withReferences(req.prompt, req));
+    form.set("n", "1");
+    form.set("size", sizeFor(req.model, req.aspect));
+    for (const [index, { image }] of pictures.entries())
+        form.append("image[]", new Blob([Uint8Array.from(image.bytes)], { type: image.mime }), `${index === 0 ? "reference" : `reference-${String(index + 1)}`}${image.mime === "image/jpeg" ? ".jpg" : ".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.
@@ -88,7 +114,7 @@ function decode(b64) {
     if (mime === undefined) {
         throw providerError({
             kind: "other",
-            message: `OpenAI sent back something that is not a PNG or JPEG image (${describeBytes(bytes)}). Use Retry stage; if it keeps happening, choose another image model in the Providers section of Edit project.`,
+            message: `OpenAI sent back something that is not a PNG or JPEG image (${describeBytes(bytes)}). Use Try again; if it keeps happening, choose another image model in the Providers section of Edit project.`,
         });
     }
     return { bytes, mime };
@@ -115,6 +141,9 @@ function kindOf(status, code) {
     // ceiling: everything else is `other` and is retried, so a prompt past the model's length
     // limit fails the same way four times over. A terminal "this will never work" kind has to
     // reach the port's error contract first, which is not this adapter's to widen.
+    // The provider's own server failed; the same request may well succeed later.
+    if (status >= 500)
+        return "dropped";
     return "other";
 }
 async function failure(response) {