ima2-gen 3.14.0 → 3.15.0

package/CHANGELOG.md

@@ -28,6 +28,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.15.0] - 2026-09-08
+
+### Added
+
+- **NovelAI quota lane** (#193) — `GET /api/quota` now returns `nai` alongside `codex` and `grok`: the Opus V5 battery meter (`v5-battery` window with remaining charge and the next +1% ETA), the `isNegative` recharge flag and fixed/purchased Anlas, read from `image.novelai.net/user/subscription` without forwarding account identifiers. Settings shows a NovelAI card with the charge bar and Anlas line when a token is configured.
+- **NAI 402 split** (#193) — a 402 on a V5 model probes the subscription once and reports `NAI_USAGE_EXHAUSTED` (battery drained, no Anlas) separately from `NAI_SUBSCRIPTION_REQUIRED`; V4.5 requests and failed probes keep the subscription code without a second request.
+
+### Changed
+
+- **Provider Adapter v1 execution hook** (#150) — `ProviderAdapterV1` gains an optional `prepareImageExecution` and the NovelAI, MiniMax, Atlas Cloud and ComfyUI adapters now own their classic/node/edit/multimode dispatch; `prepareImageExecution` routes to a registered adapter before the legacy lane switches, which are reduced to their unsupported-surface refusals. Descriptor adapters for `api`, `grok-api` and `gemini-api` (API key or Vertex service account) join the common contract suite; `oauth`, `grok` and `agy` stay unregistered because their readiness is asynchronous.
+
+### Fixed
+
+- Removed no-op `catch (error) { throw error; }` wrappers across provider execution, sprite, asset and LAN-session modules; behavior is unchanged and the coding convention now asks for try/catch only where an error is transformed, logged, or surfaced at a boundary.
+
+## [3.14.0] - 2026-09-06
+
 ### Production readiness
 
 - Correct NovelAI positive/negative prompt pane sizing, scrolling and toolbar spacing across sidebar, bottom, home and mobile composers; retain drafts when changing providers.

package/docs/API.md

@@ -154,7 +154,7 @@ inventing a runtime `lanes` availability result.
 | `GET` | `/api/oauth/status` | OAuth proxy status and visible models |
 | `GET` | `/api/grok/status` | Bundled progrok status and visible xAI image models |
 | `GET` | `/api/billing` | Billing/status probe, including API key source when configured |
-| `GET` | `/api/quota` | Provider quota: returns `{ codex, grok }`. Eligible Grok Build xAI OIDC/external auth returns a `weekly` percentage/reset window from `GET /v1/billing?format=credits`. If unavailable, the legacy endpoint may return a `monthly` window plus `billing: { usedUsd, limitUsd }`. |
+| `GET` | `/api/quota` | Provider quota: returns `{ codex, grok, nai }`. Codex windows are `5h` and `7d`. NovelAI returns a `v5-battery` remaining-charge window when available (`resetsAt` is the ISO ETA for +1%, not full recharge), with Anlas balances in `nai.anlasFixed` / `nai.anlasPurchased`; a missing meter has no window. NovelAI account email is always null. Eligible Grok Build xAI OIDC/external auth returns a `weekly` percentage/reset window from `GET /v1/billing?format=credits`. If unavailable, the legacy endpoint may return a `monthly` window plus `billing: { usedUsd, limitUsd }`. |
 
 ## Account Switching
 
@@ -1009,7 +1009,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `GET /api/events` (SSE multiplex) | Web UI only (persistent `EventSource`; no CLI wrapper) |
 | `GET /api/storage/status` / `POST /api/storage/open-generated-dir` | `ima2 storage status` / `ima2 storage open` |
 | `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` / `GET /api/grok/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` / `ima2 grok status` |
-| `GET /api/quota` | Web UI only (Grok quota bar in Settings) |
+| `GET /api/quota` | Web UI only (Grok and NovelAI quota in Settings) |
 | `POST /api/auth/switch` / `GET /api/auth/switch/:sessionId` | Web UI only (Settings > QuotaCard > Switch Account) |
 | `GET /api/health` | `ima2 ping` |
 | `GET /api/capabilities` | `ima2 capabilities` |

package/docs/CLI.md

@@ -462,7 +462,7 @@ Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `feature
 | `ima2 inflight rm <requestId>` | Force-remove a stuck job |
 | `ima2 storage status` | Storage inspection (richer than `doctor`) |
 | `ima2 storage open` | Open the generated dir in the OS file manager (POST) |
-| `ima2 billing` | API usage probe via `/api/billing` (OpenAI/API-key credits when configured). Grok quota is web-UI only via `GET /api/quota`: weekly percentage/reset for current Grok Build xAI auth, with legacy monthly `usedUsd`/`limitUsd` fallback. |
+| `ima2 billing` | API usage probe via `/api/billing` (OpenAI/API-key credits when configured). Grok and NovelAI quota are web-UI only via `GET /api/quota`: weekly percentage/reset for current Grok Build xAI auth, with legacy monthly `usedUsd`/`limitUsd` fallback. |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
 | `ima2 grok status` | Bundled progrok / xAI image-model probe state |

package/docs/CLI.zh-CN.md

@@ -349,7 +349,7 @@ Windows DNS/碎片绕过工具（例如 SecretDNS）正在使用。
 | `ima2 inflight rm <requestId>` |强制删除卡住的作业|
 | `ima2 storage status` |入库检查（丰富于`doctor`) |
 | `ima2 storage open` |在操作系统文件管理器（POST）中打开生成的目录|
-| `ima2 billing` | API使用探针通过`/api/billing` (OpenAI/API- 配置后的密钥积分）。Grok配额是网络-UI仅通过`GET /api/quota`：当前的每周百分比/重置Grok建造xAIauth，每月遗留`usedUsd`/`limitUsd`倒退。|
+| `ima2 billing` | API使用探针通过`/api/billing` (OpenAI/API- 配置后的密钥积分）。Grok和NovelAI配额仅在网页UI中通过`GET /api/quota`：当前的每周百分比/重置Grok建造xAIauth，每月遗留`usedUsd`/`limitUsd`倒退。|
 | `ima2 providers` |配置的提供商|
 | `ima2 oauth status` | OAuth代理状态|
 | `ima2 grok status` |捆绑式progrok / xAI图像模型探测状态|

package/docs/CLI.zh-TW.md

@@ -349,7 +349,7 @@ Windows DNS/碎片繞過工具（例如 SecretDNS）正在使用。
 | `ima2 inflight rm <requestId>` |強制刪除卡住的作業|
 | `ima2 storage status` |入庫檢查（豐富於`doctor`) |
 | `ima2 storage open` |在作業系統檔案管理器（POST）中開啟產生的目錄|
-| `ima2 billing` | API使用探針通過`/api/billing` (OpenAI/API- 配置後的金鑰積分）。Grok配額是網絡-UI僅透過`GET /api/quota`：目前的每週百分比/重置Grok建造xAIauth，每月遺留`usedUsd`/`limitUsd`倒退。|
+| `ima2 billing` | API使用探針通過`/api/billing` (OpenAI/API- 配置後的金鑰積分）。Grok和NovelAI配額僅在網頁UI中透過`GET /api/quota`：目前的每週百分比/重置Grok建造xAIauth，每月遺留`usedUsd`/`limitUsd`倒退。|
 | `ima2 providers` |配置的提供者|
 | `ima2 oauth status` | OAuth代理狀態|
 | `ima2 grok status` |捆綁式progrok / xAI影像模型探測狀態|

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 487 (runtime: 224, contract: 263)
+Total: 488 (runtime: 225, contract: 263)
 
 ## Runtime-importing tests
 - `tests/agent-image-reference-contract.test.ts`
@@ -147,6 +147,7 @@ Total: 487 (runtime: 224, contract: 263)
 - `tests/nai-options-contract.test.ts`
 - `tests/nai-provider-contract.test.ts`
 - `tests/nai-routing-contract.test.ts`
+- `tests/nai-subscription-contract.test.ts`
 - `tests/nai-zip-decode.test.ts`
 - `tests/node-parent-source-contract.test.ts`
 - `tests/node-route-refs.test.ts`

package/lib/agyArtifactRead.js

@@ -157,9 +157,6 @@ async function readBytes(handle, signal) {
             throw tooLarge();
         return Buffer.concat(chunks, total);
     }
-    catch (error) {
-        throw error;
-    }
     finally {
         chunks.length = 0;
     }

package/lib/assetLifecycle.js

@@ -29,12 +29,7 @@ export function resolveInGenerated(rootDir, relPath) {
     return target;
 }
 export async function assertRegularGeneratedPath(path) {
-    try {
-        await regularFileWithin(path, config.storage.generatedDir);
-    }
-    catch (error) {
-        throw error;
-    }
+    await regularFileWithin(path, config.storage.generatedDir);
 }
 /** Existing assets only; output filenames use the separate lexical resolver. */
 async function regularFileWithin(path, root) {

package/lib/errors/providerMap.js

@@ -45,6 +45,7 @@ export const PROVIDER_ERROR_MAP = {
     // NovelAI answers 402 when the account has no active subscription, which is
     // a billing state rather than a bad token.
     NAI_SUBSCRIPTION_REQUIRED: "BILLING_REQUIRED",
+    NAI_USAGE_EXHAUSTED: "BILLING_REQUIRED",
     NAI_BAD_REQUEST: "CAPABILITY_UNSUPPORTED",
     NAI_RATE_LIMITED: "RATE_LIMITED",
     NAI_UPSTREAM_ERROR: "NETWORK_FAILURE",

package/lib/mcp/downloadMediaResult.js

@@ -24,12 +24,7 @@ async function resolvePublicHttps(url, signal) {
     }
 }
 export async function assertPublicHttps(url) {
-    try {
-        await resolvePublicHttps(url, new AbortController().signal);
-    }
-    catch (error) {
-        throw error;
-    }
+    await resolvePublicHttps(url, new AbortController().signal);
 }
 /** Transient right after task completion: network-level failures and
  *  403/5xx from CDN propagation are worth retrying; contract violations and

package/lib/naiImageAdapter.js

@@ -1,6 +1,7 @@
 import { detectImageMimeFromB64 } from "./refs.js";
 import { logEvent } from "./logger.js";
 import { extractFirstZipEntry, looksLikeZip } from "./naiZip.js";
+import { classifyNai402, naiError } from "./naiSubscription.js";
 export const NAI_DEFAULT_IMAGE_MODEL = "nai-diffusion-5-full";
 const NAI_TIMEOUT_MS = 180_000;
 /** Accepted by the V5 endpoint; the reference client offers exactly these. */
@@ -20,13 +21,6 @@ export const NAI_UC_PRESET_IDS = ["heavy", "light", "furryFocus", "humanFocus",
 export const NAI_QUALITY_PRESET_IDS = ["standard", "light", "none"];
 const DEFAULT_WIDTH = 832;
 const DEFAULT_HEIGHT = 1216;
-function naiError(message, status, code) {
-    const err = new Error(message);
-    err.status = status;
-    err.code = code;
-    err.isOperational = true;
-    return err;
-}
 /** NovelAI sizes are WxH strings; anything else falls back to the portrait default. */
 function parseSize(size) {
     if (!size || size === "auto")
@@ -75,7 +69,8 @@ export async function generateViaNai(prompt, ctx, options = {}) {
         scale: options.scale ?? cfg.defaultScale,
         sampler,
         steps: options.steps ?? cfg.defaultSteps,
-        // Kept at 1: NovelAI's Opus free tier only covers single-image requests.
+        // Opus V5 battery covers 832x1216 / <=28 steps / one image; larger
+        // resolutions or more steps use Anlas instead. Keep the defaults eligible.
         n_samples: 1,
         ucPresetId: options.ucPresetId ?? "heavy",
         qualityPresetId: isV5 ? (options.qualityPresetId ?? "standard") : "standard",
@@ -147,7 +142,7 @@ export async function generateViaNai(prompt, ctx, options = {}) {
             throw naiError(`NovelAI rejected the token: ${detail}`, 401, "NAI_AUTH_FAILED");
         }
         if (res.status === 402) {
-            throw naiError(`NovelAI requires an active subscription: ${detail}`, 402, "NAI_SUBSCRIPTION_REQUIRED");
+            throw await classifyNai402(ctx, model, detail, combinedSignal);
         }
         if (res.status === 429) {
             throw naiError(`NovelAI rate limited: ${detail}`, 429, "NAI_RATE_LIMITED");

package/lib/naiSubscription.js

@@ -0,0 +1,95 @@
+const subscriptionTimeoutMs = 5_000;
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : null;
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function findBattery(root) {
+    const pending = [root];
+    const seen = new Set(pending);
+    for (const current of pending) {
+        const percent = current === root ? null : finiteNumber(current.percent);
+        if (percent !== null)
+            return {
+                percent,
+                isNegative: current.isNegative === true,
+                timeUntilNextPercentSec: finiteNumber(current.timeUntilNextPercent),
+            };
+        for (const key of Object.keys(current)) {
+            // Do not even read identity/credential values while locating a moved meter.
+            if (/email|token|^(?:id|user_?id|raw_?body)$/i.test(key))
+                continue;
+            const child = record(current[key]);
+            if (child && !seen.has(child)) {
+                seen.add(child);
+                pending.push(child);
+            }
+        }
+    }
+    return null;
+}
+export function parseNaiSubscription(value) {
+    const subscription = record(value);
+    if (!subscription || typeof subscription.active !== "boolean")
+        return null;
+    const anlas = record(subscription.trainingStepsLeft);
+    return {
+        active: subscription.active,
+        tier: finiteNumber(subscription.tier),
+        battery: findBattery(subscription),
+        anlas: {
+            fixed: finiteNumber(anlas?.fixedTrainingStepsLeft) ?? 0,
+            purchased: finiteNumber(anlas?.purchasedTrainingSteps) ?? 0,
+        },
+    };
+}
+export async function fetchNaiSubscription(ctx, opts = {}) {
+    if (!ctx.naiApiKey)
+        return { ok: false, status: 401 };
+    try {
+        const timeoutMs = Math.min(subscriptionTimeoutMs, Math.max(0, finiteNumber(opts.timeoutMs) ?? subscriptionTimeoutMs));
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+        signal.throwIfAborted();
+        const accountBaseUrl = ctx.config?.naiProvider?.accountBaseUrl;
+        if (!accountBaseUrl)
+            return { ok: false, status: "error" };
+        const baseUrl = accountBaseUrl.replace(/\/$/, "");
+        const response = await fetch(`${baseUrl}/user/subscription`, {
+            headers: { Authorization: `Bearer ${ctx.naiApiKey}`, "Content-Type": "application/json" },
+            signal,
+        });
+        if (!response.ok)
+            return { ok: false, status: response.status === 401 ? 401 : "error" };
+        const snapshot = parseNaiSubscription(await response.json());
+        signal.throwIfAborted();
+        return snapshot ? { ok: true, snapshot } : { ok: false, status: "error" };
+    }
+    catch {
+        // Subscription bodies and errors can contain account identifiers; never log them.
+        return { ok: false, status: "error" };
+    }
+}
+export function isNaiBatteryModel(model) {
+    return model.startsWith("nai-diffusion-5-");
+}
+export function naiBatteryExhausted(snapshot) {
+    return snapshot.battery !== null && (snapshot.battery.isNegative || snapshot.battery.percent <= 0);
+}
+export function naiAnlasAvailable(snapshot) {
+    return snapshot.anlas.fixed + snapshot.anlas.purchased > 0;
+}
+export function naiError(message, status, code) {
+    return Object.assign(new Error(message), { status, code, isOperational: true });
+}
+export async function classifyNai402(ctx, model, detail, signal) {
+    if (isNaiBatteryModel(model)) {
+        const result = await fetchNaiSubscription(ctx, { signal, timeoutMs: subscriptionTimeoutMs });
+        if (result.ok && result.snapshot.active && naiBatteryExhausted(result.snapshot) && !naiAnlasAvailable(result.snapshot)) {
+            return naiError("NovelAI V5 battery exhausted and no Anlas available", 402, "NAI_USAGE_EXHAUSTED");
+        }
+    }
+    return naiError(`NovelAI requires an active subscription: ${detail}`, 402, "NAI_SUBSCRIPTION_REQUIRED");
+}

package/lib/pinnedHttpGet.js

@@ -121,27 +121,22 @@ const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 /** Public consumers cannot opt into Grok's configured proxy exception. */
 export async function publicPinnedHttpGet(rawUrl, signal, validateUrl, headers) {
     let url = new URL(rawUrl);
-    try {
-        for (let hop = 0;; hop++) {
-            signal.throwIfAborted();
-            validateUrl(url.href); // Includes scheme/allowhost, before DNS and every socket.
-            const target = await resolvePublicDownloadTarget(url, signal);
-            const response = await pinnedHttpGet(target, signal, headers ? { headers } : {});
-            if (!REDIRECT_STATUSES.has(response.status))
-                return response;
-            try {
-                const location = response.headers.get("location");
-                if (!location?.trim() || hop >= MAX_PUBLIC_REDIRECTS)
-                    throw new Error("PINNED_GET_REDIRECT_REFUSED");
-                url = new URL(location, url);
-            }
-            finally {
-                response.cancel();
-            }
+    for (let hop = 0;; hop++) {
+        signal.throwIfAborted();
+        validateUrl(url.href); // Includes scheme/allowhost, before DNS and every socket.
+        const target = await resolvePublicDownloadTarget(url, signal);
+        const response = await pinnedHttpGet(target, signal, headers ? { headers } : {});
+        if (!REDIRECT_STATUSES.has(response.status))
+            return response;
+        try {
+            const location = response.headers.get("location");
+            if (!location?.trim() || hop >= MAX_PUBLIC_REDIRECTS)
+                throw new Error("PINNED_GET_REDIRECT_REFUSED");
+            url = new URL(location, url);
+        }
+        finally {
+            response.cancel();
         }
-    }
-    catch (error) {
-        throw error;
     }
 }
 export class PinnedBodyTooLarge extends Error {
@@ -165,9 +160,6 @@ export async function readPinnedBody(response, maxBytes) {
             }
         return Buffer.concat(chunks, total); // Empty text remains a valid import input.
     }
-    catch (error) {
-        throw error;
-    }
     finally {
         response.cancel();
     }

package/lib/providers/adapters/api.js

@@ -0,0 +1,55 @@
+import { getProvider } from "../registry.js";
+const LANE_ID = "api";
+const ERROR_PREFIX = getProvider(LANE_ID).errorPrefix;
+/** Status codes worth retrying: transient upstream conditions, not bad input. */
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+function readStatus(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const candidate = error;
+    return typeof candidate.status === "number" ? candidate.status
+        : typeof candidate.statusCode === "number" ? candidate.statusCode
+            : undefined;
+}
+function readCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const candidate = error;
+    return typeof candidate.code === "string" ? candidate.code : undefined;
+}
+export function createApiAdapter(ctx) {
+    return {
+        laneId: LANE_ID,
+        validateAuth() {
+            return ctx.apiKey
+                ? { ok: true }
+                : { ok: false, reason: "OpenAI API key missing" };
+        },
+        listModels() {
+            // Straight from the registry. A hand-written list here is exactly the
+            // drift the capability registry was built to remove.
+            return getProvider(LANE_ID).models;
+        },
+        normalizeError(error) {
+            const status = readStatus(error);
+            const rawCode = readCode(error);
+            const message = error instanceof Error ? error.message
+                : typeof error === "string" ? error
+                    : "OpenAI request failed";
+            const code = !ERROR_PREFIX
+                ? rawCode ?? "UNKNOWN"
+                : rawCode?.startsWith(ERROR_PREFIX)
+                    ? rawCode
+                    : rawCode
+                        ? `${ERROR_PREFIX}${rawCode}`
+                        : `${ERROR_PREFIX}UNKNOWN`;
+            const retryable = status === undefined ? false : RETRYABLE_STATUSES.has(status);
+            return {
+                code,
+                message,
+                ...(status === undefined ? {} : { status }),
+                retryable,
+            };
+        },
+    };
+}

package/lib/providers/adapters/atlascloud.js

@@ -1,3 +1,10 @@
+/**
+ * Atlas Cloud adapter: readiness, registry models, errors and image execution surfaces.
+ * The existing image adapter retains transport and provider protocol ownership.
+ */
+import { generateViaAtlasCloud } from "../../atlasCloudImageAdapter.js";
+import { detectImageMimeFromB64 } from "../../refs.js";
+import { requireRuntimeContext } from "../../runtimeContext.js";
 import { getProvider } from "../registry.js";
 const LANE_ID = "atlascloud";
 const ERROR_PREFIX = "ATLASCLOUD_";
@@ -28,6 +35,7 @@ function readCode(error) {
 export function createAtlasCloudAdapter(ctx) {
     return {
         laneId: LANE_ID,
+        prepareImageExecution: prepareLaneImageExecution,
         validateAuth() {
             // Presence only, and note the spelling: the context field is
             // atlasCloudApiKey (capital C) while the lane id is all-lowercase.
@@ -61,3 +69,61 @@ export function createAtlasCloudAdapter(ctx) {
         },
     };
 }
+function prepareClassic(ctx, request) {
+    const { prompt: generationPrompt, requestId, background: backgroundParams } = request;
+    const { model: imageModel, size: effectiveSize, quality } = request.options;
+    // Capture scalars/background at prepare; ctx, refs, signal and lane options stay live.
+    return { execute: async () => {
+            const value = await generateViaAtlasCloud(generationPrompt, requireRuntimeContext(ctx), {
+                model: imageModel, size: effectiveSize, quality, signal: request.signal,
+                requestId, references: request.references,
+                ...(backgroundParams ? { background: backgroundParams.background } : {}),
+                // The caller's resolveImageBackgroundParams validates this alpha-only format.
+                ...(backgroundParams?.outputFormat ? { outputFormat: backgroundParams.outputFormat } : {}),
+            });
+            return { kind: "single", value };
+        } };
+}
+function prepareNode(ctx, request) {
+    return { execute: async () => {
+            const { sourceImage: parentB64, rawPrompt: prompt, references, requestId, signal, options } = request;
+            const { model, size, quality } = options;
+            const value = await generateViaAtlasCloud(parentB64 ? `Edit this image: ${prompt}` : prompt, requireRuntimeContext(ctx), {
+                model, size, quality, signal, requestId,
+                references: parentB64
+                    ? [{ b64: parentB64, declaredMime: null, detectedMime: null }, ...references]
+                    : references,
+            });
+            return { kind: "single", value };
+        } };
+}
+function prepareEdit(ctx, request) {
+    return { execute: async () => {
+            const { prompt, sourceImage, signal, requestId, options } = request;
+            const references = [{ b64: sourceImage, declaredMime: null, detectedMime: detectImageMimeFromB64(sourceImage) || null }];
+            const editPrompt = `Edit this image: ${prompt}`;
+            const params = { model: options.model, size: options.size, signal, ...(requestId !== undefined ? { requestId } : {}), references };
+            const value = await generateViaAtlasCloud(editPrompt, ctx, { ...params, quality: options.quality });
+            return { kind: "single", value };
+        } };
+}
+function prepareMultimode(ctx, request) {
+    return { execute: async () => {
+            const { rawPrompt, references, signal, requestId, options } = request;
+            const params = { model: options.model, size: options.size, signal, ...(requestId !== undefined ? { requestId } : {}), references };
+            const result = await generateViaAtlasCloud(rawPrompt, ctx, { ...params, quality: options.quality });
+            // Preserve the projection; the caller owns the final persistence sweep.
+            return { kind: "sequence", value: {
+                    images: [{ b64: result.b64, ...(result.revisedPrompt !== undefined ? { revisedPrompt: result.revisedPrompt } : {}) }],
+                    usage: result.usage, webSearchCalls: result.webSearchCalls,
+                } };
+        } };
+}
+async function prepareLaneImageExecution(ctx, request, _progress) {
+    switch (request.surface) {
+        case "classic": return prepareClassic(ctx, request);
+        case "node": return prepareNode(ctx, request);
+        case "edit": return prepareEdit(ctx, request);
+        case "multimode": return prepareMultimode(ctx, request);
+    }
+}

package/lib/providers/adapters/comfy.js

@@ -1,3 +1,23 @@
+/**
+ * Comfy adapter (#150) — the first runtime-catalog lane.
+ *
+ * MiniMax and Atlas Cloud project a compile-time model list and answer "am I
+ * authenticated" from an API key. Comfy has neither: its models are workflows
+ * the user registered, and it has no credential at all. What decides whether
+ * the lane is usable is whether any workflow exists, because an empty store
+ * makes every generation a guaranteed 400 — which is exactly what the UI needs
+ * to say.
+ *
+ * Both methods read ctx.comfyWorkflows rather than the store. The interface is
+ * synchronous while the store is async, and the contract suite injects lane
+ * state exclusively through RuntimeContext — a module-level cache could not be
+ * empty and non-empty for the two calls that suite makes. Generation does not
+ * use this projection: lib/comfyImageAdapter reads the store directly, so a
+ * context lagging one write can never run a stale graph.
+ */
+import { generateViaComfy } from "../../comfyImageAdapter.js";
+import { detectImageMimeFromB64 } from "../../refs.js";
+import { requireRuntimeContext } from "../../runtimeContext.js";
 const LANE_ID = "comfy";
 const ERROR_PREFIX = "COMFY_";
 /** Transient upstream conditions, not bad input. */
@@ -19,6 +39,7 @@ function readCode(error) {
 export function createComfyAdapter(ctx) {
     return {
         laneId: LANE_ID,
+        prepareImageExecution: prepareLaneImageExecution,
         validateAuth() {
             const workflows = (ctx.comfyWorkflows ?? []).filter((workflow) => workflow.mediaKind !== "video");
             return workflows.length > 0
@@ -42,24 +63,60 @@ export function createComfyAdapter(ctx) {
                 },
             }));
         },
-        normalizeError(error) {
-            const status = readStatus(error);
-            const rawCode = readCode(error);
-            const message = error instanceof Error ? error.message
-                : typeof error === "string" ? error
-                    : "ComfyUI request failed";
-            const code = rawCode?.startsWith(ERROR_PREFIX)
-                ? rawCode
-                : rawCode
-                    ? `${ERROR_PREFIX}${rawCode}`
-                    : `${ERROR_PREFIX}UNKNOWN`;
-            const retryable = status === undefined ? false : RETRYABLE_STATUSES.has(status);
-            return {
-                code,
-                message,
-                ...(status === undefined ? {} : { status }),
-                retryable,
-            };
-        },
+        normalizeError,
+    };
+}
+function prepareClassic(ctx, request, progress) {
+    const { prompt: generationPrompt, requestId } = request;
+    const { model: imageModel, size: effectiveSize } = request.options;
+    // Capture scalars at prepare; ctx, refs, signal and lane options stay live.
+    return { execute: async () => {
+            const value = await generateViaComfy(generationPrompt, requireRuntimeContext(ctx), {
+                model: imageModel, size: effectiveSize, signal: request.signal,
+                requestId, references: request.references,
+                ...request.comfy, onQueue: progress.onQueue,
+            });
+            return { kind: "single", value };
+        } };
+}
+function prepareEdit(ctx, request) {
+    return { execute: async () => {
+            const { prompt, sourceImage, signal, requestId, options } = request;
+            const references = [{ b64: sourceImage, declaredMime: null, detectedMime: detectImageMimeFromB64(sourceImage) || null }];
+            const editPrompt = `Edit this image: ${prompt}`;
+            const params = { model: options.model, size: options.size, signal, ...(requestId !== undefined ? { requestId } : {}), references };
+            const value = await generateViaComfy(editPrompt, ctx, params);
+            return { kind: "single", value };
+        } };
+}
+async function prepareLaneImageExecution(ctx, request, progress = {}) {
+    switch (request.surface) {
+        case "classic": return prepareClassic(ctx, request, progress);
+        case "node": return { execute: async () => {
+                throw new Error(`Unsupported node execution provider: ${request.provider}`);
+            } };
+        case "edit": return prepareEdit(ctx, request);
+        case "multimode": return { execute: async () => {
+                throw new Error(`Unsupported legacy multimode provider: ${request.provider}`);
+            } };
+    }
+}
+function normalizeError(error) {
+    const status = readStatus(error);
+    const rawCode = readCode(error);
+    const message = error instanceof Error ? error.message
+        : typeof error === "string" ? error
+            : "ComfyUI request failed";
+    const code = rawCode?.startsWith(ERROR_PREFIX)
+        ? rawCode
+        : rawCode
+            ? `${ERROR_PREFIX}${rawCode}`
+            : `${ERROR_PREFIX}UNKNOWN`;
+    const retryable = status === undefined ? false : RETRYABLE_STATUSES.has(status);
+    return {
+        code,
+        message,
+        ...(status === undefined ? {} : { status }),
+        retryable,
     };
 }

package/lib/providers/adapters/gemini-api.js

@@ -0,0 +1,55 @@
+import { getProvider } from "../registry.js";
+const LANE_ID = "gemini-api";
+const ERROR_PREFIX = getProvider(LANE_ID).errorPrefix;
+/** Status codes worth retrying: transient upstream conditions, not bad input. */
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+function readStatus(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const candidate = error;
+    return typeof candidate.status === "number" ? candidate.status
+        : typeof candidate.statusCode === "number" ? candidate.statusCode
+            : undefined;
+}
+function readCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const candidate = error;
+    return typeof candidate.code === "string" ? candidate.code : undefined;
+}
+export function createGeminiApiAdapter(ctx) {
+    return {
+        laneId: LANE_ID,
+        validateAuth() {
+            return ctx.geminiApiKey || ctx.vertexServiceAccountJson
+                ? { ok: true }
+                : { ok: false, reason: "Gemini API key or Vertex service account missing" };
+        },
+        listModels() {
+            // Straight from the registry. A hand-written list here is exactly the
+            // drift the capability registry was built to remove.
+            return getProvider(LANE_ID).models;
+        },
+        normalizeError(error) {
+            const status = readStatus(error);
+            const rawCode = readCode(error);
+            const message = error instanceof Error ? error.message
+                : typeof error === "string" ? error
+                    : "Gemini API request failed";
+            const code = !ERROR_PREFIX
+                ? rawCode ?? "UNKNOWN"
+                : rawCode?.startsWith(ERROR_PREFIX)
+                    ? rawCode
+                    : rawCode
+                        ? `${ERROR_PREFIX}${rawCode}`
+                        : `${ERROR_PREFIX}UNKNOWN`;
+            const retryable = status === undefined ? false : RETRYABLE_STATUSES.has(status);
+            return {
+                code,
+                message,
+                ...(status === undefined ? {} : { status }),
+                retryable,
+            };
+        },
+    };
+}