ima2-gen 3.5.3 → 3.6.0

package/bin/lib/mcpJob.js

@@ -80,6 +80,22 @@ function doneResult(data) {
         result: { filename: data.filename, url: data.url, meta: data },
     };
 }
+/** Human-readable failure text. Non-MCP producers put it in data.error; MCP routes use data.message. */
+function errorMessage(data) {
+    if (typeof data.error === "string" && data.error)
+        return data.error;
+    if (typeof data.message === "string" && data.message)
+        return data.message;
+    return "MCP job failed";
+}
+/** Defensive code fallback per canonical phase; producers normally supply data.code. */
+function fallbackCode(phase) {
+    if (phase === "cancelled")
+        return "GENERATION_CANCELED";
+    if (phase === "timed_out")
+        return "MCP_JOB_TIMEOUT";
+    return "MCP_JOB_FAILED";
+}
 function matchingOutcome(event, opts) {
     if (event.event === "replay-gap")
         return { kind: "replay-gap", lastEventId: event.id };
@@ -91,6 +107,28 @@ function matchingOutcome(event, opts) {
             opts.onProgress?.(data.phase);
         return null;
     }
+    // #151 stage 2: the canonical envelope is the primary terminal signal. The
+    // event-name branches below stay as the fallback for servers that predate it.
+    const envelope = asRecord(data.envelope);
+    if (envelope && envelope.terminal === true) {
+        const phase = String(envelope.phase ?? "");
+        if (phase === "completed") {
+            // Only a real done event carries filename/url; a non-done event with a
+            // completed envelope falls through rather than minting an invalid-event
+            // error.
+            if (event.event === "done")
+                return doneResult(data);
+        }
+        else {
+            const envErr = asRecord(envelope.error);
+            return {
+                kind: "error",
+                error: new McpJobError(typeof envErr?.code === "string" ? envErr.code
+                    : typeof data.code === "string" ? data.code
+                        : fallbackCode(phase), errorMessage(data)),
+            };
+        }
+    }
     if (event.event === "done")
         return doneResult(data);
     if (event.event === "error") {

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: 362 (runtime: 159, contract: 203)
+Total: 364 (runtime: 161, contract: 203)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -78,6 +78,7 @@ Total: 362 (runtime: 159, contract: 203)
 - `tests/inflight-persistence.test.ts`
 - `tests/inflight.test.ts`
 - `tests/job-envelope-contract.test.ts`
+- `tests/job-envelope-terminal-coverage.test.ts`
 - `tests/job-idempotency.test.ts`
 - `tests/job-terminal-status-contract.test.ts`
 - `tests/local-import-contract.test.ts`
@@ -88,6 +89,7 @@ Total: 362 (runtime: 159, contract: 203)
 - `tests/mcp-download-retry.test.ts`
 - `tests/mcp-edit-video.test.ts`
 - `tests/mcp-generation-integration.test.ts`
+- `tests/mcp-job-envelope-consumer.test.ts`
 - `tests/mcp-log-secrecy.test.ts`
 - `tests/mcp-long-job-recovery.test.ts`
 - `tests/mcp-media-action.test.ts`

package/lib/generatePipeline.js

@@ -54,7 +54,8 @@ export async function runGeneratePipeline(req, res, ctx) {
         // generation is the default and never publishes a terminal event.
         completeIdempotencyKey(idempotencyKey, "error", { ...payload, status });
         if (asyncMode && res.headersSent) {
-            publish(requestId, "error", { ...payload, status, requestId });
+            // #151 stage 2: terminal failure carries the canonical envelope.
+            publishJobEvent(requestId, "error", { ...payload, status, requestId });
             return;
         }
         return res.status(status).json(payload);

package/lib/inflight.js

@@ -1,6 +1,7 @@
 import { config } from "../config.js";
 import { getDb } from "./db.js";
 import { publish } from "./eventBus.js";
+import { buildEnvelope } from "./jobs/envelope.js";
 import { logError, logEvent } from "./logger.js";
 const terminalJobs = new Map(); // requestId -> terminal snapshot, active-only API stays default
 /**
@@ -144,11 +145,26 @@ export function abortJob(requestId) {
         aborted = true;
     }
     if (active || aborted) {
-        publish(requestId, "error", {
+        // #151 stage 2: the cancel path is a terminal event, so it carries the
+        // canonical envelope. Assembled inline rather than via ssePublish because
+        // ssePublish imports this module (cycle), and abortJob already knows the
+        // inflight phase locally.
+        const data = {
             error: "Generation canceled",
             code: "GENERATION_CANCELED",
             status: 499,
             requestId,
+        };
+        const inflightPhase = getJobPhase(requestId);
+        publish(requestId, "error", data, {
+            buildEnvelope: (sequence) => buildEnvelope({
+                jobId: requestId,
+                requestId,
+                sequence,
+                event: "error",
+                data,
+                inflightPhase,
+            }),
         });
     }
     finishJob(requestId, {

package/lib/multimodePipeline.js

@@ -69,7 +69,8 @@ async function resolveMultimodeElements(elementIds, references, activeProvider,
 function dualEmitMultimode(res, requestId, event, data) {
     if (!res.writableEnded)
         writeSse(res, event, data);
-    if (event === "done") {
+    if (event === "done" || event === "error") {
+        // #151 stage 2: terminal events carry the canonical envelope.
         publishJobEvent(requestId, event, data);
     }
     else {
@@ -77,7 +78,8 @@ function dualEmitMultimode(res, requestId, event, data) {
     }
 }
 function respondMultimodeValidationError(res, requestId, asyncMode, status, payload) {
-    publish(requestId, "error", payload);
+    // #151 stage 2: terminal failure carries the canonical envelope.
+    publishJobEvent(requestId, "error", payload);
     if (asyncMode && !res.headersSent) {
         return res.status(status).json(payload);
     }

package/lib/nodeHelpers.js

@@ -1,7 +1,7 @@
 import { loadNodeB64, loadNodeMeta } from "./nodeStore.js";
 import { detectImageMimeFromB64 } from "./refs.js";
 import { writeSse } from "./routeHelpers.js";
-import { publish } from "./eventBus.js";
+import { publishJobEvent } from "./ssePublish.js";
 import { errorEnvelopeFields } from "./errors/envelope.js";
 export function asUpstream(e) {
     return (e && typeof e === "object" ? e : {});
@@ -18,8 +18,14 @@ export function writeNodeError(res, status, code, message, parentNodeId, details
         status,
         ...payloadDetails,
     };
-    if (requestId)
-        publish(requestId, "error", payload);
+    if (requestId) {
+        // #151 stage 2: node-mode terminal failure carries the canonical envelope.
+        // The bus record flattens code/error to top-level strings because
+        // buildEnvelope's errorFromData/resolvePhase read data.code / data.error as
+        // strings — the nested shape would stamp every node error "failed" and drop
+        // envelope.error (cancel/timeout classification depends on data.code).
+        publishJobEvent(requestId, "error", { ...payload, code, error: message });
+    }
     if (res.writableEnded || res.destroyed)
         return;
     if (res.headersSent) {

package/lib/providers/adapters/atlascloud.js

@@ -0,0 +1,63 @@
+import { getProvider } from "../registry.js";
+const LANE_ID = "atlascloud";
+const ERROR_PREFIX = "ATLASCLOUD_";
+/** 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;
+}
+/**
+ * Creates an adapter bound to a runtime context.
+ *
+ * A factory rather than a module-level singleton because the API key is not a
+ * process constant: routes/keys.ts updates ctx.atlasCloudApiKey while the
+ * server runs, so reading process.env would report the lane as unauthenticated
+ * right after the user configured it.
+ */
+export function createAtlasCloudAdapter(ctx) {
+    return {
+        laneId: LANE_ID,
+        validateAuth() {
+            // Presence only, and note the spelling: the context field is
+            // atlasCloudApiKey (capital C) while the lane id is all-lowercase.
+            return ctx.atlasCloudApiKey
+                ? { ok: true }
+                : { ok: false, reason: "Atlas Cloud 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
+                    : "Atlas Cloud 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/index.js

@@ -1,6 +1,8 @@
+import { createAtlasCloudAdapter } from "./atlascloud.js";
 import { createMinimaxAdapter } from "./minimax.js";
 const ADAPTER_FACTORIES = {
     minimax: createMinimaxAdapter,
+    atlascloud: createAtlasCloudAdapter,
 };
 export function getProviderAdapter(ctx, laneId) {
     const factory = ADAPTER_FACTORIES[laneId];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -119,5 +119,5 @@
     "tsx": "^4.23.12",
     "typescript": "^5.9.3"
   },
-  "gitHead": "ff8f95493fc2e2b5130223e6c63f55043d79fcfe"
+  "gitHead": "232bb540a0eb73e570d990d66ebe44be53df3bdf"
 }

package/routes/models.js

@@ -87,11 +87,24 @@ function geminiLane(ctx) {
     });
 }
 function atlasCloudLane(ctx) {
-    const state = ctx.atlasCloudApiKey
+    // #150 phase 2: Atlas Cloud is the second lane behind ProviderAdapterV1.
+    // The adapter owns auth state and the model list; the DTO projection stays
+    // here, so /api/models keeps its exact shape.
+    const adapter = getProviderAdapter(ctx, "atlascloud");
+    if (!adapter) {
+        const fallback = ctx.atlasCloudApiKey
+            ? { status: "ready" }
+            : { status: "key-missing", reason: "Atlas Cloud API key missing" };
+        return lane(fallback, { image: ATLASCLOUD_TEXT_TO_IMAGE_MODEL }, {
+            image: entries(deriveModels("atlascloud", "image")), video: [],
+        });
+    }
+    const auth = adapter.validateAuth();
+    const state = auth.ok
         ? { status: "ready" }
-        : { status: "key-missing", reason: "Atlas Cloud API key missing" };
+        : { status: "key-missing", reason: auth.reason ?? "Atlas Cloud API key missing" };
     return lane(state, { image: ATLASCLOUD_TEXT_TO_IMAGE_MODEL }, {
-        image: entries(deriveModels("atlascloud", "image")), video: [],
+        image: entries(adapter.listModels().map((model) => model.id)), video: [],
     });
 }
 function minimaxLane(ctx) {

package/routes/video.js

@@ -38,7 +38,9 @@ function sendSse(res, event, data) {
 function dualEmitVideo(res, requestId, event, data) {
     if (!res.writableEnded)
         sendSse(res, event, data);
-    if (event === "done") {
+    if (event === "done" || event === "error") {
+        // #151 stage 2: terminal events (done AND error) carry the canonical
+        // envelope. Stream events (progress/phase/partial) stay on raw publish.
         publishJobEvent(requestId, event, data);
     }
     else {
@@ -124,7 +126,8 @@ export function registerVideoRoutes(app, ctxRaw) {
             finishHttpStatus = httpStatus;
             finishErrorCode = code;
             const payload = { error, code, status: httpStatus, requestId, ...extra };
-            publish(requestId, "error", payload);
+            // #151 stage 2: terminal failure carries the canonical envelope.
+            publishJobEvent(requestId, "error", payload);
             if (asyncMode && !res.headersSent) {
                 return res.status(httpStatus).json(payload);
             }

package/routes/videoExtended.js

@@ -248,7 +248,8 @@ export function registerVideoExtendedRoutes(app, ctxRaw, dependencies = {}) {
             const status = info.status ?? 500;
             const code = info.code ?? "VIDEO_EXTEND_FAILED";
             const payload = { requestId, error: info.message, code, status, ...retryableData(error), ...errorEnvelopeFields(error) };
-            publish(requestId, "error", payload);
+            // #151 stage 2: terminal failure carries the canonical envelope.
+            publishJobEvent(requestId, "error", payload);
             finishJob(requestId, { status: "error", httpStatus: status, errorCode: code, meta: { stage: "preflight" } });
             if (!res.headersSent)
                 res.status(status).json(payload);
@@ -369,7 +370,8 @@ export function registerVideoExtendedRoutes(app, ctxRaw, dependencies = {}) {
             catch (error) {
                 if (!isJobCanceled(requestId)) {
                     const info = errInfo(error);
-                    publish(requestId, "error", { requestId, error: info.message, code: info.code ?? "VIDEO_EXTEND_FAILED", status: info.status ?? 500, ...retryableData(error), ...errorEnvelopeFields(error) });
+                    // #151 stage 2: terminal failure carries the canonical envelope.
+                    publishJobEvent(requestId, "error", { requestId, error: info.message, code: info.code ?? "VIDEO_EXTEND_FAILED", status: info.status ?? 500, ...retryableData(error), ...errorEnvelopeFields(error) });
                     finishJob(requestId, { status: "error", httpStatus: info.status ?? 500, errorCode: info.code ?? "VIDEO_EXTEND_FAILED", meta: { stage } });
                 }
             }

package/ui/dist/.vite/manifest.json

@@ -1,11 +1,15 @@
 {
-  "_AssetGenWorkspace-D-p57I-0.js": {
-    "file": "assets/AssetGenWorkspace-D-p57I-0.js",
+  "_AssetGenWorkspace-Dkr80l12.css": {
+    "file": "assets/AssetGenWorkspace-Dkr80l12.css",
+    "src": "_AssetGenWorkspace-Dkr80l12.css"
+  },
+  "_AssetGenWorkspace-XbViHOY0.js": {
+    "file": "assets/AssetGenWorkspace-XbViHOY0.js",
     "name": "AssetGenWorkspace",
     "isDynamicEntry": true,
     "imports": [
       "index.html",
-      "_KeyingPanel-hK4oc51k.js"
+      "_KeyingPanel-D79TCHH_.js"
     ],
     "dynamicImports": [
       "src/components/assetgen/SpriteRecipeWorkspace.tsx"
@@ -14,16 +18,12 @@
       "assets/AssetGenWorkspace-Dkr80l12.css"
     ]
   },
-  "_AssetGenWorkspace-Dkr80l12.css": {
-    "file": "assets/AssetGenWorkspace-Dkr80l12.css",
-    "src": "_AssetGenWorkspace-Dkr80l12.css"
-  },
-  "_KeyingPanel-hK4oc51k.js": {
-    "file": "assets/KeyingPanel-hK4oc51k.js",
+  "_KeyingPanel-D79TCHH_.js": {
+    "file": "assets/KeyingPanel-D79TCHH_.js",
     "name": "KeyingPanel",
     "imports": [
       "index.html",
-      "_useAgentDialogFocus-C1ZNYO-9.js"
+      "_useAgentDialogFocus-BOGEpRNF.js"
     ]
   },
   "__vite-browser-external": {
@@ -32,15 +32,15 @@
     "src": "__vite-browser-external",
     "isDynamicEntry": true
   },
-  "_useAgentDialogFocus-C1ZNYO-9.js": {
-    "file": "assets/useAgentDialogFocus-C1ZNYO-9.js",
+  "_useAgentDialogFocus-BOGEpRNF.js": {
+    "file": "assets/useAgentDialogFocus-BOGEpRNF.js",
     "name": "useAgentDialogFocus",
     "imports": [
       "index.html"
     ]
   },
   "index.html": {
-    "file": "assets/index-znBY56O9.js",
+    "file": "assets/index-DoM1FoZ5.js",
     "name": "index",
     "src": "index.html",
     "isEntry": true,
@@ -55,7 +55,7 @@
       "src/components/card-news/CardNewsWorkspace.tsx",
       "src/components/agent/AgentWorkspace.tsx",
       "src/components/assets/AssetsWorkspace.tsx",
-      "_AssetGenWorkspace-D-p57I-0.js",
+      "_AssetGenWorkspace-XbViHOY0.js",
       "src/components/home/HomeWorkspace.tsx",
       "src/components/PromptLibraryPanel.tsx"
     ],
@@ -64,7 +64,7 @@
     ]
   },
   "node_modules/pptxgenjs/dist/pptxgen.es.js": {
-    "file": "assets/pptxgen.es-C5xOqzMQ.js",
+    "file": "assets/pptxgen.es-DlpIDw00.js",
     "name": "pptxgen.es",
     "src": "node_modules/pptxgenjs/dist/pptxgen.es.js",
     "isDynamicEntry": true,
@@ -78,7 +78,7 @@
     ]
   },
   "src/components/GenerationRequestLogPanel.tsx": {
-    "file": "assets/GenerationRequestLogPanel-CJYn7vCN.js",
+    "file": "assets/GenerationRequestLogPanel-CKw9JLH8.js",
     "name": "GenerationRequestLogPanel",
     "src": "src/components/GenerationRequestLogPanel.tsx",
     "isDynamicEntry": true,
@@ -87,7 +87,7 @@
     ]
   },
   "src/components/NodeCanvas.tsx": {
-    "file": "assets/NodeCanvas-CO9FzAfn.js",
+    "file": "assets/NodeCanvas-BpNgtUxt.js",
     "name": "NodeCanvas",
     "src": "src/components/NodeCanvas.tsx",
     "isDynamicEntry": true,
@@ -99,7 +99,7 @@
     ]
   },
   "src/components/PromptImportDialog.tsx": {
-    "file": "assets/PromptImportDialog-CGxyjU6L.js",
+    "file": "assets/PromptImportDialog-qD_tVhN5.js",
     "name": "PromptImportDialog",
     "src": "src/components/PromptImportDialog.tsx",
     "isDynamicEntry": true,
@@ -112,7 +112,7 @@
     ]
   },
   "src/components/PromptImportDiscoverySection.tsx": {
-    "file": "assets/PromptImportDiscoverySection-C5PY1YV3.js",
+    "file": "assets/PromptImportDiscoverySection-51FDzoLN.js",
     "name": "PromptImportDiscoverySection",
     "src": "src/components/PromptImportDiscoverySection.tsx",
     "isDynamicEntry": true,
@@ -121,7 +121,7 @@
     ]
   },
   "src/components/PromptImportFolderSection.tsx": {
-    "file": "assets/PromptImportFolderSection-DWsWg6nw.js",
+    "file": "assets/PromptImportFolderSection-uQNX1sJ_.js",
     "name": "PromptImportFolderSection",
     "src": "src/components/PromptImportFolderSection.tsx",
     "isDynamicEntry": true,
@@ -130,7 +130,7 @@
     ]
   },
   "src/components/PromptLibraryPanel.tsx": {
-    "file": "assets/PromptLibraryPanel-BPiKLU-z.js",
+    "file": "assets/PromptLibraryPanel-BngHherb.js",
     "name": "PromptLibraryPanel",
     "src": "src/components/PromptLibraryPanel.tsx",
     "isDynamicEntry": true,
@@ -142,7 +142,7 @@
     ]
   },
   "src/components/SettingsWorkspace.tsx": {
-    "file": "assets/SettingsWorkspace-D1gLUIPQ.js",
+    "file": "assets/SettingsWorkspace-dpl5CLsg.js",
     "name": "SettingsWorkspace",
     "src": "src/components/SettingsWorkspace.tsx",
     "isDynamicEntry": true,
@@ -151,43 +151,43 @@
     ]
   },
   "src/components/agent/AgentWorkspace.tsx": {
-    "file": "assets/AgentWorkspace-BZuw_82p.js",
+    "file": "assets/AgentWorkspace-Bfe9PqZy.js",
     "name": "AgentWorkspace",
     "src": "src/components/agent/AgentWorkspace.tsx",
     "isDynamicEntry": true,
     "imports": [
       "index.html",
-      "_useAgentDialogFocus-C1ZNYO-9.js"
+      "_useAgentDialogFocus-BOGEpRNF.js"
     ]
   },
   "src/components/assetgen/SpriteRecipeWorkspace.tsx": {
-    "file": "assets/SpriteRecipeWorkspace-vlnp398m.js",
+    "file": "assets/SpriteRecipeWorkspace-IpS6TVAF.js",
     "name": "SpriteRecipeWorkspace",
     "src": "src/components/assetgen/SpriteRecipeWorkspace.tsx",
     "isDynamicEntry": true,
     "imports": [
       "index.html",
-      "_AssetGenWorkspace-D-p57I-0.js",
-      "_KeyingPanel-hK4oc51k.js",
-      "_useAgentDialogFocus-C1ZNYO-9.js"
+      "_AssetGenWorkspace-XbViHOY0.js",
+      "_KeyingPanel-D79TCHH_.js",
+      "_useAgentDialogFocus-BOGEpRNF.js"
     ]
   },
   "src/components/assets/AssetsWorkspace.tsx": {
-    "file": "assets/AssetsWorkspace-BlVr5Qjq.js",
+    "file": "assets/AssetsWorkspace-HemkY-0A.js",
     "name": "AssetsWorkspace",
     "src": "src/components/assets/AssetsWorkspace.tsx",
     "isDynamicEntry": true,
     "imports": [
       "index.html",
-      "_KeyingPanel-hK4oc51k.js",
-      "_useAgentDialogFocus-C1ZNYO-9.js"
+      "_KeyingPanel-D79TCHH_.js",
+      "_useAgentDialogFocus-BOGEpRNF.js"
     ],
     "css": [
       "assets/AssetsWorkspace-BkUjPPKU.css"
     ]
   },
   "src/components/canvas-mode/index.ts": {
-    "file": "assets/index-DogXlrkz.js",
+    "file": "assets/index-BA51BzWd.js",
     "name": "index",
     "src": "src/components/canvas-mode/index.ts",
     "isDynamicEntry": true,
@@ -199,7 +199,7 @@
     ]
   },
   "src/components/card-news/CardNewsWorkspace.tsx": {
-    "file": "assets/CardNewsWorkspace-BPYWHZqh.js",
+    "file": "assets/CardNewsWorkspace-Cchcm8ts.js",
     "name": "CardNewsWorkspace",
     "src": "src/components/card-news/CardNewsWorkspace.tsx",
     "isDynamicEntry": true,
@@ -208,7 +208,7 @@
     ]
   },
   "src/components/home/HomeWorkspace.tsx": {
-    "file": "assets/HomeWorkspace-DbWuQI7B.js",
+    "file": "assets/HomeWorkspace-Do6VnjWR.js",
     "name": "HomeWorkspace",
     "src": "src/components/home/HomeWorkspace.tsx",
     "isDynamicEntry": true,
@@ -217,7 +217,7 @@
     ]
   },
   "src/components/prompt-builder/PromptBuilderPanel.tsx": {
-    "file": "assets/PromptBuilderPanel-DEPrkXcU.js",
+    "file": "assets/PromptBuilderPanel-DHB1sU7O.js",
     "name": "PromptBuilderPanel",
     "src": "src/components/prompt-builder/PromptBuilderPanel.tsx",
     "isDynamicEntry": true,