@agentprojectcontext/apx 1.81.0 → 1.89.1

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

@@ -0,0 +1,204 @@
+// stable-diffusion.cpp native adapter — asynchronous job + polling.
+//
+//   POST /sdcpp/v1/img_gen        → { id, poll_url, status: "queued" }
+//   GET  /sdcpp/v1/jobs/<id>      → { status, queue_position, result, error }
+//   POST /sdcpp/v1/jobs/<id>/cancel
+//   GET  /sdcpp/v1/capabilities   → model, samplers, schedulers, defaults, limits
+//
+// Statuses seen from the server: queued → generating → completed (or failed,
+// with `error` set). The finished job carries
+//   result: { images: [{ b64_json }], output_format: "png" }
+//
+// This is the adapter to prefer for anything unattended. The A1111 route holds
+// one socket open for the whole render, so a queued job behind someone else's
+// batch looks like a hung request; here the socket closes immediately and the
+// caller polls, which also means we can report queue position while waiting.
+//
+// One model per server: stable-diffusion.cpp loads a checkpoint at launch, so
+// there is no field to switch it and `model` is declared unsupported rather
+// than quietly ignored.
+//
+// ── ControlNet ─────────────────────────────────────────────────────────────
+// A `control_image` conditions the render on the structure of a picture —
+// pose, composition, edges — while the prompt still decides everything else.
+// It rides on this native route (the A1111 shim has no field for it), needs a
+// server launched with a ControlNet model loaded, and `control_strength`
+// (0..1, default 0.8) sets how hard the structure is enforced.
+//
+// This is NOT img2img: the control image is never the canvas, so the output
+// does not start from those pixels. To *edit* a picture use the a1111
+// adapter's `init_image` instead.
+//
+// The finished job's envelope is the trap here — `result.images[0].b64_json`.
+// It is not a list of strings the way the A1111 route answers, and it is not
+// `.b64` or `.data`; imagesFrom() below is what absorbs that difference.
+
+import { postJson, getJson, probeUrl, joinUrl, trimBase, writeImage, decodeBase64Image, toRawBase64 } from "./shared.js";
+
+const DEFAULT_POLL_MS = 1200;
+const DEFAULT_TIMEOUT_S = 900;
+const TERMINAL_OK = new Set(["completed", "succeeded", "success", "done"]);
+const TERMINAL_BAD = new Set(["failed", "error", "cancelled", "canceled"]);
+
+function headersFor(config) {
+  const h = {};
+  if (config.api_key) h.authorization = `Bearer ${config.api_key}`;
+  return h;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * The server hands back a relative poll_url ("/sdcpp/v1/jobs/<id>"). Honor it
+ * rather than rebuilding the path: a server behind a sub-path proxy tells us
+ * where it really lives, and reconstructing would send us to a 404.
+ */
+function pollUrlFor(config, submitted) {
+  const rel = submitted?.poll_url;
+  if (typeof rel === "string" && rel.startsWith("/")) return trimBase(config.base_url) + rel;
+  if (typeof rel === "string" && /^https?:/i.test(rel)) return rel;
+  return joinUrl(config.base_url, `/sdcpp/v1/jobs/${submitted?.id}`);
+}
+
+/** Pull the base64 images out of whichever envelope the build uses. */
+function imagesFrom(result) {
+  if (!result) return [];
+  const list = result.images || result.data || [];
+  return list
+    .map((item) => (typeof item === "string" ? item : item?.b64_json || item?.b64 || item?.image))
+    .filter(Boolean);
+}
+
+export default {
+  id: "sdcpp",
+
+  // `model` is absent on purpose — see the header.
+  supports: [
+    "negative_prompt", "width", "height", "steps", "cfg_scale",
+    "seed", "sampler", "scheduler", "count", "format",
+    "control_image", "control_strength",
+  ],
+
+  async isAvailable(config = {}) {
+    if (!config.base_url) return false;
+    return probeUrl(joinUrl(config.base_url, "/sdcpp/v1/capabilities"), {
+      headers: headersFor(config),
+    });
+  },
+
+  async generate({
+    prompt, negative_prompt, width, height, steps, cfg_scale, seed,
+    sampler, scheduler, count, format, outDir, config = {}, signal, onProgress,
+    control_image, control_strength,
+  }) {
+    if (!config.base_url) throw new Error("sdcpp: base_url required");
+
+    const sample_params = {};
+    if (steps) sample_params.sample_steps = steps;
+    if (sampler) sample_params.sample_method = sampler;
+    if (scheduler) sample_params.scheduler = scheduler;
+    if (cfg_scale != null) sample_params.guidance = { txt_cfg: cfg_scale };
+
+    const body = { prompt };
+    if (negative_prompt) body.negative_prompt = negative_prompt;
+    if (width) body.width = width;
+    if (height) body.height = height;
+    if (count) body.batch_count = count;
+    if (seed != null) body.seed = seed;
+    if (format) body.output_format = format;
+    // Bare base64: this server decodes the "data:…;base64," prefix as pixels
+    // and fails inside the sampler without naming the field.
+    if (control_image) {
+      body.control_image = toRawBase64(control_image);
+      body.control_strength = control_strength != null ? control_strength : 0.8;
+    }
+    if (Object.keys(sample_params).length) body.sample_params = sample_params;
+
+    const submitted = await postJson(
+      joinUrl(config.base_url, "/sdcpp/v1/img_gen"),
+      body,
+      { headers: headersFor(config), signal, timeoutMs: 60_000 }
+    );
+    if (!submitted?.id) throw new Error("sdcpp: server did not return a job id");
+
+    const pollUrl = pollUrlFor(config, submitted);
+    const intervalMs = Number(config.poll_interval_ms) || DEFAULT_POLL_MS;
+    const deadline = Date.now() + (Number(config.timeout_s) || DEFAULT_TIMEOUT_S) * 1000;
+
+    let job = submitted;
+    while (true) {
+      if (signal?.aborted) {
+        // Best-effort: tell the server to stop burning GPU on a job nobody
+        // is waiting for any more. Failure here is not worth surfacing.
+        fetch(`${pollUrl}/cancel`, { method: "POST", headers: headersFor(config) }).catch(() => {});
+        throw new Error("sdcpp: cancelled");
+      }
+      if (Date.now() > deadline) {
+        fetch(`${pollUrl}/cancel`, { method: "POST", headers: headersFor(config) }).catch(() => {});
+        throw new Error(`sdcpp: job ${submitted.id} timed out`);
+      }
+      await sleep(intervalMs);
+
+      try {
+        job = await getJson(pollUrl, { headers: headersFor(config), timeoutMs: 30_000 });
+      } catch (e) {
+        // A restarting server drops its job table and answers "job not found".
+        // Say so plainly — the generic 4xx text sends people hunting for a bug
+        // in the request instead of looking at the box.
+        if (/not found/i.test(e.message)) {
+          throw new Error(`sdcpp: job ${submitted.id} disappeared (the server restarted mid-render)`);
+        }
+        throw e;
+      }
+
+      const status = String(job?.status || "").toLowerCase();
+      if (onProgress) onProgress({ status, queue_position: job?.queue_position ?? null });
+      if (TERMINAL_BAD.has(status)) {
+        throw new Error(`sdcpp: job ${status}${job?.error ? ` — ${job.error}` : ""}`);
+      }
+      if (TERMINAL_OK.has(status)) break;
+    }
+
+    const b64s = imagesFrom(job?.result);
+    if (!b64s.length) throw new Error("sdcpp: job completed with no images");
+    const outFormat = job?.result?.output_format || format;
+
+    return {
+      images: b64s.map((b64, i) =>
+        ({ ...writeImage(decodeBase64Image(b64), { outDir, provider: "sdcpp", format: outFormat, index: i }),
+           seed: seed >= 0 ? seed : null })),
+      model: null, // filled in by the facade from capabilities() when known
+      meta: {
+        job_id: submitted.id,
+        elapsed_s: job?.completed && job?.started ? job.completed - job.started : null,
+        ...(control_image ? { mode: "controlnet", control_strength: body.control_strength } : {}),
+      },
+    };
+  },
+
+  /**
+   * The richest catalog of the three adapters: the settings UI reads samplers,
+   * schedulers and the server's own defaults straight off it, so nothing has
+   * to be hardcoded per install.
+   */
+  async capabilities(config = {}) {
+    if (!config.base_url) return null;
+    try {
+      const caps = await getJson(joinUrl(config.base_url, "/sdcpp/v1/capabilities"), {
+        headers: headersFor(config),
+        timeoutMs: 8000,
+      });
+      if (!caps) return null;
+      return {
+        models: caps.model ? [caps.model.stem || caps.model.name].filter(Boolean) : [],
+        samplers: caps.samplers || [],
+        schedulers: caps.schedulers || [],
+        defaults: caps.defaults || null,
+        modes: caps.supported_modes || [],
+        formats: caps.output_formats_by_mode?.img_gen || caps.output_formats || [],
+      };
+    } catch {
+      return null;
+    }
+  },
+};

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

@@ -0,0 +1,218 @@
+// Helpers shared by every image adapter. Nothing here talks to a specific
+// server — it is the plumbing three of the four adapters would otherwise each
+// grow their own copy of (base64 → file, size parsing, endpoint joining).
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** Strip a trailing slash so `${base}/v1/x` never becomes `//v1/x`. */
+export function trimBase(url) {
+  return String(url || "").replace(/\/+$/, "");
+}
+
+/**
+ * Join a base URL and a path, tolerating a base that already carries the API
+ * prefix. A user who pastes `http://host:8189/v1` into the OpenAI field and one
+ * who pastes `http://host:8189` must both end up at /v1/images/generations —
+ * getting this wrong is the single most common way a local endpoint "doesn't
+ * work" (it 404s and the error says nothing about the URL).
+ */
+export function joinUrl(base, suffix) {
+  const b = trimBase(base);
+  const s = suffix.startsWith("/") ? suffix : `/${suffix}`;
+  // e.g. base ".../v1" + suffix "/v1/images/generations" → don't repeat /v1
+  const firstSeg = s.split("/")[1];
+  if (firstSeg && b.endsWith(`/${firstSeg}`)) {
+    return b + s.slice(firstSeg.length + 1);
+  }
+  return b + s;
+}
+
+/** "512x768" → { width: 512, height: 768 }. Returns null when unparseable. */
+export function parseSize(size) {
+  const m = /^\s*(\d{2,5})\s*[x×*]\s*(\d{2,5})\s*$/.exec(String(size || ""));
+  if (!m) return null;
+  return { width: Number(m[1]), height: Number(m[2]) };
+}
+
+/** Reverse of parseSize — what OpenAI-shaped APIs want. */
+export function formatSize(width, height) {
+  return `${width}x${height}`;
+}
+
+const MIME_BY_EXT = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  gif: "image/gif",
+};
+
+export function mimeFor(format) {
+  return MIME_BY_EXT[String(format || "png").toLowerCase()] || "application/octet-stream";
+}
+
+/**
+ * Sniff the real container from the first bytes. Servers lie about (or omit)
+ * the format: stable-diffusion.cpp answers `output_format: "png"` for a
+ * request that asked for webp. The file extension should describe the actual
+ * bytes, or every viewer downstream has to guess.
+ */
+export function sniffFormat(buf, fallback = "png") {
+  if (!buf || buf.length < 12) return fallback;
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return "png";
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "jpeg";
+  if (buf.toString("ascii", 0, 4) === "RIFF" && buf.toString("ascii", 8, 12) === "WEBP") return "webp";
+  if (buf.toString("ascii", 0, 3) === "GIF") return "gif";
+  return fallback;
+}
+
+/**
+ * Write one decoded image into `outDir` and describe it. `index` only shapes
+ * the filename, so a batch stays ordered on disk the way it was generated.
+ */
+export function writeImage(buf, { outDir, provider, format, index = 0 }) {
+  const ext = sniffFormat(buf, format);
+  fs.mkdirSync(outDir, { recursive: true });
+  const suffix = index > 0 ? `-${index + 1}` : "";
+  const file = path.join(outDir, `${provider}-${randomUUID()}${suffix}.${ext === "jpeg" ? "jpg" : ext}`);
+  fs.writeFileSync(file, buf);
+  return { path: file, bytes: buf.length, mime: mimeFor(ext), format: ext };
+}
+
+/** Decode a base64 payload, tolerating a `data:image/png;base64,…` prefix. */
+export function decodeBase64Image(b64) {
+  const raw = String(b64 || "").replace(/^data:[^;]+;base64,/, "");
+  if (!raw) throw new Error("empty image payload");
+  return Buffer.from(raw, "base64");
+}
+
+/**
+ * Outbound counterpart of decodeBase64Image: hand a server bare base64.
+ *
+ * Diffusion servers are inconsistent about the `data:` prefix — A1111 strips it,
+ * stable-diffusion.cpp does not and decodes the literal "data:image/png;base64,"
+ * as image bytes, which fails deep inside the sampler with a message that names
+ * neither the field nor the prefix. Normalizing on the way out costs nothing and
+ * removes a whole class of "the reference image did nothing" reports.
+ */
+export function toRawBase64(b64) {
+  const raw = String(b64 || "").replace(/^data:[^;]+;base64,/, "").trim();
+  if (!raw) throw new Error("empty image payload");
+  return raw;
+}
+
+/**
+ * Pixel dimensions of a PNG or JPEG, straight from the header bytes.
+ *
+ * There is no image library in this tree and this does not need one: an
+ * inpainting mask whose size differs from the canvas is the single most common
+ * way the feature "does nothing", and the servers accept the mismatch silently.
+ * Reading two headers is enough to turn that into an error that names the fix.
+ *
+ * Returns null for anything it cannot parse — callers treat that as "unknown",
+ * never as "mismatched", so an exotic-but-valid file is not rejected.
+ */
+export function imageSize(buf) {
+  if (!buf || buf.length < 24) return null;
+  // PNG: an 8-byte signature, then the IHDR chunk with width/height at 16..24.
+  if (buf[0] === 0x89 && buf.toString("ascii", 1, 4) === "PNG") {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+  // JPEG: walk the marker segments to the first SOF, which carries the size.
+  if (buf[0] === 0xff && buf[1] === 0xd8) {
+    let i = 2;
+    while (i + 9 < buf.length) {
+      if (buf[i] !== 0xff) { i++; continue; }
+      const marker = buf[i + 1];
+      // SOF0-SOF15, minus the four that are not frame headers (DHT/JPG/DAC/RST).
+      if (marker >= 0xc0 && marker <= 0xcf &&
+          marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) };
+      }
+      i += 2 + buf.readUInt16BE(i + 2);
+    }
+  }
+  return null;
+}
+
+/**
+ * A stand-in for an image payload in anything a human or a log will read.
+ *
+ * The resolved request travels back to the caller and into `--json`; a 700 KB
+ * base64 string in there turns a readable receipt into an unreadable one and
+ * bloats every stored session. The size is what a reader actually wants.
+ */
+export function redactImagePayload(b64) {
+  const n = String(b64 || "").length;
+  return `<base64 ${Math.round((n * 3) / 4 / 1024)} KB>`;
+}
+
+/**
+ * POST JSON and parse the reply, turning a non-2xx into an Error whose message
+ * carries the server's own words — a 400 from a diffusion server usually names
+ * the offending field, and swallowing that costs the user the fix.
+ */
+export async function postJson(url, body, { headers = {}, signal, timeoutMs } = {}) {
+  const ctrl = timeoutMs ? new AbortController() : null;
+  const timer = ctrl ? setTimeout(() => ctrl.abort(), timeoutMs) : null;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body),
+      signal: signal || ctrl?.signal,
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* keep text */ }
+    if (!res.ok) {
+      const detail = json?.error?.message || json?.error || json?.detail || text;
+      throw new Error(`${res.status}: ${String(detail).slice(0, 300)}`);
+    }
+    return json;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** GET JSON with the same error shaping as postJson. */
+export async function getJson(url, { headers = {}, signal, timeoutMs } = {}) {
+  const ctrl = timeoutMs ? new AbortController() : null;
+  const timer = ctrl ? setTimeout(() => ctrl.abort(), timeoutMs) : null;
+  try {
+    const res = await fetch(url, { headers, signal: signal || ctrl?.signal });
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* keep text */ }
+    if (!res.ok) {
+      const detail = json?.error?.message || json?.error || json?.detail || text;
+      throw new Error(`${res.status}: ${String(detail).slice(0, 300)}`);
+    }
+    return json;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Is this endpoint answering at all? Used by isAvailable() probes: a
+ * configured-but-unreachable local server must not win the routing chain, or
+ * every generation fails with a connection error instead of falling through to
+ * the next engine.
+ */
+export async function probeUrl(url, { headers = {}, timeoutMs = 1500 } = {}) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, { headers, signal: ctrl.signal });
+      return res.ok;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return false;
+  }
+}

package/src/core/images/generate.js

@@ -0,0 +1,260 @@
+// Unified image-generation facade. Callers don't pick the engine — the
+// selector does, exactly like core/voice/tts.js does for speech.
+//
+//   generate({ prompt, ... })  → { images: [{path, …}], provider, model, … }
+//   listProviders()            → catalog + availability for the settings UI
+//   capabilities({ provider }) → live model/sampler list from one server
+//
+// Files land under ~/.apx/images/<YYYY-MM-DD>/ and STAY there: a generated
+// picture is an artifact the user asked for, not a scratch file, and nothing
+// is ever written into a project checkout unless a caller passes an explicit
+// destination.
+
+import fs from "node:fs";
+import path from "node:path";
+import { IMAGES_DIR } from "#core/config/paths.js";
+import { readConfig } from "#core/config/index.js";
+import {
+  selectImageEngine,
+  listAvailableImageEngines,
+  getImageAdapter,
+  providerConfig,
+  imagesConfig,
+  resolveMode,
+  resolveChainOrder,
+} from "./engines/index.js";
+import { parseSize, redactImagePayload } from "./engines/shared.js";
+
+export { IMAGES_DIR };
+
+/**
+ * Family-wide fallbacks. Deliberately conservative — 512² at 20 steps renders
+ * on any machine — and every one of them is overridable per call, then per
+ * engine (images.<id>.defaults), then globally (images.defaults).
+ */
+export const FAMILY_DEFAULTS = Object.freeze({
+  width: 512,
+  height: 512,
+  steps: 20,
+  cfg_scale: 7,
+  seed: -1,
+  count: 1,
+  format: "png",
+  negative_prompt: "",
+  sampler: "",
+  scheduler: "",
+});
+
+/** Every knob an adapter may be asked to honor. Order is display order. */
+export const REQUEST_OPTIONS = Object.freeze([
+  "negative_prompt", "width", "height", "steps", "cfg_scale",
+  "seed", "sampler", "scheduler", "count", "format", "model",
+  "init_image", "denoising_strength", "control_image", "control_strength",
+  "mask", "mask_blur", "inpainting_fill", "inpaint_full_res",
+]);
+
+/**
+ * The two ways a caller can hand in a reference picture. They are different
+ * operations against different routes, not two spellings of one:
+ *
+ *   init_image     the canvas the sampler starts from   (img2img, a1111 route)
+ *   control_image  a structural hint it renders around  (ControlNet, sdcpp route)
+ *
+ * `mask` is not a third one: it is a modifier on init_image that confines the
+ * repaint to part of the canvas (inpainting), which is why it rides the same
+ * route and is refused on its own.
+ *
+ * No engine speaks both, which is exactly why they are separate keys — folding
+ * them into one "reference image" would make the engine silently pick a
+ * meaning, and the two produce very different pictures.
+ */
+export const IMAGE_INPUTS = Object.freeze(["init_image", "control_image", "mask"]);
+
+/** Swap base64 payloads for a size marker in anything echoed back to a caller. */
+function redactInputs(request) {
+  const out = { ...request };
+  for (const k of IMAGE_INPUTS) {
+    if (out[k]) out[k] = redactImagePayload(out[k]);
+  }
+  return out;
+}
+
+/** Today's folder under the gallery. Dated so a busy week stays navigable. */
+export function imageOutDir(now = new Date()) {
+  const day = now.toISOString().slice(0, 10);
+  const dir = path.join(IMAGES_DIR, day);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Drop undefined/empty entries so a later layer's value isn't masked by "". */
+function present(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (v === undefined || v === null || v === "") continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Fold the four layers of settings into one request. Later wins:
+ *   family defaults → images.defaults → images.<engine>.defaults → the call.
+ * A `size: "768x512"` at any layer expands into width/height, because that is
+ * how humans and OpenAI-shaped APIs say it.
+ */
+export function resolveRequest({ imgCfg = {}, engineCfg = {}, request = {} } = {}) {
+  const expand = (layer) => {
+    const copy = present(layer);
+    if (copy.size) {
+      const parsed = parseSize(copy.size);
+      delete copy.size;
+      if (parsed) Object.assign(copy, parsed);
+    }
+    return copy;
+  };
+  return {
+    ...FAMILY_DEFAULTS,
+    ...expand(imgCfg.defaults),
+    ...expand(engineCfg.defaults),
+    ...expand(request),
+  };
+}
+
+/**
+ * Which of the caller's *explicit* knobs this engine cannot honor.
+ *
+ * Project rule: an adapter must honor — or explicitly declare it lacks — every
+ * option the family passes. Declaring is what `supports` does; this is the
+ * other half, so `--steps 8` against an OpenAI endpoint says so out loud
+ * instead of rendering something silently different from what was asked.
+ */
+export function ignoredOptions(adapter, request = {}) {
+  const supported = new Set(adapter?.supports || []);
+  return REQUEST_OPTIONS.filter((k) => {
+    if (supported.has(k)) return false;
+    const v = request[k];
+    if (v === undefined || v === null || v === "") return false;
+    // A default-valued knob was not "asked for" — only report a real choice.
+    if (k === "seed" && Number(v) === -1) return false;
+    if (k === "count" && Number(v) === 1) return false;
+    return true;
+  });
+}
+
+/**
+ * Generate one or more images. Throws on real errors; only falls back to the
+ * mock engine when nothing at all is configured AND no provider was forced
+ * (same contract as synthesize()).
+ *
+ * @param {object}   opts
+ * @param {string}   opts.prompt            What to draw. Required.
+ * @param {string}  [opts.negative_prompt]  What to avoid.
+ * @param {number}  [opts.width]            Pixels; also settable as `size`.
+ * @param {number}  [opts.height]
+ * @param {string}  [opts.size]             "768x512" — expands to width/height.
+ * @param {number}  [opts.steps]            Sampling steps.
+ * @param {number}  [opts.cfg_scale]        Prompt adherence.
+ * @param {number}  [opts.seed]             -1 for random.
+ * @param {string}  [opts.sampler]          Engine-specific sampler id.
+ * @param {string}  [opts.scheduler]        Engine-specific scheduler id.
+ * @param {number}  [opts.count]            How many images.
+ * @param {string}  [opts.format]           png | jpeg | webp.
+ * @param {string}  [opts.model]            Checkpoint / model id.
+ * @param {string}  [opts.provider]         Force an engine (skips the chain).
+ * @param {string}  [opts.outDir]           Where to write; defaults to the gallery.
+ * @param {object}  [opts.globalConfig]     Pass-in for tests; else readConfig().
+ * @param {Function}[opts.onProgress]       ({status, queue_position}) while polling.
+ * @param {AbortSignal} [opts.signal]
+ * @returns {Promise<{images, provider, model, prompt, request, ignored, elapsed_ms, meta}>}
+ */
+export async function generate({
+  prompt,
+  provider,
+  outDir,
+  globalConfig,
+  onProgress,
+  signal,
+  ...rest
+} = {}) {
+  if (typeof prompt !== "string" || !prompt.trim()) {
+    throw new Error("generate: prompt required");
+  }
+  const cfg = globalConfig || readConfig() || {};
+  const { provider: selected, adapter, engineConfig } = await selectImageEngine({
+    globalConfig: cfg,
+    provider,
+  });
+
+  const request = resolveRequest({
+    imgCfg: imagesConfig(cfg),
+    engineCfg: engineConfig,
+    request: rest,
+  });
+  const declaredIgnored = ignoredOptions(adapter, { ...present(rest) });
+
+  const dir = outDir || imageOutDir();
+  const started = Date.now();
+  const result = await adapter.generate({
+    ...request,
+    prompt: prompt.trim(),
+    outDir: dir,
+    config: engineConfig,
+    parentEnginesCfg: cfg.engines,
+    onProgress,
+    signal,
+  });
+
+  // An adapter may discover, from the reply, that the server dropped something
+  // it had declared support for — a single-checkpoint clone answering 200 to a
+  // checkpoint switch it never made. The static declaration is the promise;
+  // this is the receipt.
+  const ignored = [...new Set([...declaredIgnored, ...(result.unhonored || [])])];
+
+  return {
+    images: result.images || [],
+    provider: selected,
+    // Only claim the requested model when the adapter could actually act on
+    // it: a server that hosts one checkpoint would otherwise report back the
+    // name it just ignored, which reads as "your model was used".
+    model: result.model
+      || (adapter.supports?.includes("model") ? request.model : null)
+      || null,
+    prompt: prompt.trim(),
+    // Redacted: the payload is up to a megabyte of base64 and this object ends
+    // up in --json, in logs and in stored sessions.
+    request: redactInputs(request),
+    ignored,
+    elapsed_ms: Date.now() - started,
+    meta: result.meta || {},
+  };
+}
+
+/** Engines, availability, and the configured routing — for CLI and settings. */
+export async function listProviders(globalConfig) {
+  const cfg = globalConfig || readConfig() || {};
+  const imgCfg = imagesConfig(cfg);
+  return {
+    configured_provider: imgCfg.provider || "auto",
+    mode: resolveMode(imgCfg),
+    order: resolveChainOrder(imgCfg),
+    defaults: { ...FAMILY_DEFAULTS, ...present(imgCfg.defaults) },
+    engines: await listAvailableImageEngines(cfg),
+  };
+}
+
+/**
+ * Ask one server what it can do (models, samplers, schedulers). Returns null
+ * when the engine has no catalog route or is unreachable — the settings UI
+ * treats that as "type it by hand", not as an error.
+ */
+export async function capabilities({ provider, globalConfig } = {}) {
+  const cfg = globalConfig || readConfig() || {};
+  const id = provider && provider !== "auto"
+    ? provider
+    : (await selectImageEngine({ globalConfig: cfg })).provider;
+  const adapter = getImageAdapter(id, cfg);
+  if (typeof adapter.capabilities !== "function") return { provider: id, capabilities: null };
+  const caps = await adapter.capabilities(providerConfig(cfg, id), cfg.engines);
+  return { provider: id, capabilities: caps };
+}