@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/images/engines/a1111.js

@@ -0,0 +1,219 @@
+// AUTOMATIC1111-compatible adapter — POST /sdapi/v1/txt2img, synchronous.
+//
+// The most widely spoken text-to-image dialect there is: A1111 itself, Forge,
+// SD.Next, Draw Things on macOS, and the stable-diffusion.cpp server all
+// answer on it. One adapter therefore covers "the homelab box" and "a local
+// Mac server" with nothing different but a base_url.
+//
+// Synchronous: the request stays open for the whole generation and the reply
+// carries the images as base64. That is why it has no progress callback — the
+// server sends nothing until it is done. For a long queue prefer the sdcpp
+// adapter, which polls instead of holding a socket open.
+//
+// Shape of the reply (verified against stable-diffusion.cpp's shim):
+//   { images: ["<base64 png>", …], info: "<json string>", parameters: {…} }
+// `info` is a JSON *string* (not an object) and carries the resolved seed —
+// the only way to learn which seed a `seed: -1` request actually used.
+//
+// ── img2img ────────────────────────────────────────────────────────────────
+// An `init_image` switches the route to POST /sdapi/v1/img2img, where the
+// picture is the starting canvas rather than a structural hint: the reply keeps
+// the same envelope, so only the URL and two fields differ. `denoising_strength`
+// is how far the sampler is allowed to walk away from it — ~0.3 retouches,
+// ~0.45 is the useful middle, >0.6 reinvents the scene. Verified against
+// stable-diffusion.cpp at 512x768.
+//
+// ── Inpainting ─────────────────────────────────────────────────────────────
+// A `mask` alongside the init image confines the repaint to the white areas
+// and leaves the black ones byte-identical, which is the only way to change one
+// thing in a picture and keep the rest of the scene. Verified against
+// stable-diffusion.cpp's shim.
+//
+// `inpainting_fill` decides what the masked region starts from, and it is the
+// setting that decides whether the prompt lands at all:
+//   1 "original" (default) keeps the existing pixels — a gentle edit, but on a
+//     turbo checkpoint at cfg 1.0 the old content can outvote the prompt
+//     entirely and nothing visibly changes;
+//   2 "latent noise" throws them away, which is what a prompt that has to
+//     override the region needs.
+// Measured on Z-Image Turbo: fill 1 at denoise 0.75 left a green body green;
+// fill 2 at denoise 1.0 turned it red with the rest of the frame untouched.
+//
+// Structural conditioning (ControlNet) is NOT here: that server takes a
+// `control_image` on its own native route, so it lives in the sdcpp adapter.
+
+import { postJson, probeUrl, joinUrl, writeImage, decodeBase64Image, toRawBase64, imageSize } from "./shared.js";
+
+const DEFAULT_TIMEOUT_S = 600;
+
+function headersFor(config) {
+  const h = {};
+  if (config.api_key) h.authorization = `Bearer ${config.api_key}`;
+  return h;
+}
+
+/**
+ * Is `asked` the checkpoint the server says it `rendered` with? Compared
+ * loosely on purpose: a server reports "z_image_turbo-Q4_K.gguf" for what a
+ * person types as "z_image_turbo-Q4_K", and a strict compare would cry wolf on
+ * every correct request.
+ */
+function sameCheckpoint(asked, rendered) {
+  if (!asked || !rendered) return false;
+  const norm = (v) => String(v).toLowerCase().replace(/\.(gguf|safetensors|ckpt|pt)$/, "").trim();
+  const a = norm(asked);
+  const r = norm(rendered);
+  return a === r || r.includes(a) || a.includes(r);
+}
+
+/** The resolved seed hides inside a JSON string; a malformed one is not fatal. */
+function parseInfo(info) {
+  if (!info) return null;
+  if (typeof info === "object") return info;
+  try { return JSON.parse(info); } catch { return null; }
+}
+
+export default {
+  id: "a1111",
+
+  // Everything in the family contract except `format`: the A1111 API has no
+  // output-format field — the server decides (PNG in practice) and we sniff
+  // the real container from the bytes rather than trusting a request that was
+  // never sent.
+  //
+  // `model` is listed, but it is the one entry this adapter cannot promise
+  // STATICALLY. Real A1111 and Forge switch checkpoints through
+  // override_settings; a single-checkpoint clone accepts the field, answers
+  // 200, and renders with whatever it loaded at launch — measured against
+  // stable-diffusion.cpp, which happily took a checkpoint name that does not
+  // exist. So the promise is verified per RESPONSE instead: `info` names the
+  // model that actually rendered, and generate() reports `model` as unhonored
+  // when that is not the one asked for. Declaring it here is right for the
+  // dialect; the per-response check is what keeps it honest per server.
+  supports: [
+    "negative_prompt", "width", "height", "steps", "cfg_scale",
+    "seed", "sampler", "scheduler", "count", "model",
+    "init_image", "denoising_strength",
+    "mask", "mask_blur", "inpainting_fill", "inpaint_full_res",
+  ],
+
+  async isAvailable(config = {}) {
+    if (!config.base_url) return false;
+    // /sdapi/v1/options is the cheapest route every A1111 clone implements.
+    // A server that answers 404 there but serves txt2img still counts as
+    // reachable, so fall back to the root document before giving up.
+    return (
+      (await probeUrl(joinUrl(config.base_url, "/sdapi/v1/options"))) ||
+      (await probeUrl(joinUrl(config.base_url, "/")))
+    );
+  },
+
+  async generate({
+    prompt, negative_prompt, width, height, steps, cfg_scale, seed,
+    sampler, scheduler, count, model, format, outDir, config = {}, signal,
+    init_image, denoising_strength,
+    mask, mask_blur, inpainting_fill, inpaint_full_res,
+  }) {
+    if (!config.base_url) throw new Error("a1111: base_url required");
+
+    // A mask with nothing to mask is a request that would render a plain
+    // txt2img and look like the mask was ignored. Refuse instead.
+    if (mask && !init_image) {
+      throw new Error("a1111: mask needs an init image — inpainting repaints part of a picture");
+    }
+    const img2img = !!init_image;
+    const body = { prompt };
+    if (negative_prompt) body.negative_prompt = negative_prompt;
+    if (width) body.width = width;
+    if (height) body.height = height;
+    if (steps) body.steps = steps;
+    if (cfg_scale != null) body.cfg_scale = cfg_scale;
+    if (seed != null) body.seed = seed;
+    if (sampler) body.sampler_name = sampler;
+    if (scheduler) body.scheduler = scheduler;
+    if (count && count > 1) { body.n_iter = count; body.batch_size = 1; }
+    // A1111 switches checkpoints through override_settings, not a top-level
+    // field. Servers that host a single model (sd.cpp) ignore it harmlessly.
+    if (model) body.override_settings = { sd_model_checkpoint: model };
+
+    // img2img carries the canvas plus how far the sampler may stray from it.
+    // The field is `init_images` (plural, an array) even for a single picture —
+    // an `init_image` singular is silently ignored and you get plain txt2img.
+    if (img2img) {
+      body.init_images = [toRawBase64(init_image)];
+      body.denoising_strength = denoising_strength != null ? denoising_strength : 0.45;
+    }
+
+    if (mask) {
+      const initBuf = decodeBase64Image(init_image);
+      const maskBuf = decodeBase64Image(mask);
+      const a = imageSize(initBuf);
+      const b = imageSize(maskBuf);
+      // Servers accept a mismatched mask without complaint and then inpaint the
+      // wrong region (or nothing), so catch it here where the fix is sayable.
+      if (a && b && (a.width !== b.width || a.height !== b.height)) {
+        throw new Error(
+          `a1111: mask is ${b.width}x${b.height} but the init image is ${a.width}x${a.height} — ` +
+          "they must match exactly; resize the mask first"
+        );
+      }
+      body.mask = toRawBase64(mask);
+      if (mask_blur != null) body.mask_blur = mask_blur;
+      body.inpainting_fill = inpainting_fill != null ? inpainting_fill : 1;
+      body.inpaint_full_res = inpaint_full_res != null ? inpaint_full_res : false;
+    }
+
+    const timeoutMs = (Number(config.timeout_s) || DEFAULT_TIMEOUT_S) * 1000;
+    const reply = await postJson(
+      joinUrl(config.base_url, img2img ? "/sdapi/v1/img2img" : "/sdapi/v1/txt2img"),
+      body,
+      { headers: headersFor(config), signal, timeoutMs }
+    );
+
+    const b64s = Array.isArray(reply?.images) ? reply.images : [];
+    if (!b64s.length) throw new Error("a1111: server returned no images");
+
+    const info = parseInfo(reply?.info);
+    const seeds = Array.isArray(info?.all_seeds) ? info.all_seeds : [];
+    const rendered = info?.sd_model_name || null;
+
+    return {
+      images: b64s.map((b64, i) =>
+        ({ ...writeImage(decodeBase64Image(b64), { outDir, provider: "a1111", format, index: i }),
+           seed: seeds[i] ?? info?.seed ?? (seed >= 0 ? seed : null) })),
+      // Report the model that RENDERED, never the one that was asked for — a
+      // server that ignored the request must not have its silence read as
+      // agreement.
+      model: rendered || (sameCheckpoint(model, rendered) ? model : null) || null,
+      unhonored: model && rendered && !sameCheckpoint(model, rendered) ? ["model"] : [],
+      meta: {
+        mode: mask ? "inpaint" : img2img ? "img2img" : "txt2img",
+        sampler: info?.sampler_name || sampler || null,
+        steps: info?.steps ?? steps ?? null,
+        cfg_scale: info?.cfg_scale ?? cfg_scale ?? null,
+        ...(img2img ? { denoising_strength: body.denoising_strength } : {}),
+        ...(mask ? { inpainting_fill: body.inpainting_fill, mask_blur: body.mask_blur ?? null } : {}),
+      },
+    };
+  },
+
+  /** Live catalog for the settings UI: which checkpoints and samplers exist. */
+  async capabilities(config = {}) {
+    if (!config.base_url) return null;
+    const out = {};
+    const pull = async (route, shape) => {
+      try {
+        const res = await fetch(joinUrl(config.base_url, route), { headers: headersFor(config) });
+        if (!res.ok) return;
+        Object.assign(out, shape(await res.json()));
+      } catch { /* a missing sub-route is normal on minimal clones */ }
+    };
+    await pull("/sdapi/v1/sd-models", (j) =>
+      ({ models: (j || []).map((m) => m.model_name || m.title).filter(Boolean) }));
+    await pull("/sdapi/v1/samplers", (j) =>
+      ({ samplers: (j || []).map((s) => s.name).filter(Boolean) }));
+    await pull("/sdapi/v1/schedulers", (j) =>
+      ({ schedulers: (j || []).map((s) => s.name || s.label).filter(Boolean) }));
+    return Object.keys(out).length ? out : null;
+  },
+};

package/src/core/images/engines/index.js

@@ -0,0 +1,187 @@
+// Image-engine registry. Same shape as the TTS registry at core/voice/engines/
+// and the LLM one at core/engines/ — one directory of uniform adapters plus an
+// id→adapter map, so adding a provider touches its own file and one line here.
+//
+// Two selection modes (config.images.mode):
+//   "chain"  — ordered fallback router. Walk config.images.order (falling back
+//              to AUTO_PREFERENCE), skip engines turned off
+//              (config.images.<id>.enabled === false), and take the first whose
+//              isAvailable() says yes. "mock" is always kept as the final rung.
+//   "single" — use exactly config.images.provider, no fallback.
+//
+// An explicit `provider` argument always wins (the settings tester and
+// `apx image --provider` both rely on that).
+//
+// ── Custom providers ───────────────────────────────────────────────────────
+// Any number of extra endpoints live under images.custom.<slug> and surface as
+// "custom:<slug>". Unlike TTS — where every custom endpoint is OpenAI-shaped —
+// an image server can speak any of the three dialects, so a custom entry
+// carries a `kind` ("a1111" | "sdcpp" | "openai", default "a1111") naming which
+// adapter drives it. Getting that wrong is a 404, not a subtle degradation,
+// which is why it is explicit rather than sniffed.
+
+import a1111 from "./a1111.js";
+import sdcpp from "./sdcpp.js";
+import openai from "./openai.js";
+import mock from "./mock.js";
+
+const ADAPTERS = { a1111, sdcpp, openai, mock };
+export const IMAGE_ENGINE_IDS = Object.keys(ADAPTERS);
+
+/**
+ * Local-first, and A1111 ahead of the native sdcpp route on purpose: the same
+ * stable-diffusion.cpp server answers both, but only the A1111 dialect carries
+ * steps and cfg scale, and a turbo checkpoint left on a server's stock 20
+ * steps / cfg 7 renders several times slower for a worse picture.
+ */
+export const AUTO_PREFERENCE = ["a1111", "sdcpp", "openai", "mock"];
+
+/** Dialects a custom endpoint may declare. */
+export const CUSTOM_KINDS = ["a1111", "sdcpp", "openai"];
+export const CUSTOM_PREFIX = "custom:";
+
+export function isCustomId(id) {
+  return typeof id === "string" && id.startsWith(CUSTOM_PREFIX);
+}
+function slugOf(id) {
+  return isCustomId(id) ? id.slice(CUSTOM_PREFIX.length) : id;
+}
+function customEngineIds(imgCfg) {
+  return Object.keys(imgCfg?.custom || {}).map((slug) => CUSTOM_PREFIX + slug);
+}
+function knownIds(imgCfg) {
+  return [...IMAGE_ENGINE_IDS, ...customEngineIds(imgCfg)];
+}
+
+export function imagesConfig(globalConfig) {
+  return globalConfig?.images || {};
+}
+
+export function providerConfig(globalConfig, provider) {
+  const img = imagesConfig(globalConfig);
+  if (isCustomId(provider)) return img?.custom?.[slugOf(provider)] || {};
+  return img?.[provider] || {};
+}
+
+/** Which adapter drives an engine id (a custom one names its dialect). */
+export function getImageAdapter(provider, globalConfig) {
+  if (isCustomId(provider)) {
+    const kind = providerConfig(globalConfig, provider).kind || "a1111";
+    const adapter = ADAPTERS[kind];
+    if (!adapter) {
+      throw new Error(`unknown kind "${kind}" for ${provider}. Known: ${CUSTOM_KINDS.join(", ")}`);
+    }
+    return adapter;
+  }
+  const adapter = ADAPTERS[provider];
+  if (!adapter) {
+    throw new Error(`unknown image provider "${provider}". Known: ${IMAGE_ENGINE_IDS.join(", ")}`);
+  }
+  return adapter;
+}
+
+function isEnabled(imgCfg, id) {
+  if (isCustomId(id)) return imgCfg?.custom?.[slugOf(id)]?.enabled !== false;
+  return imgCfg?.[id]?.enabled !== false;
+}
+
+/** Effective routing mode for the chain/single decision. */
+export function resolveMode(imgCfg) {
+  if (imgCfg?.mode === "chain" || imgCfg?.mode === "single") return imgCfg.mode;
+  const p = imgCfg?.provider;
+  return p && p !== "auto" ? "single" : "chain";
+}
+
+/**
+ * Full engine order for chain mode: the user's order first (known ids only),
+ * then whatever AUTO_PREFERENCE and the custom entries add. Disabled engines
+ * stay in the list so the settings UI can render and reorder every row;
+ * filtering happens at selection time.
+ */
+export function resolveChainOrder(imgCfg) {
+  const known = knownIds(imgCfg);
+  const ordered = Array.isArray(imgCfg?.order) ? imgCfg.order.filter((id) => known.includes(id)) : [];
+  const rest = [...AUTO_PREFERENCE, ...customEngineIds(imgCfg)].filter((id) => !ordered.includes(id));
+  const full = [...ordered, ...rest];
+  if (!full.includes("mock")) full.push("mock");
+  return full;
+}
+
+/**
+ * Resolve which engine handles a generate() call.
+ * Returns { provider, adapter, engineConfig }.
+ */
+export async function selectImageEngine({ globalConfig, provider }) {
+  const imgCfg = imagesConfig(globalConfig);
+
+  // 1. Explicit override (CLI --provider, the settings tester) always wins.
+  if (provider && provider !== "auto") {
+    return {
+      provider,
+      adapter: getImageAdapter(provider, globalConfig),
+      engineConfig: providerConfig(globalConfig, provider),
+    };
+  }
+
+  // 2. Single mode: the configured engine verbatim, no fallback.
+  if (resolveMode(imgCfg) === "single") {
+    const id = imgCfg?.provider;
+    if (id && id !== "auto") {
+      return {
+        provider: id,
+        adapter: getImageAdapter(id, globalConfig),
+        engineConfig: providerConfig(globalConfig, id),
+      };
+    }
+    // Misconfigured single mode (no concrete provider) falls through to chain.
+  }
+
+  // 3. Chain mode: probe the enabled order, first available wins.
+  for (const id of resolveChainOrder(imgCfg)) {
+    if (id !== "mock" && !isEnabled(imgCfg, id)) continue;
+    let adapter;
+    try { adapter = getImageAdapter(id, globalConfig); } catch { continue; }
+    const cfg = providerConfig(globalConfig, id);
+    try {
+      if (await adapter.isAvailable(cfg, globalConfig?.engines)) {
+        return { provider: id, adapter, engineConfig: cfg };
+      }
+    } catch { /* probe failures fall through to the next engine */ }
+  }
+
+  return { provider: "mock", adapter: mock, engineConfig: providerConfig(globalConfig, "mock") };
+}
+
+/**
+ * Which engines are configured/available right now. Every entry is probed, so
+ * this makes real (short-timeout) network calls — fine for a settings screen,
+ * not for a hot path.
+ */
+export async function listAvailableImageEngines(globalConfig) {
+  const imgCfg = imagesConfig(globalConfig);
+  const out = [];
+  for (const id of knownIds(imgCfg)) {
+    const cfg = providerConfig(globalConfig, id);
+    let adapter = null;
+    try { adapter = getImageAdapter(id, globalConfig); } catch { /* unknown kind */ }
+    let available = false;
+    try {
+      available = adapter ? await adapter.isAvailable(cfg, globalConfig?.engines) : false;
+    } catch { available = false; }
+    const custom = isCustomId(id);
+    out.push({
+      id,
+      available,
+      // `enabled`, `label` and `kind` are routing/display metadata, not config —
+      // excluding them keeps "configured" from turning true the moment someone
+      // toggles a row off.
+      configured: Object.keys(cfg).filter((k) => !["enabled", "label", "kind"].includes(k)).length > 0,
+      enabled: isEnabled(imgCfg, id),
+      supports: adapter?.supports || [],
+      ...(custom
+        ? { custom: true, kind: cfg.kind || "a1111", label: cfg.label || slugOf(id), note: cfg.base_url || "" }
+        : { note: cfg.base_url || "" }),
+    });
+  }
+  return out;
+}

package/src/core/images/engines/mock.js

@@ -0,0 +1,74 @@
+// Deterministic offline engine. Always available, always last in the chain.
+//
+// It exists for the same reason the TTS mock does: tests run with no network
+// and no keys (project rule 1), and a caller that asks for a picture when
+// nothing is configured should get a real file back rather than an exception
+// from four different servers in a row. The PNG is a solid colour derived from
+// the prompt, so the same prompt always yields the same swatch — a useful
+// property when a test wants to assert "the pipeline wrote the bytes it was
+// given" without shipping a fixture.
+
+import { createHash } from "node:crypto";
+import { deflateSync } from "node:zlib";
+import { writeImage } from "./shared.js";
+
+const SIZE = 64;
+
+function crc32(buf) {
+  let c = ~0;
+  for (const byte of buf) {
+    c ^= byte;
+    for (let k = 0; k < 8; k++) c = (c >>> 1) ^ (0xedb88320 & -(c & 1));
+  }
+  return (~c) >>> 0;
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+}
+
+/** Minimal hand-rolled PNG encoder — no image dependency for a test fixture. */
+function solidPng(r, g, b) {
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(SIZE, 0);
+  ihdr.writeUInt32BE(SIZE, 4);
+  ihdr[8] = 8;   // bit depth
+  ihdr[9] = 2;   // colour type: truecolour
+  const row = Buffer.concat([Buffer.from([0]), Buffer.concat(Array(SIZE).fill(Buffer.from([r, g, b])))]);
+  const raw = Buffer.concat(Array(SIZE).fill(row));
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw)),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+export default {
+  id: "mock",
+
+  // `count` is the one option it genuinely honors — it really does write N
+  // files. Everything else is accepted and ignored, and saying so is what
+  // keeps the "ignored options" report honest.
+  supports: ["count"],
+
+  async isAvailable() { return true; },
+
+  async generate({ prompt, count, outDir }) {
+    const digest = createHash("sha256").update(String(prompt || "")).digest();
+    const n = Math.max(1, Math.min(Number(count) || 1, 4));
+    return {
+      images: Array.from({ length: n }, (_, i) =>
+        ({ ...writeImage(solidPng(digest[i * 3], digest[i * 3 + 1], digest[i * 3 + 2]),
+                         { outDir, provider: "mock", format: "png", index: i }),
+           seed: digest.readUInt32BE(0) })),
+      model: "mock",
+      meta: { note: "generated offline by the mock engine" },
+    };
+  },
+};

package/src/core/images/engines/openai.js

@@ -0,0 +1,130 @@
+// OpenAI Images adapter — POST /v1/images/generations.
+//
+// Two lives, same code path, distinguished by whether base_url is set:
+//   • stock OpenAI (gpt-image-1 / dall-e-3), keyed from engines.openai.api_key
+//   • any OpenAI-compatible server, including the stable-diffusion.cpp box,
+//     LocalAI, vLLM-style shims and a hosted gateway.
+//
+// The compatibility that makes this dialect universal is also its ceiling: the
+// schema has no steps, no cfg scale, no sampler and no negative prompt. Against
+// a local diffusion server that means the server's own defaults decide, and
+// `z_image_turbo` at its stock 20 steps / cfg 7 took ~4× longer than the same
+// picture through the A1111 route at 8 steps / cfg 1. Those knobs are declared
+// unsupported here rather than silently dropped, and the facade reports them
+// back so a caller can see why its `--steps` did nothing.
+//
+// As with TTS, a custom endpoint uses ONLY its own key: never leak the stock
+// OpenAI key (or OPENAI_API_KEY) to somebody else's server.
+
+import { postJson, getJson, probeUrl, joinUrl, writeImage, decodeBase64Image, formatSize } from "./shared.js";
+
+const DEFAULT_URL = "https://api.openai.com/v1";
+const DEFAULT_MODEL = "gpt-image-1";
+const DEFAULT_TIMEOUT_S = 600;
+
+function getKey(config, parentEnginesCfg) {
+  if (config.base_url) return config.api_key || "";
+  return config.api_key || parentEnginesCfg?.openai?.api_key || process.env.OPENAI_API_KEY || "";
+}
+
+function baseFor(config) {
+  return config.base_url || DEFAULT_URL;
+}
+
+function headersFor(config, parentEnginesCfg) {
+  const h = {};
+  const key = getKey(config, parentEnginesCfg);
+  if (key) h.authorization = `Bearer ${key}`;
+  return h;
+}
+
+export default {
+  id: "openai",
+
+  // No steps / cfg_scale / sampler / scheduler / negative_prompt / seed: the
+  // API has nowhere to put them.
+  supports: ["width", "height", "count", "model", "format"],
+
+  async isAvailable(config = {}, parentEnginesCfg) {
+    if (config.base_url) {
+      return probeUrl(joinUrl(config.base_url, "/v1/models"), {
+        headers: headersFor(config, parentEnginesCfg),
+      });
+    }
+    return Boolean(getKey(config, parentEnginesCfg));
+  },
+
+  async generate({
+    prompt, width, height, count, model, format,
+    outDir, config = {}, parentEnginesCfg, signal,
+  }) {
+    const isCustom = Boolean(config.base_url);
+    const key = getKey(config, parentEnginesCfg);
+    if (!isCustom && !key) {
+      throw new Error("openai-images: no api_key (set engines.openai.api_key or OPENAI_API_KEY)");
+    }
+
+    const body = { prompt };
+    const chosenModel = model || config.model || (isCustom ? undefined : DEFAULT_MODEL);
+    if (chosenModel) body.model = chosenModel;
+    if (count && count > 1) body.n = count;
+    if (width && height) body.size = formatSize(width, height);
+    else if (config.size) body.size = config.size;
+    // gpt-image-1 always answers in base64; dall-e-3 answers with a URL unless
+    // asked otherwise, and a URL would leave nothing on disk.
+    if (!isCustom) body.response_format = "b64_json";
+    if (!isCustom && config.quality) body.quality = config.quality;
+    if (isCustom && format) body.output_format = format;
+
+    const timeoutMs = (Number(config.timeout_s) || DEFAULT_TIMEOUT_S) * 1000;
+    const reply = await postJson(
+      joinUrl(baseFor(config), "/v1/images/generations"),
+      body,
+      { headers: headersFor(config, parentEnginesCfg), signal, timeoutMs }
+    );
+
+    const entries = Array.isArray(reply?.data) ? reply.data : [];
+    if (!entries.length) throw new Error("openai-images: server returned no images");
+
+    const images = [];
+    for (const [i, entry] of entries.entries()) {
+      let buf;
+      if (entry?.b64_json) {
+        buf = decodeBase64Image(entry.b64_json);
+      } else if (entry?.url) {
+        // dall-e-3's default. Fetch it now: those URLs expire within the hour.
+        const res = await fetch(entry.url, { signal });
+        if (!res.ok) throw new Error(`openai-images: could not fetch ${res.status} from the image URL`);
+        buf = Buffer.from(await res.arrayBuffer());
+      } else {
+        throw new Error("openai-images: reply entry carried neither b64_json nor url");
+      }
+      images.push(writeImage(buf, {
+        outDir,
+        provider: "openai",
+        format: reply?.output_format || format,
+        index: i,
+      }));
+    }
+
+    return { images, model: chosenModel || null, meta: {} };
+  },
+
+  async capabilities(config = {}, parentEnginesCfg) {
+    if (!config.base_url) {
+      // Stock OpenAI: a fixed, small catalog. Listing /v1/models would return
+      // every chat model too, which is noise in an image picker.
+      return { models: ["gpt-image-1", "dall-e-3", "dall-e-2"], sizes: ["1024x1024", "1024x1536", "1536x1024"] };
+    }
+    try {
+      const j = await getJson(joinUrl(config.base_url, "/v1/models"), {
+        headers: headersFor(config, parentEnginesCfg),
+        timeoutMs: 8000,
+      });
+      const models = (j?.data || []).map((m) => m.id).filter(Boolean);
+      return models.length ? { models } : null;
+    } catch {
+      return null;
+    }
+  },
+};