ima2-gen 3.21.0 → 3.22.0

package/bin/commands/grok.js

@@ -113,7 +113,14 @@ async function loginViaServer(base) {
     const deadline = Date.now() + start.expiresIn * 1000;
     while (Date.now() < deadline) {
         await sleep(POLL_INTERVAL_MS);
-        const poll = await request(base, `/api/auth/switch/${encodeURIComponent(start.sessionId)}`);
+        // A 404 means the session is gone (server restarted or reaped it): report it as the
+        // expired login it is, not as a bare HTTP status the user cannot act on.
+        const poll = await request(base, `/api/auth/switch/${encodeURIComponent(start.sessionId)}`)
+            .catch((error) => {
+            if (error.status === 404)
+                return { status: "expired" };
+            throw error;
+        });
         if (poll.status === "complete")
             return;
         if (poll.status === "error")

package/docs/API.md

@@ -1266,13 +1266,16 @@ Async: `202 { requestId, provider }`; lifecycle events on `/api/events`.
 Results commit with `workflow: "video.multishot"` and `mcpParameters`.
 
 Re-download a remote-succeeded MCP task into the generated library. Body:
-`{ provider?: "runway", kind?: "video"|"image" }`. Use after a generation's
+`{ provider?: "runway", kind?: "video"|"image", requestId? }`. Use after a generation's
 download/commit step failed transiently — provider assets stay fetchable for
 ~24-48h. Re-polls `get_task`, requires `SUCCEEDED` with an output URL
 (`error` SSE event with `MCP_TASK_NOT_SUCCEEDED` otherwise), then runs the same
 download (with retry + IPv4 fallback) → single-persistence commit path as a
 normal generation. Async: `202 { requestId, taskId }`; `done` carries
 `recovered: true`.
+`requestId` dedupes only while the job is still running — a retry with the
+same id returns `409 REQUEST_ID_IN_USE`, and once the job settles a new
+recover may reuse it (same scope as `/api/mcp/generate`).
 Catalog-only providers (e.g. Higgsfield on a free plan) return
 `409 MCP_EXECUTION_LOCKED`, same as `/api/mcp/generate`.
 

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: 513 (runtime: 233, contract: 280)
+Total: 518 (runtime: 234, contract: 284)
 
 ## Runtime-importing tests
 - `tests/advertise-payload-contract.test.ts`
@@ -185,8 +185,9 @@ Total: 513 (runtime: 233, contract: 280)
 - `tests/provider-registry-parity.test.ts`
 - `tests/provider-surface-boundary.test.ts`
 - `tests/provider-surface-support.test.ts`
+- `tests/quota-codex-session.test.ts`
 - `tests/reference-image-compress.test.ts`
-- `tests/reference-limits-node-recovery.test.mjs`
+- `tests/reference-limits-node-recovery.test.ts`
 - `tests/refs-size.test.ts`
 - `tests/request-logging.test.ts`
 - `tests/responses-adapter-safety.test.ts`
@@ -245,102 +246,105 @@ Total: 513 (runtime: 233, contract: 280)
 - `tests/a11y-modal-contract.test.ts`
 - `tests/a11y-touch-target-contract.test.ts`
 - `tests/action-pin-contract.test.ts`
-- `tests/agent-mode-frontend-contract.test.js`
-- `tests/agent-mode-layout-contract.test.js`
-- `tests/agent-mode-right-sidebar-contract.test.js`
+- `tests/agent-mode-frontend-contract.test.ts`
+- `tests/agent-mode-layout-contract.test.ts`
+- `tests/agent-mode-right-sidebar-contract.test.ts`
 - `tests/agent-mode-run-progress-contract.test.ts`
-- `tests/agent-mode-streaming-a11y-contract.test.js`
-- `tests/agent-mode-tool-call-rendering-contract.test.js`
-- `tests/agent-mode-tool-folding-contract.test.js`
+- `tests/agent-mode-streaming-a11y-contract.test.ts`
+- `tests/agent-mode-tool-call-rendering-contract.test.ts`
+- `tests/agent-mode-tool-folding-contract.test.ts`
 - `tests/agy-artifact-check-contract.test.ts`
 - `tests/agy-artifact-read-bounds.test.ts`
-- `tests/api-docs-contract.test.js`
-- `tests/app-weight-splitting-contract.test.js`
+- `tests/api-docs-contract.test.ts`
+- `tests/app-weight-splitting-contract.test.ts`
 - `tests/asset-element-toggle-contract.test.ts`
-- `tests/asset-gen-keying-preview-contract.test.js`
-- `tests/asset-gen-media-lightbox-contract.test.js`
+- `tests/asset-gen-keying-preview-contract.test.ts`
+- `tests/asset-gen-media-lightbox-contract.test.ts`
 - `tests/asset-preview-element-fallback.test.ts`
 - `tests/assets-element-library-contract.test.ts`
 - `tests/assets-star-rename-contract.test.ts`
 - `tests/assets-ui-store-contract.test.ts`
 - `tests/assets-workspace-polish-contract.test.ts`
 - `tests/async-capacity-retry-behavior.test.ts`
-- `tests/async-capacity-retry-contract.test.js`
-- `tests/async-stream-subscribe-order.test.js`
+- `tests/async-capacity-retry-contract.test.ts`
+- `tests/async-stream-subscribe-order.test.ts`
 - `tests/audit-gate-contract.test.ts`
-- `tests/backend-hardening-contract.test.js`
-- `tests/background-cleanup-brush-rasterize.test.js`
-- `tests/background-cleanup-mask-compose.test.js`
-- `tests/bin.test.js`
-- `tests/blank-canvas-size-contract.test.js`
-- `tests/browser-attention-badge-contract.test.js`
-- `tests/canvas-alpha-controls-contract.test.js`
-- `tests/canvas-annotation-contract.test.js`
-- `tests/canvas-annotation-revert-contract.test.js`
-- `tests/canvas-apply-merged-contract.test.js`
-- `tests/canvas-background-cleanup-2x2-contract.test.js`
-- `tests/canvas-background-cleanup-contract.test.js`
-- `tests/canvas-edit-mask-flow-contract.test.js`
-- `tests/canvas-eraser-contract.test.js`
-- `tests/canvas-export-contract.test.js`
-- `tests/canvas-history-contract.test.js`
-- `tests/canvas-hit-test-contract.test.js`
-- `tests/canvas-mask-contract.test.js`
-- `tests/canvas-memo-contract.test.js`
-- `tests/canvas-memo-prompt-contract.test.js`
-- `tests/canvas-mode-contract.test.js`
-- `tests/canvas-object-key-contract.test.js`
-- `tests/canvas-persistence-contract.test.js`
+- `tests/backend-hardening-contract.test.ts`
+- `tests/background-cleanup-brush-rasterize.test.ts`
+- `tests/background-cleanup-mask-compose.test.ts`
+- `tests/bin.test.ts`
+- `tests/blank-canvas-size-contract.test.ts`
+- `tests/browser-attention-badge-contract.test.ts`
+- `tests/canvas-alpha-controls-contract.test.ts`
+- `tests/canvas-annotation-contract.test.ts`
+- `tests/canvas-annotation-revert-contract.test.ts`
+- `tests/canvas-apply-merged-contract.test.ts`
+- `tests/canvas-background-cleanup-2x2-contract.test.ts`
+- `tests/canvas-background-cleanup-contract.test.ts`
+- `tests/canvas-edit-mask-flow-contract.test.ts`
+- `tests/canvas-eraser-contract.test.ts`
+- `tests/canvas-export-contract.test.ts`
+- `tests/canvas-history-contract.test.ts`
+- `tests/canvas-hit-test-contract.test.ts`
+- `tests/canvas-mask-contract.test.ts`
+- `tests/canvas-memo-contract.test.ts`
+- `tests/canvas-memo-prompt-contract.test.ts`
+- `tests/canvas-mode-contract.test.ts`
+- `tests/canvas-object-key-contract.test.ts`
+- `tests/canvas-persistence-contract.test.ts`
 - `tests/canvas-pptx-export-contract.test.ts`
-- `tests/canvas-selection-contract.test.js`
-- `tests/canvas-style-contract.test.js`
+- `tests/canvas-selection-contract.test.ts`
+- `tests/canvas-style-contract.test.ts`
 - `tests/canvas-svg-export-contract.test.ts`
 - `tests/canvas-vectorize-entry-contract.test.ts`
-- `tests/canvas-version-api.test.js`
-- `tests/canvas-version-contract.test.js`
-- `tests/canvas-viewport-pan-contract.test.js`
-- `tests/card-news-42-43-contract.test.js`
-- `tests/card-news-frontend-contract.test.js`
-- `tests/card-news-smoke.test.js`
+- `tests/canvas-version-api.test.ts`
+- `tests/canvas-version-contract.test.ts`
+- `tests/canvas-viewport-pan-contract.test.ts`
+- `tests/card-news-42-43-contract.test.ts`
+- `tests/card-news-frontend-contract.test.ts`
+- `tests/card-news-smoke.test.ts`
 - `tests/card-news-visible-text-language-contract.test.ts`
 - `tests/character-binding-ui-contract.test.ts`
 - `tests/ci-windows-candidate.test.ts`
-- `tests/cli-capabilities-contract.test.js`
-- `tests/cli-character-contract.test.js`
-- `tests/cli-commands.test.js`
-- `tests/cli-config-keys-contract.test.js`
-- `tests/cli-default-output-dir-contract.test.js`
-- `tests/cli-defaults-command-contract.test.js`
-- `tests/cli-destructive-safety-contract.test.js`
-- `tests/cli-doctor-status-contract.test.js`
-- `tests/cli-feature-parity-contract.test.js`
-- `tests/cli-help-safety-contract.test.js`
-- `tests/cli-output-recovery-contract.test.js`
-- `tests/cli-prompt-builder-contract.test.js`
-- `tests/cli-prompt-import-contract.test.js`
+- `tests/cli-capabilities-contract.test.ts`
+- `tests/cli-character-contract.test.ts`
+- `tests/cli-commands.test.ts`
+- `tests/cli-config-keys-contract.test.ts`
+- `tests/cli-default-output-dir-contract.test.ts`
+- `tests/cli-defaults-command-contract.test.ts`
+- `tests/cli-destructive-safety-contract.test.ts`
+- `tests/cli-doctor-status-contract.test.ts`
+- `tests/cli-feature-parity-contract.test.ts`
+- `tests/cli-grok-login.test.ts`
+- `tests/cli-help-safety-contract.test.ts`
+- `tests/cli-output-recovery-contract.test.ts`
+- `tests/cli-prompt-builder-contract.test.ts`
+- `tests/cli-prompt-import-contract.test.ts`
 - `tests/cli-session-graph.test.ts`
-- `tests/cli-skill-command-contract.test.js`
+- `tests/cli-skill-command-contract.test.ts`
 - `tests/cli-unknown-options.test.ts`
-- `tests/cli-upscale-contract.test.js`
-- `tests/cli-video-command-contract.test.js`
+- `tests/cli-upscale-contract.test.ts`
+- `tests/cli-video-command-contract.test.ts`
 - `tests/color-key.test.ts`
 - `tests/comfy-cli-contract.test.ts`
 - `tests/comfy-display.test.ts`
-- `tests/comfy-export-ui-contract.test.js`
+- `tests/comfy-export-ui-contract.test.ts`
 - `tests/comfy-ui-contract.test.ts`
-- `tests/comfyui-custom-node-contract.test.js`
-- `tests/composer-feedback-contract.test.js`
-- `tests/composer-mention-parity-contract.test.js`
-- `tests/composer-tray-ui-contract.test.js`
-- `tests/config.test.js`
+- `tests/comfyui-custom-node-contract.test.ts`
+- `tests/composer-feedback-contract.test.ts`
+- `tests/composer-mention-parity-contract.test.ts`
+- `tests/composer-tray-ui-contract.test.ts`
+- `tests/config.test.ts`
 - `tests/contract-docs-projection.test.ts`
 - `tests/core-generation-mode.test.ts`
 - `tests/core-selection-actions.test.ts`
 - `tests/core-selection-memory.test.ts`
 - `tests/core-selection-reconcile.test.ts`
-- `tests/core-selection-transport.test.mjs`
-- `tests/current-image-actions-readiness-contract.test.js`
+- `tests/core-selection-transport.test.ts`
+- `tests/current-image-actions-readiness-contract.test.ts`
 - `tests/desktop-app-lifecycle.test.ts`
+- `tests/desktop-context-menu.test.ts`
+- `tests/desktop-edit-menu.test.ts`
 - `tests/desktop-mac-verification.test.ts`
 - `tests/desktop-release-assets.test.ts`
 - `tests/desktop-release-contract.test.ts`
@@ -349,159 +353,160 @@ Total: 513 (runtime: 233, contract: 280)
 - `tests/desktop-signing-policy.test.ts`
 - `tests/desktop-tray.test.ts`
 - `tests/desktop-updater.test.ts`
-- `tests/direct-mode-visual-contract.test.js`
+- `tests/desktop-window-open.test.ts`
+- `tests/direct-mode-visual-contract.test.ts`
 - `tests/dropped-media-sorting-contract.test.ts`
-- `tests/duration-slider-contract.test.js`
+- `tests/duration-slider-contract.test.ts`
 - `tests/e2e-app-environment.test.ts`
-- `tests/e2e-runtime-build.test.mjs`
-- `tests/e2e-runtime-guards.test.mjs`
-- `tests/edit-mask-api-contract.test.js`
-- `tests/element-mention-ui-contract.test.js`
+- `tests/e2e-runtime-build.test.ts`
+- `tests/e2e-runtime-guards.test.ts`
+- `tests/edit-mask-api-contract.test.ts`
+- `tests/element-mention-ui-contract.test.ts`
 - `tests/error-ui-consumption.test.ts`
 - `tests/event-channel-replay-gap.test.ts`
 - `tests/execution-network-isolation.test.ts`
 - `tests/execution-process-isolation.test.ts`
 - `tests/frame-extraction-fallback.test.ts`
 - `tests/frontend-connection-state-contract.test.ts`
-- `tests/frontend-sse-risk-contract.test.js`
+- `tests/frontend-sse-risk-contract.test.ts`
 - `tests/gallery-hang-regression-contract.test.ts`
-- `tests/gallery-load-older-contract.test.js`
-- `tests/gallery-navigation-ux-contract.test.js`
-- `tests/gallery-selection-during-generation-contract.test.js`
-- `tests/gallery-session-scope-contract.test.js`
-- `tests/gallery-shortcuts-behavior.test.js`
-- `tests/gallery-shortcuts-visible-domain-contract.test.js`
-- `tests/gallery-viewer-navigation-contract.test.js`
+- `tests/gallery-load-older-contract.test.ts`
+- `tests/gallery-navigation-ux-contract.test.ts`
+- `tests/gallery-selection-during-generation-contract.test.ts`
+- `tests/gallery-session-scope-contract.test.ts`
+- `tests/gallery-shortcuts-behavior.test.ts`
+- `tests/gallery-shortcuts-visible-domain-contract.test.ts`
+- `tests/gallery-viewer-navigation-contract.test.ts`
 - `tests/gemini-api-wire-contract.test.ts`
 - `tests/gemini-transport-parity.test.ts`
-- `tests/gen-output-path-contract.test.js`
-- `tests/generation-controls-ux-contract.test.js`
-- `tests/generation-limit-unlock-contract.test.js`
+- `tests/gen-output-path-contract.test.ts`
+- `tests/generation-controls-ux-contract.test.ts`
+- `tests/generation-limit-unlock-contract.test.ts`
 - `tests/governance-files-contract.test.ts`
-- `tests/health.test.js`
-- `tests/history-index-contract.test.js`
-- `tests/history-permanent-delete.test.js`
+- `tests/health.test.ts`
+- `tests/history-index-contract.test.ts`
+- `tests/history-permanent-delete.test.ts`
 - `tests/history-strip-duplicate-contract.test.ts`
 - `tests/i18n-coverage-contract.test.ts`
 - `tests/i18n-dictionary-contract.test.ts`
-- `tests/image-metadata-ui-contract.test.js`
-- `tests/inflight-badge-popup-contract.test.js`
-- `tests/inflight-cancel-contract.test.js`
-- `tests/inflight-list-tooltip-contract.test.js`
-- `tests/inflight-popup-polish-contract.test.js`
+- `tests/image-metadata-ui-contract.test.ts`
+- `tests/inflight-badge-popup-contract.test.ts`
+- `tests/inflight-cancel-contract.test.ts`
+- `tests/inflight-list-tooltip-contract.test.ts`
+- `tests/inflight-popup-polish-contract.test.ts`
 - `tests/inflight-reconciliation-behavior.test.ts`
 - `tests/inflight-reload-race.test.ts`
 - `tests/inflight-reload-reconcile-contract.test.ts`
 - `tests/install-runtime-contract.test.ts`
-- `tests/install-windows-contract.test.js`
-- `tests/issue75-prompt-studio-state-contract.test.js`
-- `tests/issue77-long-prompt-preview-contract.test.js`
-- `tests/j6-isolation-preflight.test.mjs`
+- `tests/install-windows-contract.test.ts`
+- `tests/issue75-prompt-studio-state-contract.test.ts`
+- `tests/issue77-long-prompt-preview-contract.test.ts`
+- `tests/j6-isolation-preflight.test.ts`
 - `tests/job-tracking-ci-contract.test.ts`
 - `tests/job-tracking-timeout-ui.test.ts`
 - `tests/lan-config.test.ts`
 - `tests/lane-catalog.test.ts`
 - `tests/mcp-media-kind-behavior.test.ts`
 - `tests/mcp-provider-smoke.test.ts`
-- `tests/mcp-provider-ui-contract.test.js`
+- `tests/mcp-provider-ui-contract.test.ts`
 - `tests/mcp-readiness-observation.test.ts`
 - `tests/mcp-readiness.test.ts`
 - `tests/mcp-schema-spike-contract.test.ts`
 - `tests/mcp-selection-helpers.test.ts`
 - `tests/mcp-settings-states-contract.test.ts`
 - `tests/minimax-ui-registration-contract.test.ts`
-- `tests/mobile-compose-sheet-accessibility-contract.test.js`
-- `tests/mobile-composer-tray-contract.test.js`
-- `tests/mobile-generate-entry-contract.test.js`
+- `tests/mobile-compose-sheet-accessibility-contract.test.ts`
+- `tests/mobile-composer-tray-contract.test.ts`
+- `tests/mobile-generate-entry-contract.test.ts`
 - `tests/model-select-lane-gating.test.ts`
-- `tests/multimode-backend-contract.test.js`
-- `tests/multimode-concurrent-store-contract.test.js`
-- `tests/multimode-ui-contract.test.js`
+- `tests/multimode-backend-contract.test.ts`
+- `tests/multimode-concurrent-store-contract.test.ts`
+- `tests/multimode-ui-contract.test.ts`
 - `tests/nai-cli-built-smoke.test.ts`
 - `tests/nai-dual-prompt-contract.test.ts`
 - `tests/nai-ui-registration-contract.test.ts`
 - `tests/navrail-hover-label-contract.test.ts`
-- `tests/node-async-eventbus-contract.test.js`
-- `tests/node-batch-contract.test.js`
+- `tests/node-async-eventbus-contract.test.ts`
+- `tests/node-batch-contract.test.ts`
 - `tests/node-batch-partial-contract.test.ts`
-- `tests/node-child-refs-contract.test.js`
-- `tests/node-child-refs-payload.test.js`
+- `tests/node-child-refs-contract.test.ts`
+- `tests/node-child-refs-payload.test.ts`
 - `tests/node-compatibility.test.ts`
-- `tests/node-context-policy.test.js`
+- `tests/node-context-policy.test.ts`
 - `tests/node-cycle-contract.test.ts`
-- `tests/node-diagnostics-contract.test.js`
-- `tests/node-edge-disconnect-contract.test.js`
+- `tests/node-diagnostics-contract.test.ts`
+- `tests/node-edge-disconnect-contract.test.ts`
 - `tests/node-error-info-contract.test.ts`
-- `tests/node-footer-compact-contract.test.js`
-- `tests/node-gallery-drop-contract.test.js`
-- `tests/node-generation-lock-contract.test.js`
+- `tests/node-footer-compact-contract.test.ts`
+- `tests/node-gallery-drop-contract.test.ts`
+- `tests/node-generation-lock-contract.test.ts`
 - `tests/node-history-contract.test.ts`
 - `tests/node-image-preview-contract.test.ts`
-- `tests/node-layout-contract.test.js`
+- `tests/node-layout-contract.test.ts`
 - `tests/node-multi-parent-ui.test.ts`
-- `tests/node-pending-recovery-contract.test.js`
-- `tests/node-regen-actions-contract.test.js`
-- `tests/node-session-evaporation-contract.test.js`
-- `tests/node-studio-ui-contract.test.js`
-- `tests/node-ui-contract.test.js`
+- `tests/node-pending-recovery-contract.test.ts`
+- `tests/node-regen-actions-contract.test.ts`
+- `tests/node-session-evaporation-contract.test.ts`
+- `tests/node-studio-ui-contract.test.ts`
+- `tests/node-ui-contract.test.ts`
 - `tests/oauth-image-lane-contract.test.ts`
-- `tests/oauth-masked-edit-contract.test.js`
-- `tests/oauth-proxy-edit-mask-contract.test.js`
+- `tests/oauth-masked-edit-contract.test.ts`
+- `tests/oauth-proxy-edit-mask-contract.test.ts`
 - `tests/package-global-update-smoke-contract.test.ts`
-- `tests/package-smoke.test.js`
+- `tests/package-smoke.test.ts`
 - `tests/pages-publication-contract.test.ts`
 - `tests/platform-open-url.test.ts`
-- `tests/png-info-contract.test.js`
+- `tests/png-info-contract.test.ts`
 - `tests/portal-dropdown-scroll-dismiss-contract.test.ts`
-- `tests/pr-fast-history.test.mjs`
+- `tests/pr-fast-history.test.ts`
 - `tests/pr-screenshot-gate.test.ts`
-- `tests/prompt-curated-search-contract.test.js`
-- `tests/prompt-discovery-ui-contract.test.js`
-- `tests/prompt-import-dialog-ui-contract.test.js`
-- `tests/prompt-import-folder-ui-contract.test.js`
-- `tests/prompt-import-search-ux-contract.test.js`
-- `tests/prompt-library-ui-contract.test.js`
-- `tests/prompt-studio-docs-contract.test.js`
-- `tests/prompt-studio-ui-contract.test.js`
+- `tests/prompt-curated-search-contract.test.ts`
+- `tests/prompt-discovery-ui-contract.test.ts`
+- `tests/prompt-import-dialog-ui-contract.test.ts`
+- `tests/prompt-import-folder-ui-contract.test.ts`
+- `tests/prompt-import-search-ux-contract.test.ts`
+- `tests/prompt-library-ui-contract.test.ts`
+- `tests/prompt-studio-docs-contract.test.ts`
+- `tests/prompt-studio-ui-contract.test.ts`
 - `tests/provenance-chip-contract.test.ts`
 - `tests/provider-canary-live-contract.test.ts`
 - `tests/provider-canary-parity.test.ts`
 - `tests/provider-execution-edit.test.ts`
 - `tests/provider-execution-harness.test.ts`
 - `tests/provider-execution-imports.test.ts`
-- `tests/provider-ui-polish-contract.test.js`
+- `tests/provider-ui-polish-contract.test.ts`
 - `tests/reference-limits.test.ts`
 - `tests/reference-tray-model.test.ts`
 - `tests/release-pipeline-contract.test.ts`
 - `tests/runtime-install-projection.test.ts`
 - `tests/selector-comfy-admission.test.ts`
-- `tests/server-fallback-contract.test.js`
-- `tests/server.test.js`
-- `tests/session-conflict.test.js`
+- `tests/server-fallback-contract.test.ts`
+- `tests/server.test.ts`
+- `tests/session-conflict.test.ts`
 - `tests/settings-i18n-state-contract.test.ts`
-- `tests/settings-persistence-contract.test.js`
-- `tests/settings-workspace-layout-contract.test.js`
-- `tests/size-custom-input-contract.test.js`
-- `tests/size-presets.test.js`
+- `tests/settings-persistence-contract.test.ts`
+- `tests/settings-workspace-layout-contract.test.ts`
+- `tests/size-custom-input-contract.test.ts`
+- `tests/size-presets.test.ts`
 - `tests/slash-command-menu-contract.test.ts`
 - `tests/soft-unmix.test.ts`
-- `tests/sprite-curator-ui-contract.test.js`
-- `tests/sprite-recipe-ui-contract.test.js`
+- `tests/sprite-curator-ui-contract.test.ts`
+- `tests/sprite-recipe-ui-contract.test.ts`
 - `tests/sprite-transform-contract.test.ts`
 - `tests/star-prompt-ui-contract.test.ts`
 - `tests/star-surface-controls-contract.test.ts`
-- `tests/storage-open-generated-dir.test.js`
-- `tests/structure-line-counts-contract.test.js`
+- `tests/storage-open-generated-dir.test.ts`
+- `tests/structure-line-counts-contract.test.ts`
 - `tests/studio-surface-docs-contract.test.ts`
-- `tests/style-feature-removal-contract.test.js`
+- `tests/style-feature-removal-contract.test.ts`
 - `tests/subprocess-deadline-contract.test.ts`
 - `tests/test-runner-invocation.test.ts`
-- `tests/toast-stack-contract.test.js`
+- `tests/toast-stack-contract.test.ts`
 - `tests/tools-cli-contract.test.ts`
-- `tests/transparent-background-ui-contract.test.js`
-- `tests/ui-build-receipt-inventory.test.mjs`
-- `tests/ui-build-receipt-transaction.test.mjs`
-- `tests/ui-build-receipt.test.mjs`
+- `tests/transparent-background-ui-contract.test.ts`
+- `tests/ui-build-receipt-inventory.test.ts`
+- `tests/ui-build-receipt-transaction.test.ts`
+- `tests/ui-build-receipt.test.ts`
 - `tests/ui-color-token-contract.test.ts`
 - `tests/ui-error-code-contract.test.ts`
 - `tests/ui-glyph-policy.test.ts`
@@ -511,14 +516,14 @@ Total: 513 (runtime: 233, contract: 280)
 - `tests/ui-typography-rules-contract.test.ts`
 - `tests/vectorize-cli-contract.test.ts`
 - `tests/vectorize-panel-contract.test.ts`
-- `tests/video-continuity-ui-contract.test.js`
-- `tests/video-defaults-persistence-contract.test.js`
+- `tests/video-continuity-ui-contract.test.ts`
+- `tests/video-defaults-persistence-contract.test.ts`
 - `tests/video-edit-client-contract.test.ts`
-- `tests/video-extend-ui-contract.test.js`
-- `tests/video-frame-local-file.test.js`
+- `tests/video-extend-ui-contract.test.ts`
+- `tests/video-frame-local-file.test.ts`
 - `tests/video-gallery-refresh-contract.test.ts`
-- `tests/video-inflight-kind-contract.test.js`
+- `tests/video-inflight-kind-contract.test.ts`
 - `tests/video-ui-source-count.test.ts`
-- `tests/vite-dev-port-contract.test.js`
+- `tests/vite-dev-port-contract.test.ts`
 - `tests/wand-erase.test.ts`
-- `tests/web-search-toggle-contract.test.js`
+- `tests/web-search-toggle-contract.test.ts`

package/lib/grokSizeMapper.js

@@ -12,6 +12,8 @@ const SUPPORTED_ASPECTS = [
     "9:19.5",
     "20:9",
     "9:20",
+    "21:9",
+    "5:2",
 ];
 const PRESET_MAP = {
     "1024x1024": { aspect_ratio: "1:1", resolution: "1k" },

package/lib/mcp/adapters/higgsfield.js

@@ -6,7 +6,9 @@
 // - Poll tool is `job_status({ jobId })` (uuid), NOT `get_task`.
 // - `job_status` supports `sync: true` (~25s server-side wait) to reduce churn.
 // - `generate_video`/`generate_image` take `medias[].value` as media_id/job_id
-//   via `media_import_url` / `media_upload_widget`, never raw URLs.
+//   via `media_upload` + `media_confirm` / `media_import_url`, never raw URLs,
+//   and `medias[].role` names the provider-declared role (image|start_image|
+//   end_image per models_explore — not the runway-style canonical names).
 // - Status enum: pending|waiting|queued|in_progress|ip_detect|completed|failed|canceled|nsfw|ip_detected
 // - Output URL lives at `generation.results.rawUrl`.
 //
@@ -58,6 +60,7 @@ export const HIGGSFIELD_VIDEO_MODELS = [
 ];
 const DEFAULT_MODEL = { image: "soul_2", video: "cinematic_studio_3_0" };
 const TASK_ID_PATTERN = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+const FORWARDED_PARAM_KEYS = new Set(["resolution", "quality", "count", "use_unlim"]);
 function buildGenerateCall(request) {
     const model = request.model ?? DEFAULT_MODEL[request.kind];
     // 260723: the web app sends `use_unlim: true` on every generation (captured
@@ -75,27 +78,31 @@ function buildGenerateCall(request) {
     }
     // Provider-declared scalar knobs (models catalog): resolution (nano_banana),
     // quality (soul), count. Only whitelisted keys are forwarded.
-    const FORWARDED_PARAM_KEYS = new Set(["resolution", "quality", "count", "use_unlim"]);
     for (const [key, value] of Object.entries(request.parameters ?? {})) {
         if (FORWARDED_PARAM_KEYS.has(key))
             params[key] = value;
     }
-    // Reference images: Higgsfield requires media_id (from media_import_url),
-    // not raw URLs. The MCP media pipeline handles upload before calling here,
-    // so referenceImages[].url should already be a provider-hosted media_id or
-    // a public HTTPS URL that the server can auto-import.
+    // medias[].value must be a provider media_id (local uploads go through
+    // media_upload + media_confirm; https inputs through media_import_url).
+    // medias[].role must be a provider-declared role name — start_image /
+    // end_image / image. Every media slot in models_explore is type:"image";
+    // no higgsfield model declares a video-input role.
     const medias = [];
     if (request.startFrameUrl) {
-        medias.push({ value: request.startFrameUrl, role: "start_frame" });
+        medias.push({ value: request.startFrameUrl, role: "start_image" });
     }
     if (request.endFrameUrl) {
-        medias.push({ value: request.endFrameUrl, role: "end_frame" });
+        if (!request.startFrameUrl)
+            throw new Error(`MCP_END_FRAME_REQUIRES_START:${model}`);
+        medias.push({ value: request.endFrameUrl, role: "end_image" });
     }
     for (const ref of request.referenceImages ?? []) {
-        medias.push({ value: ref.url, role: ref.tag || "reference" });
+        medias.push({ value: ref.url, role: "image" });
     }
     if (request.referenceVideoUrl) {
-        medias.push({ value: request.referenceVideoUrl, role: "video_reference" });
+        // Undeclared roles would either be dropped silently or fail the whole job
+        // provider-side; forward a video role once models_explore declares one.
+        throw new Error(`MCP_INPUT_ROLE_UNSUPPORTED:${model}:video_references`);
     }
     if (medias.length > 0)
         params.medias = medias;

package/lib/mcp/adapters/higgsfieldUpload.js

@@ -0,0 +1,77 @@
+// Higgsfield media inputs (260925 audit): local files go media_upload ->
+// presigned PUT -> media_confirm; public https inputs go media_import_url.
+// Both produce the media_id that generate_*'s medias[].value requires —
+// higgsfield never accepts raw URLs or runway-hosted assets.
+import { readFile } from "node:fs/promises";
+import { assertPublicHttps } from "../downloadMediaResult.js";
+function structuredOf(result) {
+    const value = result.structuredContent;
+    return value && typeof value === "object" ? value : {};
+}
+function mediaTypeFor(mimeType) {
+    if (mimeType.startsWith("video/"))
+        return "video";
+    if (mimeType.startsWith("audio/"))
+        return "audio";
+    return "image";
+}
+function providerError(result) {
+    const error = structuredOf(result).error;
+    return typeof error === "string" && error ? error.slice(0, 120) : null;
+}
+/** Upload a validated local file; returns the higgsfield media_id for medias[].value. */
+export async function uploadLocalMediaToHiggsfield(manager, filePath, options) {
+    const bytes = await readFile(filePath);
+    if (bytes.byteLength === 0)
+        throw new Error("MCP_UPLOAD_EMPTY");
+    if (bytes.byteLength > (options.maxBytes ?? 100 * 1024 * 1024))
+        throw new Error("MCP_UPLOAD_TOO_LARGE");
+    const type = mediaTypeFor(options.mimeType);
+    const init = await manager.callTool("higgsfield", "media_upload", {
+        filename: options.fileName,
+        content_type: options.mimeType,
+    });
+    const uploads = structuredOf(init).uploads;
+    const slot = Array.isArray(uploads) ? uploads[0] : undefined;
+    const uploadUrl = typeof slot?.upload_url === "string" ? slot.upload_url : null;
+    const mediaId = typeof slot?.media_id === "string" ? slot.media_id : null;
+    if (!uploadUrl || !mediaId) {
+        const detail = providerError(init);
+        throw new Error(`MCP_UPLOAD_INIT_INVALID${detail ? `:${detail}` : ""}`);
+    }
+    // Same public-HTTPS/IP validation as downloads — hostile MCP output must not
+    // redirect local media elsewhere.
+    const target = new URL(uploadUrl);
+    await assertPublicHttps(target);
+    const response = await fetch(target, {
+        method: "PUT",
+        redirect: "error",
+        body: bytes,
+        headers: { "content-type": options.mimeType, "content-length": String(bytes.byteLength) },
+        signal: AbortSignal.timeout(180_000),
+    });
+    if (!response.ok)
+        throw new Error(`MCP_UPLOAD_PUT_FAILED:${response.status}`);
+    const confirmed = await manager.callTool("higgsfield", "media_confirm", { type, media_id: mediaId });
+    const confirmError = providerError(confirmed);
+    if (confirmError)
+        throw new Error(`MCP_UPLOAD_CONFIRM_FAILED:${confirmError}`);
+    const results = structuredOf(confirmed).results;
+    const confirmedId = Array.isArray(results)
+        ? results[0]?.media_id
+        : undefined;
+    if (typeof confirmedId !== "string" || !confirmedId)
+        throw new Error("MCP_UPLOAD_CONFIRM_INVALID");
+    return confirmedId;
+}
+/** Import a public https URL into a higgsfield media_id via media_import_url. */
+export async function importUrlToHiggsfield(manager, url, type) {
+    const result = await manager.callTool("higgsfield", "media_import_url", { url, type });
+    const detail = providerError(result);
+    if (detail)
+        throw new Error(`MCP_IMPORT_URL_FAILED:${detail}`);
+    const mediaId = structuredOf(result).media_id;
+    if (typeof mediaId !== "string" || !mediaId)
+        throw new Error("MCP_IMPORT_URL_INVALID");
+    return mediaId;
+}