Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { getRunwayModelCatalog } from '../services/runwayModelCatalog.js';
import { assertCatalogIdentityWritable } from '../services/catalogDB/identityAccess.js';
/**
* Image Generation Routes — works against the external SD API, local mflux,
* or the Codex CLI built-in image_gen tool, depending on settings.imageGen.mode
* (or the per-request `mode` override).
*
* Generic endpoints (status, generate, avatar) go through the dispatcher.
* Async-mode endpoints (events SSE, cancel) also go through the dispatcher
* which routes the jobId to whichever provider owns it. Local-only endpoints
* (gallery, loras, models, delete) target the local module directly.
*/
import { createImageGalleryHandlers } from './imageGalleryRead.js';
import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler, ServerError, failValidation } from '../lib/errorHandler.js';
import {
validateRequest, modelDownloadQuerySchema, modelDownloadParamsSchema, imageCancelBodySchema, imageVisibilityBodySchema, imageEdgeSchema, refineImagePixelCap, PIXEL_CAP_MESSAGE,
} from '../lib/validation.js';
import { optionalUploadFields, optionalUpload } from '../lib/multipart.js';
import * as imageGen from '../services/imageGen/index.js';
import { local, IMAGE_GEN_MODE, IMAGE_GEN_MODES } from '../services/imageGen/index.js';
import { maxInputImages, resolveCloudProviderConfig } from '../services/imageGen/cloudProviderConfig.js';
import setupRouter, { streamMossAction } from './imageGenSetup.js';
import { usesMossSwift } from '../lib/imageRuntimeRemedies.js';
import { downloadMossWeights, mossModelCacheStatus, verifyMossWeights, repairMossWeights } from '../services/imageGen/mossWeights.js';
import { enqueueJob, attachSseClient as attachQueueSseClient, cancelJob, listJobs } from '../services/mediaJobQueue/index.js';
import { recordUserAction } from '../services/userActions.js';
import { getImageModels, requiredReposForModel } from '../lib/mediaModels.js';
import { inspectModelCache, verifyModelCache, repairModelCache, aggregateVerifies } from '../lib/hfCache.js';
import { startHfDownloadStream } from '../services/hfDownloadStream.js';
import { PATHS, ensureDir, resolveGalleryImage, unlinkGuarded, copyFileGuarded } from '../lib/fileUtils.js';
import { prepareGenerateParams, resolveLocalImageModel, selectLocalImageModelFromSettings } from '../services/imageGen/prepareParams.js';
import { applyImageClean, applyWatermarkRemoval, applyLightRegenVariant } from '../services/imageGen/variants.js';
import { applyFilmLookBake } from '../services/imageGen/filmLookBake.js';
import { previewImagePrompt } from '../services/imageGen/promptPreview.js';
import { filmLookBakeSchema } from '../lib/filmLookValidation.js';
import { join, basename } from 'node:path';
import { STYLE_PRESETS } from '../lib/writersRoomStylePresets.js';
import {
resolveRegenBackend, getRegenAvailability, readImageDimensions, buildRegenParams,
REGEN_STRENGTH_MIN, REGEN_STRENGTH_MAX,
resolveRegenStrengthDefault, REGEN_ANNOTATED_STRENGTH_DEFAULT,
} from '../services/imageGen/regen.js';
import { getSketchPngPath, isValidKey as isValidSketchKey } from '../services/mediaSketches.js';
import { itemKey } from '../lib/mediaItemKey.js';
import { deleteGalleryImage } from '../services/galleryImageDeletion.js';
import * as characterService from '../services/character.js';
import { randomUUID } from 'crypto';
import { buildUniverseRunTag } from '../services/universeRunTag.js';
import { getSettings } from '../services/settings.js';
import { prepareRemoteMediaJob } from '../services/federatedMedia/remoteSubmission.js';
import { collectRemoteInputAssets } from '../services/federatedMedia/inputAssets.js';
import { buildFederatedMediaRequest } from '../lib/federatedMediaRequest.js';
import { asFableLoomRenderSettings, inspectEpisodeProductionOrder } from '../lib/fableLoomProduction.js';
import { attachNodeImage, getLoom } from '../services/fableLoom/records.js';
import {
compileFableLoomVisualRequest, fableLoomImageCapabilities,
} from '../services/fableLoom/visualConditioning.js';
import { loraCompatKey } from '../lib/runners.js';
import { EFFORT_LEVELS } from '../lib/providerModels.js';
import { promptAdditionsSchema } from '../lib/modelInput.js';
const router = Router();
router.get('/runway-models', asyncHandler(async (_req, res) => {
res.json(await getRunwayModelCatalog());
}));
router.post('/runway-models/refresh', asyncHandler(async (_req, res) => {
res.json(await getRunwayModelCatalog({ refresh: true }));
}));
const routeSource = (req) => ({ route: `${req.baseUrl}${req.route?.path ?? ''}`, method: req.method });
// Event-only pointer: job id in `target`, never the generation prompt (#5596).
async function enqueueLoggedImage(req, job) {
// Selective section revision (#9011): checked as the LAST step before the
// actual queue write — every branch that reaches this helper has already
// done its own staging/provider resolution, so this is as close to the
// cancel/kickoff race as a request can get. A no-op when the tag carries no
// revisionId; deferred import since only this rare path needs the revision
// service's closure.
if (job.params?.musicVideo?.revisionId) {
const { assertRevisionOpen } = await import('../services/musicVideo/revisionService.js');
await assertRevisionOpen(job.params.musicVideo.projectId, job.params.musicVideo.revisionId, { sceneId: job.params.musicVideo.sceneId, kind: 'image' });
}
const queued = await enqueueJob(job);
try {
const happenedAt = new Date().toISOString();
await recordUserAction({
type: 'media.image.enqueue',
actor: 'user',
target: queued.jobId,
summary: 'enqueued image job',
payload: { jobId: queued.jobId },
source: routeSource(req),
happenedAt,
dedupeKey: `media.image.enqueue:${queued.jobId}`,
});
} catch (error) {
// Ledger is a side effect — the job is already queued.
console.error(`❌ Failed to record media.image.enqueue: ${error.message}`);
}
return queued;
}
// Shared validation limits. MAX_REFERENCE_IMAGES must stay in sync with the
// number of `referenceImageN` upload field names below.
const MAX_PROMPT_LENGTH = 32000;
const MAX_LORAS = 8;
const MAX_REFERENCE_IMAGES = 16;
const updatePromptSchema = z.object({ prompt: z.string().max(MAX_PROMPT_LENGTH) });
const galleryImageFilenameSchema = (label) => z.string().max(256)
.regex(/^[^/\\]+\.(png|jpg|jpeg|webp)$/i, `${label} must be a basename ending in png/jpg/jpeg/webp`);
router.get('/style-presets', (_req, res) => res.json(STYLE_PRESETS));
// Rejected, never stripped: model input is not silently modified. spawn() also throws on NUL.
const noNulPrompt = z.string().max(MAX_PROMPT_LENGTH)
.refine((v) => !v.includes('\0'), { message: 'Prompt may not contain a NUL character' });
const generateSchema = z.object({
promptAdditions: promptAdditionsSchema,
// Empty prompt allowed — i2i / edit / unconditional generation don't require
// one. The multipart FormData builder drops empty-string fields, so an empty
// prompt arrives as `undefined`; default it to '' rather than rejecting.
prompt: noNulPrompt.optional().default(''),
negativePrompt: noNulPrompt.optional(),
// Per-request backend override. If omitted, the dispatcher uses
// `imageGen.mode` from settings.json.
mode: z.enum(IMAGE_GEN_MODES).optional(),
modelId: z.string().max(64).optional(),
// Per-render Codex reasoning effort. Other image backends ignore this
// provider-specific preference, preserving the story pin across a backend
// switch without inventing a second image request shape.
effort: z.enum(EFFORT_LEVELS).optional(),
// Per-render override of a cloud CLI's session model, replacing the saved
// `settings.imageGen.<mode>.model` for this one queue item. Deliberately NOT
// `modelId`: that field carries a *local* model id (`dev`, `schnell`), and a
// form that keeps it populated while the user flips to a cloud backend would
// otherwise hand the CLI an id it rejects. Ignored by providers whose spec
// has no model knob (grok). Same charset as the provider-side MODEL_ID_RE so
// a typo'd id fails validation here rather than at spawn time.
cloudModel: z.string().max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/, 'invalid cloud model id').optional(),
width: imageEdgeSchema,
height: imageEdgeSchema,
steps: z.number().int().min(1).max(150).optional(),
cfgScale: z.number().min(0).max(30).optional(),
guidance: z.number().min(0).max(30).optional(),
seed: z.number().int().min(0).optional(),
// mflux supports 3/4/5/6/8 bit quantization; 8 is the default.
quantize: z.union([z.literal(3), z.literal(4), z.literal(5), z.literal(6), z.literal(8), z.literal('3'), z.literal('4'), z.literal('5'), z.literal('6'), z.literal('8')]).optional(),
// Filenames only (basenames) — server resolves against PATHS.loras and
// applies the prefix-check. Old payloads sent absolute server paths
// (`loraPaths`); accept both for back-compat with stored gallery sidecars.
loraFilenames: z.array(z.string().max(256).regex(/^[^/\\]+$/, 'lora filename must not contain path separators')).max(MAX_LORAS).optional(),
loraPaths: z.array(z.string().max(512)).max(MAX_LORAS).optional(),
loraScales: z.array(z.number().min(0).max(2)).max(MAX_LORAS).optional(),
// i2i: pick an existing gallery image (basename) as the init image. If
// initImage was uploaded via multipart, this is ignored in favor of the
// upload. Strength: 0.0 = ignore source, 1.0 = max influence.
initImageFile: galleryImageFilenameSchema('init image').optional(),
initImageStrength: z.number().min(0).max(1).optional(),
// Multi-reference image conditioning. Up to 4 reference images are uploaded
// as separate multipart fields `referenceImage1` … `referenceImage4`, or
// named from the existing gallery through JSON `referenceImageFiles`;
// `referenceStrengths` is a parallel array of weights (0.0 = ignore the
// reference, 1.0 = full influence), ordered as named files then uploads.
// Uploaded file presence is enforced at the upload layer, and the route
// pairs all surviving slots with their strengths positionally. Strengths are honored
// numerically only by local FLUX.2; the cloud CLIs expose no per-reference
// weight, so they receive the paths alone.
referenceImageFiles: z.array(galleryImageFilenameSchema('reference image')).max(MAX_REFERENCE_IMAGES).optional(),
referenceStrengths: z.array(z.number().min(0).max(1)).max(MAX_REFERENCE_IMAGES).optional(),
// Per-render override of the cleaners. When omitted, the route inherits
// from `settings.imageGen.{mode}.{cleanC2PA,denoise}`. Explicit booleans
// here force the value for this one render. Legacy `autoClean` is still
// accepted (mapped to both flags) so older clients keep working through
// the deprecation window.
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
autoClean: z.boolean().optional(),
// Optional universe-collection target. When present, the route resolves the
// universe's media collection server-side and tags the queued job so
// `universeBuilderCollectionHook` files the finished render into that
// collection — the same auto-filing path batch renders and character
// reference sheets use. The client passes only the universe identity (never
// a collectionId — that's server-resolved), so the front-end does no
// collection bookkeeping. The base-style probe (StyleProbeImage) and the
// Universe canon section-local renders (#1395) are the callers; JSON-only
// (the multipart ImageGen page never sends it).
universeRun: z.object({
universeId: z.string().min(1).max(200),
universeName: z.string().min(1).max(200),
label: z.string().max(200).optional(),
category: z.string().max(64).optional(),
// Section-local canon renders (#1395) tag the target entry so the
// completion hook durably appends the render to its `imageRefs[]` even
// after the originating page unmounts — converging these renders onto the
// same durable path batch renders use. Shape mirrors the batch path's
// entryRef (server/services/universeBuilder.js `ENTRY_REF_KIND`).
entryRef: z.object({
kind: z.enum(['canon', 'variation', 'sheet']),
kindKey: z.string().min(1).max(64).optional(),
categoryKey: z.string().min(1).max(64).optional(),
id: z.string().min(1).max(200),
}).refine(
// Each kind needs its locating key, else appendEntryImageRef silently
// no-ops: canon→kindKey, variation→categoryKey (sheet needs neither).
(r) => (r.kind === 'canon' ? !!r.kindKey : r.kind === 'variation' ? !!r.categoryKey : true),
{ message: 'entryRef requires its locating key (canon→kindKey, variation→categoryKey)' },
).optional(),
}).optional(),
// Writers-Room storyboard scene render (#1363). When present, the mediaJobQueue
// completion hook (`writersRoomSceneImageHook`) files the finished render onto
// the analysis snapshot's `sceneImages[sceneId]` AND mirrors it into the work's
// auto-collection — durably, even if the editor unmounted mid-render (the
// "navigated away → image never attached" failure mode the synchronous attach
// suffered). Only the async local/Codex lanes ride the queue this hook listens
// to; the synchronous external SD-API lane still attaches via the scene-image
// route. The scene prompt is read from the job's own `prompt` param, so the tag
// carries only the destination identity. JSON-only (the multipart ImageGen page
// never sends it).
writersRoom: z.object({
workId: z.string().min(1).max(200),
analysisId: z.string().min(1).max(200),
sceneId: z.string().min(1).max(200),
}).optional(),
// FableLoom scene render. When present, the mediaJobQueue completion hook
// (`fableLoomSceneImageHook`) files the finished render onto that loom
// episode's scene node — durably, even if the editor unmounted mid-render.
// Only the async local/Codex lanes ride the queue; the synchronous external
// SD-API lane is attached directly by this route after generation. Rides
// into job.params untouched via `...params`. JSON-only.
fableLoom: z.object({
loomId: z.string().min(1).max(200),
episodeId: z.string().min(1).max(200),
nodeId: z.string().min(1).max(200),
role: z.literal('image').optional(),
}).optional(),
// Music Video scene reference-frame render (#1760 Phase 1b). When present, the
// mediaJobQueue completion hook (`musicVideoSceneImageHook`) appends the
// finished render to the project scene's takes (#8965) — durably, even if the
// director board unmounted mid-render. Only the async local/Codex lanes ride
// the queue this hook listens to; the synchronous external SD-API lane returns
// the filename inline and the client adds it through the scene takes route. Rides
// into job.params untouched via `...params` (like `writersRoom`). JSON-only.
musicVideo: z.object({
projectId: z.string().min(1).max(200),
sceneId: z.string().min(1).max(200),
// Selective section revision (#9011): see the matching comment on the
// video route's musicVideo schema (server/routes/videoGen.js).
revisionId: z.string().min(1).max(200).optional(),
// #11173: 'end' files the render as the scene's style-break end frame
// (an `endImage` take) instead of its start frame.
slot: z.enum(['end']).optional(),
// #11317: the prompt is the director's text; the server composes the still's
// prompt and lists each block it adds. `fromFrame` reworks the first reference
// image (a picked frame); `refine` makes the prompt an edit instruction for it.
compose: z.boolean().optional(),
fromFrame: z.boolean().optional(),
refine: z.boolean().optional(),
}).optional(),
// File the render into this music video's media collection even when no shot
// keeps it (sheets, tests, alternates): musicVideoCollectionHook for the
// queued lanes, inline below for the synchronous one. Collection only; the
// render itself is unchanged.
musicVideoProjectId: z.string().min(1).max(200).optional(),
// Durable catalog attach (#1359). When present, the mediaJobQueue completion
// hook (catalogImageAttachHook) files the finished render onto this catalog
// ingredient even if the page that started the render has since unmounted —
// so a long queued local/Codex render is no longer lost to navigation.
// `catalogMediaKind` forces portrait/reference; omitted = auto (first image →
// portrait, later → reference, mirroring the client's optimistic path). Only
// the async (local/codex) lanes need this — the synchronous external SD-API
// path returns the filename to the client, which attaches it directly.
catalogIngredientId: z.string().min(1).max(200).optional(),
catalogMediaKind: z.enum(['portrait', 'reference']).optional(),
// Federated media provider (#4348). When set, the render is submitted to
// THIS registered peer instead of running on local hardware. Server-validated
// against the per-peer allowlist — an agent cannot route work to an arbitrary
// peer by naming one here. mediaProviderEngine names the provider-side
// engine within that allowlist; local image/video generation registers as
// 'local', which is the only engine a provider can currently advertise.
// What may cross to a peer, and what may not:
// docs/decisions/2026-08-20-federated-visual-prompts.md
mediaProviderPeerId: z.string().uuid().optional(),
mediaProviderEngine: z.string().trim().min(1).max(80).optional(),
}).refine(refineImagePixelCap, { message: PIXEL_CAP_MESSAGE, path: ['width'] });
// JSON callers (SDAPI bridge, avatar route, the Imagine page's old payload
// shape) skip the parser entirely; FormData callers get req.file + string
// req.body that coerceFormFields() converts before Zod validation.
// Only the formats mflux can decode — keep this in sync with the extension
// allowlist below so the route never silently relabels (e.g. HEIC) bytes
// as ".png".
const ACCEPTED_INIT_IMAGE_MIME = new Set(['image/png', 'image/jpeg', 'image/webp']);
const _MIME_TO_EXT = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/webp': '.webp' };
// Multi-reference editing accepts up to 4 references on dedicated field names.
// The legacy single `initImage` upload (mflux i2i) stays on its own slot so a
// FLUX.2 multi-ref upload and an mflux i2i upload don't collide.
const REFERENCE_IMAGE_FIELDS = Array.from({ length: MAX_REFERENCE_IMAGES }, (_, i) => `referenceImage${i + 1}`);
const IMAGE_UPLOAD_FIELDS = ['initImage', ...REFERENCE_IMAGE_FIELDS];
const imageGenUploads = optionalUploadFields(IMAGE_UPLOAD_FIELDS, {
fileFilter: (_req, file, cb) => cb(null, ACCEPTED_INIT_IMAGE_MIME.has((file.mimetype || '').toLowerCase())),
});
// Numerics arrive as strings from FormData — coerce before Zod validation.
// `referenceStrengths` is a repeated key (one per slot), which arrives as a
// string OR an array of strings; coerce element-wise so Zod sees numbers.
function coerceFormFields(body) {
const numericFields = ['width', 'height', 'steps', 'cfgScale', 'guidance', 'seed', 'initImageStrength'];
for (const f of numericFields) {
if (typeof body[f] === 'string' && body[f] !== '') body[f] = Number(body[f]);
}
if (typeof body.quantize === 'string' && /^\d+$/.test(body.quantize)) body.quantize = Number(body.quantize);
if (body.referenceStrengths != null) {
const raw = Array.isArray(body.referenceStrengths) ? body.referenceStrengths : [body.referenceStrengths];
body.referenceStrengths = raw.map((v) => (typeof v === 'string' && v !== '' ? Number(v) : v));
}
// Array fields are repeated multipart keys. A single selected value arrives
// as a bare string, not a one-element array — wrap it so Zod accepts it.
// `loraScales` numbers also arrive as strings, so coerce element-wise like
// referenceStrengths above.
for (const f of ['loraFilenames', 'loraPaths', 'referenceImageFiles']) {
if (body[f] != null && !Array.isArray(body[f])) body[f] = [body[f]];
}
if (body.loraScales != null) {
const raw = Array.isArray(body.loraScales) ? body.loraScales : [body.loraScales];
body.loraScales = raw.map((v) => (typeof v === 'string' && v !== '' ? Number(v) : v));
}
// Multipart sends checkbox values as 'true' / 'false' strings; coerce to
// bool so Zod's `z.boolean()` accepts them.
for (const f of ['cleanC2PA', 'denoise', 'autoClean']) {
if (typeof body[f] === 'string') body[f] = body[f] === 'true';
}
// Legacy single-flag clients: an explicit `autoClean` on the wire maps to
// BOTH new flags (preserves the pre-split behavior) only when the caller
// didn't also send the new fields. Modern clients that pass cleanC2PA /
// denoise explicitly win.
if (typeof body.autoClean === 'boolean') {
if (typeof body.cleanC2PA !== 'boolean') body.cleanC2PA = body.autoClean;
if (typeof body.denoise !== 'boolean') body.denoise = body.autoClean;
}
return body;
}
const avatarSchema = z.object({
name: z.string().max(100).optional(),
characterClass: z.string().max(100).optional(),
prompt: z.string().max(2000).optional(),
// When set, the route persists the rendered path onto the singleton
// character record itself (the character store has no id), so the client
// skips the follow-up PUT /api/character round-trip.
persistToCharacter: z.boolean().optional(),
});
// Upload a user-supplied image straight into the gallery (`data/images/`) so it
// rides the existing `image` peer-sync asset path. `data` is base64 (no data:
// URI prefix); the real format is sniffed server-side, so the schema only caps
// the legacy JSON request. Multipart uploads have no size cap.
const uploadImageSchema = z.object({
data: z.string().min(1).max(24 * 1024 * 1024),
});
// SynthID-defeat regen (issue #912). Body is optional — every field defaults
// server-side (strength → DEFAULT_REGEN_STRENGTH, steps → the model default,
// prompt → empty for minimal mutation). An empty/whitespace `prompt` is treated
// as "no prompt" by buildRegenParams, so the UI can send '' for the default.
const regenerateSchema = z.object({
strength: z.number().min(REGEN_STRENGTH_MIN).max(REGEN_STRENGTH_MAX).optional(),
steps: z.number().int().min(1).max(50).optional(),
prompt: z.string().max(MAX_PROMPT_LENGTH).optional(),
// 'flux' (default) = GPU img2img round-trip; 'light' = CPU-only spatial pass
// for installs without a FLUX runner (strength/steps/prompt ignored).
method: z.enum(['flux', 'light']).optional(),
// Annotation re-render (issue #2036 phase 2): seed the img2img init image from
// the saved flattened sketch (source + drawn strokes) instead of the raw
// gallery file, so the marks reshape the render. GPU-only (light ignores the
// init image); defaults to a higher denoise so the strokes take effect.
annotated: z.boolean().optional(),
});
// Film look (lib/filmLook.js) baked into a new copy of a gallery still — the
// same SVG filter the music-video preview and final render apply, rendered in
// the composition browser at the image's own size. Synchronous like Clean:
// writes a `_look-<preset>-<id>.png` variant + sidecar beside the untouched
// source, files it into the source's collections, and returns it.
router.post('/:filename/film-look', asyncHandler(async (req, res) => {
const filename = req.params.filename;
local.assertGalleryFilename(filename);
const { look } = validateRequest(filmLookBakeSchema, req.body ?? {});
const { metadata: sourceMeta } = await local.readImageSidecar(filename);
res.json(await applyFilmLookBake({ filename, sourceMeta, look }));
}));
// Visible-watermark removal — erases the Gemini / Nano-Banana bottom-right ✦.
// Body is optional: with no fields the corner box is auto-sized to the
// sparkle's typical footprint. `size` overrides the square side; `region`
// pins an explicit box (each field clamped server-side into the image) for
// off-spec placements. All ints in pixels.
const removeWatermarkSchema = z.object({
size: z.number().int().min(1).max(4096).optional(),
region: z.object({
x: z.number().int().min(0).max(100000).optional(),
y: z.number().int().min(0).max(100000).optional(),
w: z.number().int().min(1).max(4096).optional(),
h: z.number().int().min(1).max(4096).optional(),
}).optional(),
});
router.get('/status', asyncHandler(async (req, res) => {
// Optional ?mode= override lets the Image Gen page probe a specific
// backend (e.g. when the user flips the per-render chip to Codex but
// hasn't saved Codex as the default yet). Express's default query
// parser turns duplicated keys (?mode=local&mode=codex) into arrays,
// so guard on string type before forwarding so `mode` always reaches
// the dispatcher as `string | undefined`.
const rawMode = req.query.mode;
const mode = typeof rawMode === 'string' && IMAGE_GEN_MODES.includes(rawMode) ? rawMode : undefined;
const rawModelId = req.query.modelId;
const modelId = typeof rawModelId === 'string' && rawModelId.length <= 64 ? rawModelId : undefined;
res.json(await imageGen.checkConnection({ mode, ...(modelId ? { modelId } : {}) }));
}));
router.get('/active', asyncHandler(async (_req, res) => {
res.json({ activeJob: await imageGen.getActiveJob() });
}));
router.get('/agy/models', asyncHandler(async (_req, res) => {
const settings = await getSettings();
res.json(await imageGen.agy.listModels({
agyPath: settings.imageGen?.agy?.agyPath,
}));
}));
// SynthID-defeat regen availability (issue #912). Drives whether the lightbox
// shows the "Regenerate" action — it's hardware-gated on a local FLUX runner.
// Optional `?filename=` (issue #2036): when the caller names a source image, its
// model is resolved from the sidecar and threaded into the backend pick so the
// reported `modelId` matches the exact model a regen of THAT image would run —
// the annotate re-render dialog must disclose the real model before the render.
router.get('/regen/availability', asyncHandler(async (req, res) => {
const rawFilename = req.query.filename;
const galleryPath = typeof rawFilename === 'string' && rawFilename ? resolveGalleryImage(rawFilename) : null;
let sourceModelId;
if (galleryPath) {
// Read the sidecar by the RESOLVED gallery path's basename, never the raw
// query value: resolveGalleryImage only validated the basename, so a
// `../foo.png` input could otherwise traverse out of PATHS.images in the
// sidecar read. basename(galleryPath) is the sanitized filename.
const { metadata } = await local.readImageSidecar(basename(galleryPath));
sourceModelId = metadata?.modelId;
}
res.json(await getRegenAvailability({ sourceModelId }));
}));
// Shape returned for any image-gen job that goes through the mediaJobQueue
// (local + codex). Kept in one place so the two enqueue branches below stay
// in sync — the client's polling/SSE hooks key off these fields.
const queuedImageResponse = ({ jobId, position, status, mode, model, mediaProviderPeerId = null }) => ({
jobId,
generationId: jobId,
filename: `${jobId}.png`,
path: `/data/images/${jobId}.png`,
mode,
model,
status,
position,
// Which peer is rendering this, or null for a local/cloud render. The client
// needs it to label the in-flight card honestly — `mode` is null for a
// federated render precisely because no local backend is running it.
mediaProviderPeerId,
});
// What the render would send, before it is sent (#11317). Same preparation and
// prompt builders as POST /generate; the form says which uploads it holds by
// count rather than sending their bytes, and nothing is staged or queued.
const promptPreviewSchema = generateSchema.safeExtend({
uploadedInitImage: z.boolean().optional(),
uploadedReferenceCount: z.number().int().min(0).max(MAX_REFERENCE_IMAGES).optional(),
});
router.post('/prompt-preview', asyncHandler(async (req, res) => {
res.json(await previewImagePrompt(validateRequest(promptPreviewSchema, req.body ?? {})));
}));
router.post('/generate', imageGenUploads, asyncHandler(async (req, res) => {
const data = validateRequest(generateSchema, coerceFormFields(req.body));
if (data.catalogIngredientId) await assertCatalogIdentityWritable(data.catalogIngredientId);
const { data: params, mode, settings, uploadedTempPaths } = await prepareGenerateParams({
data,
files: req.files,
referenceImageFields: REFERENCE_IMAGE_FIELDS,
});
// FableLoom is compiled server-side after the backend pin resolves. The
// browser's prompt/reference fields are hints only: stable scene bindings,
// approved assets and deterministic graph continuity own the final request.
if (params.fableLoom) {
const taggedLoom = await getLoom(params.fableLoom.loomId);
const taggedEpisode = taggedLoom?.episodes?.find((episode) => episode.id === params.fableLoom.episodeId);
const renderSettings = taggedLoom ? asFableLoomRenderSettings(taggedLoom.renderSettings) : null;
if (renderSettings) {
params.width = renderSettings.width;
params.height = renderSettings.height;
params.aspectRatio = renderSettings.aspectRatio;
}
if (taggedLoom && taggedEpisode) {
const episodeOrder = inspectEpisodeProductionOrder(taggedLoom, taggedEpisode);
if (!episodeOrder.ready) {
throw new ServerError(
`FableLoom storyboard production is out of order: ${episodeOrder.reason}`,
{
status: 409,
code: 'FABLELOOM_EPISODE_ORDER_BLOCKED',
context: { details: { episodeOrder } },
},
);
}
}
const selected = mode === IMAGE_GEN_MODE.LOCAL
? selectLocalImageModelFromSettings(settings, params.modelId)
: null;
const cloud = selected ? null : resolveCloudProviderConfig(settings, mode, {
model: params.cloudModel, modelIsShippedDefault: params.cloudModelIsShippedDefault,
});
const model = selected
? { ...selected, loraCompatKey: loraCompatKey(selected) }
: (cloud ? { id: cloud.modelId } : null);
const providerMode = params.mediaProviderPeerId ? 'federated' : mode;
const compiled = await compileFableLoomVisualRequest({
tag: params.fableLoom,
kind: 'image',
capability: fableLoomImageCapabilities({
mode: providerMode,
model,
// The backend's own input cap (per model for fal.ai), never above
// the form ceiling.
inputBudget: Math.min(maxInputImages(mode, cloud?.modelId) ?? MAX_REFERENCE_IMAGES, MAX_REFERENCE_IMAGES),
}),
authoredPrompt: params.prompt,
authoredNegativePrompt: params.negativePrompt,
});
if (compiled) {
params.prompt = compiled.prompt;
params.negativePrompt = compiled.negativePrompt;
// The compiler's canon blocks, listed beside what the scene's own request listed (#11317).
if (compiled.promptAdditions?.length) params.promptAdditions = [...(params.promptAdditions || []), ...compiled.promptAdditions];
params.referenceImagePaths = compiled.referenceImagePaths;
params.referenceImageStrengths = compiled.referenceImageStrengths;
params.loraFilenames = compiled.loraFilenames;
params.loraPaths = [];
params.loraScales = compiled.loraScales;
params.visualConditioning = compiled.visualConditioning ? {
...compiled.visualConditioning,
render: {
provider: providerMode,
modelId: model?.id || null,
modelRevision: model?.revision || null,
parameters: {
width: params.width,
height: params.height,
...(params.aspectRatio ? { aspectRatio: params.aspectRatio } : {}),
},
},
} : null;
}
}
// Resolve an optional universe-collection target into a job tag the
// completion hook understands. Done server-side so a base-style probe lands
// in the same "Universe: <name>" bucket as batch renders without the
// front-end doing any collection bookkeeping. Best-effort: a provisioning
// failure drops the tag and the render still proceeds (it just won't
// auto-file) rather than failing the user's generation over a side-effect.
if (params.universeRun?.universeId) {
const { universeId, universeName, label, category, entryRef } = params.universeRun;
// The helper provisions the universe collection (best-effort) and assembles
// the tag. It preserves `entryRef` even when provisioning fails — the
// durable `imageRefs[]` append (#1395) must not depend on the gallery
// collection existing — and returns `undefined` (dropping the tag) only
// when there's nothing left to do (no collection AND no entryRef).
params.universeRun = await buildUniverseRunTag({
universeId,
universeName,
label,
category,
entryRef,
errorContext: 'image-gen → universe collection provision failed',
});
}
// Collapse the catalog-attach params into a single job tag the completion
// hook understands (#1359). Folded into `params` so it rides into both the
// local and codex `enqueueJob` branches below via `...params`; the raw fields
// are dropped so persisted job.params carries only the canonical tag.
if (params.catalogIngredientId) {
params.catalogAttach = {
ingredientId: params.catalogIngredientId,
...(params.catalogMediaKind ? { kind: params.catalogMediaKind } : {}),
};
}
delete params.catalogIngredientId;
delete params.catalogMediaKind;
// Multer's tmp upload is no longer needed once we've copied it into
// PATHS.images. Use res.on('close') so the temp files are cleaned up whether
// generateImage resolves, throws (handled by errorHandler middleware), or
// the client drops the connection mid-flight.
if (uploadedTempPaths.length) {
res.on('close', () => {
for (const p of uploadedTempPaths) unlinkGuarded(p).catch(() => {});
});
}
// Local + codex both go through mediaJobQueue (separate lanes — codex
// doesn't share MLX). External SD-API stays synchronous: it's a remote
// call with no local single-flight constraint to absorb. `settings` and
// `mode` were already resolved above (so the FLUX.2 + local-backend gate
// could fire before staging any uploads).
// Federated render (#4348): submit to the selected peer instead of running
// locally. Checked BEFORE the cloud/local dispatch below — those branches
// resolve this machine's backends, which a remote render never uses.
if (params.mediaProviderPeerId) {
// LoRA weights are the one input that still cannot cross, and it is a
// decision rather than a gap: a LoRA is a MODEL, not conditioning, and
// remote model installation is out of scope for federation (ADR
// docs/decisions/2026-08-22-federated-media-input-assets.md rule 3). Refuse
// rather than silently dropping it — a render that quietly ignores its LoRA
// is worse than one that says why.
if (params.loraFilenames?.length || params.loraPaths?.length) {
throw new ServerError(
'A federated media provider renders with the models its own operator installed — LoRA weights do not cross. '
+ 'Render locally, or install the LoRA on the peer and allowlist a model that uses it.',
{ status: 400, code: 'MEDIA_PROVIDER_INPUT_UNSUPPORTED' },
);
}
// Conditioning images DO cross (rule 1), by id: the bytes go up through the
// provider's authenticated, digest-verified asset endpoint immediately
// before submission. The marker keeps these LOCAL paths, never the
// provider-issued ids, so a reconcile after a restart re-stages the same
// bytes instead of naming staging slots that have since expired.
const inputAssets = collectRemoteInputAssets('image', params);
// A peer advertises specific models; it has no notion of 'this caller's
// default'. Say so rather than letting the wire schema report a bare
// 'expected string, received undefined' for a field the local path defaults.
if (!params.modelId) {
throw new ServerError(
'A federated render must name the provider model explicitly (modelId)',
{ status: 400, code: 'MEDIA_PROVIDER_MODEL_REQUIRED' },
);
}
// Re-validate against the wire schema here rather than trusting the route
// schema's overlap with it: this object is what gets persisted and replayed
// on every reconcile, so it must already be a body the provider accepts.
const request = buildFederatedMediaRequest({ kind: 'image', params });
const { peer, remoteMedia } = await prepareRemoteMediaJob({
peerId: params.mediaProviderPeerId,
kind: 'image',
request,
inputAssets,
});
// Drop every field that only means something to a LOCAL dispatch: the
// routing inputs consumed above, plus the backend selectors this render
// never uses. The destination tags (universeRun, writersRoom, musicVideo,
// catalogAttach) deliberately stay — their completion hooks fire off the
// finished filename and work identically for a federated render.
const {
mediaProviderPeerId: _peerId, mediaProviderEngine: _engine,
mode: _mode, cloudModel: _cloudModel, cloudModelIsShippedDefault: _cloudModelProvenance,
...jobParams
} = params;
// The prompt and model ride only inside the versioned marker: enqueueJob
// normalizes any job carrying one into the downgrade-safe shape, so this
// render cannot be re-run for real by a build rolled back past
// `remoteMedia`. Contract: services/federatedMedia/routedJobParams.js.
const queued = await enqueueLoggedImage(req, {
kind: 'image',
params: { ...jobParams, remoteMedia },
});
return res.json(queuedImageResponse({
...queued,
mode: null,
model: request.modelId,
mediaProviderPeerId: peer.id,
}));
}
// `cloudModel` and its provenance flag are dispatcher-level knobs, not
// provider params — the resolver folds them into the provider's own `model`
// and `modelIsShippedDefault`, so drop the raw fields before they ride into
// the persisted job params.
const cloudModel = params.cloudModel;
const modelIsShippedDefault = params.cloudModelIsShippedDefault;
delete params.cloudModel;
delete params.cloudModelIsShippedDefault;
const cloud = resolveCloudProviderConfig(settings, mode, { model: cloudModel, modelIsShippedDefault });
if (cloud) {
// Reject up-front rather than enqueueing a doomed job — the cloud CLIs are
// gated behind an explicit toggle each (not every Codex account has access
// to the image_gen tool, and grok spends the user's Grok quota).
if (!cloud.enabled) throw cloud.disabledError;
// `mode` inside jobParams is the queue's discriminator — laneForJob()
// routes cloud jobs to the parallel cloud lane, and runJob's image branch
// dispatches to the matching imageGen provider module when it sees it.
// `cloud.modelId` is the *effective* model so the response metadata reports
// what actually renders (gpt-6-luna by default) instead of "codex"/null.
const queued = await enqueueLoggedImage(req, { kind: 'image', params: { ...cloud.jobParams, ...params } });
return res.json(queuedImageResponse({ ...queued, mode, model: cloud.modelId }));
}
if (mode === IMAGE_GEN_MODE.LOCAL) {
const { pythonPath: py, selectedModel } = resolveLocalImageModel(settings, params);
const queued = await enqueueLoggedImage(req, {
kind: 'image',
params: {
...params,
pythonPath: py,
...(selectedModel?.id ? { modelId: selectedModel.id } : {}),
},
});
// selectedModel reflects the actual fallback chain resolveLocalImageModel
// applied (caller modelId → 'dev' → allModels[0]) rather than just the
// requested id.
return res.json(queuedImageResponse({
...queued,
mode: IMAGE_GEN_MODE.LOCAL,
model: selectedModel?.id || params.modelId || 'dev',
}));
}
// Selective section revision (#9011): the external/agy lane renders
// synchronously and never touches enqueueLoggedImage's guard above, so it
// gets its own check right before the (paid) render call. A no-op when the
// tag carries no revisionId.
if (params.musicVideo?.revisionId) {
const { assertRevisionOpen } = await import('../services/musicVideo/revisionService.js');
await assertRevisionOpen(params.musicVideo.projectId, params.musicVideo.revisionId, { sceneId: params.musicVideo.sceneId, kind: 'image' });
}
const result = await imageGen.generateImage(params);
if (params.musicVideoProjectId && result?.filename) {
const { fileIntoMusicVideoCollection } = await import('../services/musicVideoCollectionHook.js');
await fileIntoMusicVideoCollection(params.musicVideoProjectId, [{ kind: 'image', ref: result.filename }]);
}
if (params.fableLoom && result?.filename) {
await attachNodeImage(
params.fableLoom.loomId,
params.fableLoom.episodeId,
params.fableLoom.nodeId,
{
filename: result.filename,
jobId: result.generationId,
visualConditioning: params.visualConditioning,
},
);
}
res.json(result);
}));
router.post('/avatar', asyncHandler(async (req, res) => {
const data = validateRequest(avatarSchema, req.body);
const result = await imageGen.generateAvatar(data);
// `result.path` is server-generated as `/data/images/<file>` (the same value
// the client previously round-tripped through PUT /api/character), so it's
// safe to persist directly without re-validating against the path regex.
if (data.persistToCharacter && result?.path) {
await characterService.setAvatar(result.path);
}
res.json(result);
}));
// Save an uploaded image into the gallery dir so callers (e.g. author
// headshots) get a `/data/images/<f>` URL that the peer-sync `image` asset
// path can transfer — unlike `/api/uploads/<f>`, which is not a pullable
// asset kind and 404s on a peer.
router.post('/upload', optionalUpload('file'), asyncHandler(async (req, res) => {
if (req.file) {
try {
return res.json(await local.saveUploadedGalleryImage(null, req.file.path));
} finally {
await unlinkGuarded(req.file.path).catch(() => {});
}
}
const { data } = validateRequest(uploadImageSchema, req.body);
res.json(await local.saveUploadedGalleryImage(data));
}));
// Local-only: list image models and LoRAs the local backend can use.
router.get('/models', (_req, res) => {
res.json(local.listImageModels());
});
// Per-model download status. Returns `[{ id, repo, cached, sizeBytes }]` so
// the form can show an inline "Available" or "Download" badge next to the
// model picker — without waiting until a render to discover a multi-GB HF
// download. Models without a known HF repo (typically third-party custom
// entries with `runner: 'mflux'` and a non-default name) report
// `cached: null` so the UI can render "unknown" rather than a misleading
// "not downloaded" state. Lazy generation still works regardless of badge.
const imageModelCacheStatus = async (m) => {
if (usesMossSwift(m)) return mossModelCacheStatus(m.id);
const required = requiredReposForModel(m);
if (!required) return { id: m.id, repo: null, cached: null, sizeBytes: 0 };
// Inspect every required repo (main + any aux text encoders). The badge
// is `cached: true` only when ALL are cached; sizeBytes is the sum. The
// `pendingRepos` field lets the UI explain WHICH repos still need a pull
// so the user isn't surprised when clicking "Download" triggers >1 fetch.
const inspections = await Promise.all(required.map((r) => inspectModelCache(r)));
const cached = inspections.every((i) => i.cached);
const sizeBytes = inspections.reduce((sum, i) => sum + (i.sizeBytes || 0), 0);
const pendingRepos = required.filter((_, i) => !inspections[i].cached);
// Integrity is only meaningful for repos that finished downloading — run
// the cheap structural check across every cached required repo and report
// the worst result, so a corrupt aux encoder still surfaces a Repair state.
const integrity = cached ? aggregateVerifies(await Promise.all(required.map((r) => verifyModelCache(r)))) : null;
return { id: m.id, repo: required[0], cached, sizeBytes, requiredRepos: required, pendingRepos, integrity };
};
router.get('/models/status', asyncHandler(async (_req, res) => {
res.json(await Promise.all(getImageModels().map(imageModelCacheStatus)));
}));
// POST /models/verify — on-demand integrity re-scan. `deep:true` adds the
// per-file sha256 comparison on top of the structural check. With no `modelId`
// it scans every model.
const verifyImageBodySchema = z.object({
modelId: z.string().min(1).optional(),
deep: z.boolean().optional(),
});
router.post('/models/verify', asyncHandler(async (req, res) => {
const parsed = verifyImageBodySchema.safeParse(req.body || {});
if (!parsed.success) failValidation(parsed);
const { modelId, deep = false } = parsed.data;
const models = getImageModels().filter((m) => (modelId ? m.id === modelId : true));
if (modelId && models.length === 0) {
throw new ServerError(`Unknown model id: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
}
const results = await Promise.all(models.map(async (m) => {
if (usesMossSwift(m)) return { id: m.id, ...aggregateVerifies([await verifyMossWeights({ deep })]) };
const required = requiredReposForModel(m) || [];
const verifies = await Promise.all(required.map((r) => verifyModelCache(r, { deep })));
return { id: m.id, ...(aggregateVerifies(verifies) || { status: 'missing', checkedDeep: deep, badFiles: [] }) };
}));
res.json({ deep, models: results });
}));
// POST /models/:modelId/repair — delete the flagged weight files across the
// model's required repos so the existing resumable HF fetch path re-downloads
// them. Returns the deleted-file list; the client then re-triggers the normal
// download SSE to pull clean copies with progress.
router.post('/models/:modelId/repair', asyncHandler(async (req, res) => {
const model = getImageModels().find((m) => m.id === req.params.modelId);
if (!model) throw new ServerError(`Unknown model id: ${req.params.modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
const parsed = z.object({ deep: z.boolean().optional() }).safeParse(req.body || {});
if (!parsed.success) failValidation(parsed);
const deep = parsed.data.deep || false;
if (usesMossSwift(model)) return res.json(await repairMossWeights({ deep }));
const required = requiredReposForModel(model);
if (!required) {
throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file.`, { status: 400, code: 'NO_REPO_FOR_MODEL' });
}
const repaired = await Promise.all(required.map((repo) => repairModelCache(repo, { deep })));
const deleted = repaired.flatMap((r) => r.deleted.map((name) => ({ repo: r.repoId, name })));
res.json({ deep, deleted, repos: required });
}));
// SSE-driven model download. Cancels the python child if the client
// disconnects mid-download; cross-route in-flight dedupe lives in
// startHfDownloadStream so a FLUX repo shared with video gen can't spawn
// two concurrent children.
const downloadableImageModel = (req) => {
const { modelId } = validateRequest(modelDownloadParamsSchema, req.params);
const model = getImageModels().find((m) => m.id === modelId);
if (!model) throw new ServerError(`Unknown model id: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
return model;
};
router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
validateRequest(modelDownloadQuerySchema, req.query);
res.json(await imageModelCacheStatus(downloadableImageModel(req)));
}));
router.post('/models/:modelId/download', asyncHandler(async (req, res) => {
const { force } = validateRequest(modelDownloadQuerySchema, req.query);
const model = downloadableImageModel(req);
if (usesMossSwift(model)) return streamMossAction(req, res, downloadMossWeights);
const repos = requiredReposForModel(model);
if (!repos) {
throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file — cannot pre-download.`, {
status: 400,
code: 'NO_REPO_FOR_MODEL',
});
}
// Sequentially fetch every required repo (main + aux text encoders for
// HiDream). The SSE stream tags each event with `repo` so the client can
// show per-repo progress / log lines. `?force=1` (repair-initiated) re-fetches
// even when the repo still looks cached, so a deleted shard isn't skipped.
await startHfDownloadStream({ req, res, repos, force });
}));
router.get('/loras', asyncHandler(async (_req, res) => {
res.json(await local.listLoraFilenames());
}));
const galleryReads = createImageGalleryHandlers(local.listGallery);
router.get('/gallery/collections', galleryReads.collections);
router.get('/gallery/facets', galleryReads.facets);
router.post('/gallery/lookup', galleryReads.lookup);
router.get('/gallery', galleryReads.list);
// SSE progress stream. Local renders run via the mediaJobQueue and emit
// `queued` → `started` → `progress` → `complete` events; the queue owns the
// SSE attachment for those. Codex still produces job-keyed SSE through its
// own provider — fall through to the dispatcher when the queue doesn't know
// the job. External backend has no SSE (it's blocking).
router.get('/:jobId/events', (req, res) => {
if (attachQueueSseClient(req.params.jobId, res)) return;
if (imageGen.attachSseClient(req.params.jobId, res)) return;
throw new ServerError('Job not found or expired', { status: 404 });
});
router.post('/cancel', asyncHandler(async (req, res) => {
// Cancel selection rules, in priority order:
// 1. body.all === true — cancel every queued/running image job. Used by
// the writers-room storyboard "Cancel renders" CTA, which can have
// 20+ scene renders in flight at once.
// 2. Explicit body.jobId — cancel exactly that job and NOTHING else. An id
// that is unknown (404) or already terminal (409) never falls through
// to another job or a bulk cancel (#9932). A malformed id is a 400.
// 3. No jobId — cancel the newest queued/running local image job (most
// recent activity wins, matching the user's last "submit" gesture).
// 4. No queue match — fall through to the codex-mode cancel.
const { jobId: requestedJobId, all } = validateRequest(imageCancelBodySchema, req.body ?? {});
const imageJobs = listJobs({ kind: 'image' });
const cancellable = imageJobs.filter((j) => j.status === 'queued' || j.status === 'running');
if (all === true) {
// Cancel queued first so the running job's slot doesn't get refilled the
// moment we cancel it. Settle individually so one stale job doesn't
// block the rest. cancellable is already a fresh filter() result.
const ordered = cancellable.sort((a, b) => {
if (a.status === b.status) return 0;
return a.status === 'queued' ? -1 : 1;
});
const results = await Promise.all(ordered.map((j) => cancelJob(j.id).catch((err) => ({ ok: false, error: err.message }))));
// Belt-and-braces: also poke the legacy single-process cancel so any
// in-flight gen outside the queue (codex sync mode) gets stopped.
imageGen.cancel();
return res.json({ ok: true, canceled: results.filter((r) => r?.ok).length, attempted: results.length });
}
if (requestedJobId) {
const known = imageJobs.find((j) => j.id === requestedJobId);
if (known) {
if (!cancellable.includes(known)) {
throw new ServerError(`Job already ${known.status}`, { status: 409, code: 'ALREADY_TERMINAL' });
}
const result = await cancelJob(known.id);
if (!result?.ok && result?.code) {
throw new ServerError(result.error || 'Cancel failed', { status: result.code === 'ALREADY_TERMINAL' ? 409 : 404, code: result.code });
}
return res.json(result);
}
// Not in the queue — it may be a legacy provider job (sync codex/grok/agy/
// fal, local) the dispatcher owns. Exact-ID only; never the bulk path.
if (imageGen.cancelJob(requestedJobId)) return res.json({ ok: true });
throw new ServerError('Job not found or expired', { status: 404 });
} else if (cancellable.length) {
// "Most recent submit" — explicitly sort by queuedAt DESC instead of
// relying on listJobs() ordering (which puts gpuRunning before
// codexRunning, then queue, then archive). queuedAt is the user's
// actual submit timestamp; startedAt would mis-order an older queued
// job that just dequeued ahead of a more-recently-submitted job
// still waiting in queue.
const latestSubmitFirst = [...cancellable].sort((a, b) => {
const ta = new Date(a.queuedAt || 0).getTime();
const tb = new Date(b.queuedAt || 0).getTime();
return tb - ta;
});
return res.json(await cancelJob(latestSubmitFirst[0].id));
}
const cancelled = imageGen.cancel();
res.json({ ok: cancelled });
}));
// Also purges the filename from universe canon (entry `imageRefs` and style
// references) inside the same backup admission as the file removal.
router.delete('/:filename', asyncHandler(async (req, res) => {
res.json(await deleteGalleryImage(req.params.filename));
}));
// Variant set for ONE image, for the lightbox original-vs-cleaned toggle —
// see listImageVariants for why no host list can answer it.
router.get('/:filename/variants', asyncHandler(async (req, res) => {
const filename = req.params.filename;
local.assertGalleryFilename(filename);
const { listImageVariants } = await import('../services/mediaAssetIndex/gallery.js');
res.json({ items: await listImageVariants(filename, local.listGallery) });
}));
router.post('/:filename/visibility', asyncHandler(async (req, res) => {
res.json(await local.setImageHidden(req.params.filename, validateRequest(imageVisibilityBodySchema, req.body ?? {}).hidden));
}));
router.patch('/:filename/prompt', asyncHandler(async (req, res) => {
const body = validateRequest(updatePromptSchema, req.body ?? {});
res.json(await local.updateImagePrompt(req.params.filename, body.prompt));
}));
router.post('/:filename/clean', asyncHandler(async (req, res) => {
const filename = req.params.filename;
local.assertGalleryFilename(filename);
const { metadata: sourceMeta } = await local.readImageSidecar(filename);
res.json(await applyImageClean({ filename, sourceMeta }));
}));
// Visible-watermark removal — erases the Gemini / Nano-Banana bottom-right ✦.
// Unlike SynthID regen (which round-trips the WHOLE image to overwrite an
// invisible per-pixel signal), this localizes the corner logo and reconstructs
// only that box via a dependency-free harmonic inpaint — so it's a CPU-only
// sharp pass that runs on every install, GPU or not, and leaves the rest of the
// image byte-faithful. Synchronous like Clean: writes a `_nowatermark.png`
// variant + sidecar, files it into the source's collections, and returns it.
router.post('/:filename/remove-watermark', asyncHandler(async (req, res) => {
const filename = req.params.filename;
local.assertGalleryFilename(filename);
const body = validateRequest(removeWatermarkSchema, req.body || {});
const { metadata: sourceMeta } = await local.readImageSidecar(filename);
res.json(await applyWatermarkRemoval({ filename, sourceMeta, size: body.size, region: body.region }));
}));
// SynthID-defeat regeneration (issue #912). Round-trips an existing gallery
// image through local FLUX img2img at low–moderate denoise so the per-pixel
// watermark is overwritten by fresh sampling — the only honest defeat path
// (the lossless clean above can't touch SynthID). Post-hoc + history-only:
// enqueues a normal local image job (GPU lane) using the source's own prompt;
// the new render lands in the gallery as a variant of the source. Hardware-
// gated — 400s with an actionable message when no local FLUX runner exists.
router.post('/:filename/regenerate', asyncHandler(async (req, res) => {
const filename = req.params.filename;
local.assertGalleryFilename(filename);
const body = validateRequest(regenerateSchema, req.body || {});
const sourceAbsPath = resolveGalleryImage(filename);
if (!sourceAbsPath) {
throw new ServerError('Image not found', { status: 404, code: 'NOT_FOUND' });
}
// Annotation re-render (issue #2036 phase 2): use the saved flattened sketch
// (source + strokes) as the img2img init image. It's a whole-image denoise, so
// the light spatial pass can't honor the marks — GPU only. Validate cheaply
// here (no disk writes) so a bad request 400s without leaving anything behind;
// the actual staging copy happens below, only once every gate has passed.
let annotatedSketchPath = null;
if (body.annotated) {
if (body.method === 'light') {
throw new ServerError('Annotation re-render needs the GPU img2img pass, not the light method.', { status: 400, code: 'VALIDATION_ERROR' });
}
const key = itemKey({ kind: 'image', ref: filename });
if (!isValidSketchKey(key)) {
throw new ServerError('Image cannot be annotated', { status: 400, code: 'VALIDATION_ERROR' });
}
annotatedSketchPath = await getSketchPngPath(key);
if (!annotatedSketchPath) {
throw new ServerError('No saved annotation to re-render — draw over the image and save first.', { status: 400, code: 'NO_ANNOTATION' });
}
}
// Sidecar (for prompt/model) and the on-disk dimension probe have no data
// dependency — overlap the two reads.
const [{ metadata: sourceMeta }, sourceDims] = await Promise.all([
local.readImageSidecar(filename),
readImageDimensions(sourceAbsPath),
]);
// CPU-only light path (no FLUX runner required). A best-effort spatial pass
// for installs that can't run the GPU round-trip — synchronous like Clean:
// it writes a `_regen-light.png` variant inline and returns it (no queue).
if (body.method === 'light') {
return res.json(await applyLightRegenVariant({ filename, sourceAbsPath, sourceMeta }));
}
const backend = await resolveRegenBackend({ sourceModelId: sourceMeta.modelId });
if (!backend.available) {
throw new ServerError(backend.reason, { status: 400, code: 'REGEN_BACKEND_UNAVAILABLE' });
}
// Stage the flattened annotation ONLY now that every gate has passed and the
// job is about to enqueue — so a rejected request (unavailable backend, failed
// read) never leaves an orphaned snapshot behind. The local runner re-validates
// initImagePath against its approved image roots (gallery / image-refs /
// visual-templates) and silently drops anything outside them — `data/media-
// sketches/` is NOT one, so the sidecar is copied into the image-refs root the
// runner accepts. The copy also freezes the markup at enqueue time (a later
// re-save can't change what this queued job renders from), and the `init-<uuid>`
// name (it IS this job's init image) lets imageRefsGc.js sweep it once
// unreferenced.
let initImageAbsPath = null;
if (annotatedSketchPath) {
await ensureDir(PATHS.imageRefs);
initImageAbsPath = join(PATHS.imageRefs, `init-${randomUUID()}.png`);
await copyFileGuarded(annotatedSketchPath, initImageAbsPath);
}
// Provider-aware default (issue #912): SynthID-bearing sources keep the
// known-good 0.25; local FLUX sources use a lighter pass. An annotation
// re-render instead defaults higher so the drawn marks reshape the render
// (issue #2036). The explicit `strength` override always wins.
const strength = body.strength
?? (body.annotated ? REGEN_ANNOTATED_STRENGTH_DEFAULT : resolveRegenStrengthDefault(sourceMeta));
const params = buildRegenParams({
filename,
sourceAbsPath,
sourceMeta,
sourceDims,
model: backend.model,
pythonPath: backend.pythonPath,
strength,
steps: body.steps,
promptOverride: body.prompt,
initImageAbsPath,
annotated: !!body.annotated,
});
const queued = await enqueueLoggedImage(req, { kind: 'image', params });
const via = body.annotated ? 'annotation re-render' : 'Regenerating';
console.log(`♻️ ${via} ${filename} via ${backend.model.id} (strength=${strength}) → job ${queued.jobId.slice(0, 8)}`);
return res.json(queuedImageResponse({ ...queued, mode: IMAGE_GEN_MODE.LOCAL, model: backend.model.id }));
}));
// Local-mode setup automation (python probe/venv, FLUX.2 install/status,
// HF token store, pip installer) lives in its own router.
router.use("/setup", setupRouter);
export default router;