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
/**
* Universe Builder Render Orchestration
*
* Extracted from routes/universeBuilder/render.js POST /:id/render.
* Owns the full render-job flow: settings validation, image-mode resolution,
* compilePrompts, LoRA resolution, findOrCreateUniverseCollection,
* registerUniverseBuilderRun, job enqueue loop, run record.
*
* The route handler becomes: validate → renderUniverseJobs → res.json.
*/
import { randomUUID } from 'crypto';
import * as svc from './universeBuilder.js';
import { assertMediaQueueRoom, enqueueJob, partialBatchAdmissionError } from './mediaJobQueue/index.js';
import { getSettings } from './settings.js';
import { findOrCreateUniverseCollection } from './mediaCollections.js';
import { buildUniverseRunTag } from './universeRunTag.js';
import { registerUniverseBuilderRun, shrinkUniverseBuilderRun } from './universeBuilderCollectionHook.js';
import { IMAGE_GEN_MODE, QUEUEABLE_IMAGE_MODES } from './imageGen/modes.js';
import { resolveRenderTargetConfig } from './imageGen/cloudProviderConfig.js';
import { resolveLocalImageModel } from './imageGen/prepareParams.js';
import { RENDER_TARGET, recordRenderPin } from '../lib/renderTargets.js';
import { resolveImageCleaners } from '../lib/imageCleanDefaults.js';
import { getStylePresetById } from '../lib/writersRoomStylePresets.js';
import { ServerError } from '../lib/errorHandler.js';
/**
* Orchestrate a full Universe Builder render batch.
*
* @param {string} universeId - The universe id.
* @param {object} body - Validated render request body (renderSchema shape).
* @param {function} mapServiceError - Error mapper from the route.
* @returns {Promise<object>} Response payload: { runId, collectionId, collectionName, promptCount, jobIds, entryJobs, mode }
*/
export async function renderUniverseJobs(universeId, body, mapServiceError) {
const universe = await svc.getUniverse(universeId).catch((err) => { throw mapServiceError(err); });
// Resolve a style preset (server-side authoritative list) so the embrace
// tokens are deterministic for this render even if the client sent a stale
// preset object. Unknown ids are ignored (server is the source of truth).
const stylePreset = getStylePresetById(body.stylePresetId);
// `negativePrompt` is the schema field; `extraNegative` is compilePrompts'
// option name (avoids shadowing `negativePrompt` on each compiled item).
const compiled = svc.compilePrompts(universe, {
promptMode: body.promptMode,
selection: body.selection,
sheetSelection: body.sheetSelection,
canonSelection: body.canonSelection,
batchPerVariation: body.batchPerVariation,
extraStyle: body.extraStyle,
extraNegative: body.negativePrompt,
stylePresetPrompt: stylePreset?.prompt,
stylePresetNegative: stylePreset?.negativePrompt,
stylePresetLabel: stylePreset?.label,
});
if (!compiled.length) {
throw new ServerError('No prompts to render — add canon entries, variations, or composite sheets first', {
status: 400, code: 'WORLD_BUILDER_EMPTY',
});
}
const settings = await getSettings();
// Render-target ladder (#3231): body.mode → the universe's persisted pin
// (Phase 3) → the universe-bible pin in settings.renderDefaults → the
// install default → external (rejected below). body.cloudModel wins over
// the record's imageModelId pin the same way.
const renderPin = recordRenderPin(universe);
const { mode, cloud } = resolveRenderTargetConfig(settings, RENDER_TARGET.UNIVERSE_BIBLE, {
mode: body.mode,
model: body.cloudModel,
recordMode: renderPin.mode,
recordModel: renderPin.modelId,
fallbackMode: IMAGE_GEN_MODE.EXTERNAL,
});
// Reject `external` mode upfront — batch rendering against a remote SD-API
// would block this request for the entire batch, and we don't want to leave
// an orphaned media collection behind when we discover this mid-loop below.
if (!QUEUEABLE_IMAGE_MODES.includes(mode)) {
throw new ServerError(
'Batch render requires local, codex, or grok mode — switch image-gen mode in Settings → Image Gen',
{ status: 400, code: 'WORLD_BUILDER_EXTERNAL_UNSUPPORTED' },
);
}
// Mirror the upfront validation /api/image-gen/generate does so a doomed
// batch fails before any jobs land in the queue.
if (cloud && !cloud.enabled) throw cloud.disabledError;
const localModel = mode === IMAGE_GEN_MODE.LOCAL
? resolveLocalImageModel(settings, { modelId: body.modelId })
: null;
if (mode === IMAGE_GEN_MODE.LOCAL && !localModel.selectedModel) {
throw new ServerError('No local image-gen models are registered.', {
status: 400, code: 'IMAGE_GEN_UNKNOWN_MODEL',
});
}
// Refuse a batch the media queue cannot hold (#8326) whole — before the
// collection is provisioned or any render lands — rather than half-queue it.
assertMediaQueueRoom(compiled.length);
// Provision the collection up front so renders can be tagged as they
// complete. The completion hook (universeBuilderCollectionHook) will add
// each finished image's filename to this collection. Resolution is
// universeId-first (not name-first) so a re-render finds the existing
// linked bucket even if the universe was hand-renamed or another
// universe happens to share the same display name. Name-only matching
// would either fork the bucket on rename or hijack a foreign universe's
// collection — the atomic helper rules out both.
const collection = await findOrCreateUniverseCollection({
universeId: universe.id,
universeName: universe.name,
description: `Universe Builder renders for "${universe.name}"`,
});
const runId = randomUUID();
const jobIds = [];
// Map cfgScale → guidance the same way /api/image-gen/generate does. The
// mediaJobQueue calls imageGen/local.generateImage() directly (not the
// dispatcher), so without this mapping the Universe Builder UI's CFG control
// would silently no-op for local renders.
const guidance = body.guidance ?? body.cfgScale;
// Local image gen reads `loraFilenames` (basenames) + `loraScales` (parallel
// array of numbers), not the `[{filename, scale}]` UI shape. Convert here so
// every enqueued job actually applies the user's LoRA selection.
const loraFilenames = Array.isArray(body.loras) && body.loras.length
? body.loras.map((l) => l.filename)
: undefined;
const loraScales = Array.isArray(body.loras) && body.loras.length
? body.loras.map((l) => l.scale)
: undefined;
const baseParams = {
width: body.width,
height: body.height,
steps: body.steps,
cfgScale: body.cfgScale,
guidance,
quantize: body.quantize,
seed: body.seed,
loraFilenames,
loraScales,
};
// Parallel-indexed mapping from jobId → entryRef so the client can show a
// per-entry pending loader (MediaJobThumb-style) on the variation / sheet /
// canon row that owns this render. Only entries with a stable `id` carry an
// entryRef in `compiled` (the sanitizer mints ids on every write now, so
// legacy id-less records are the only gap).
const entryJobs = [];
// Register the run BEFORE enqueueing any jobs — the queue may dispatch and
// emit `completed` synchronously for the first job, and without prior
// registration the completion hook can't coalesce the run's
// emitRecordUpdated calls. `compiled.length` is the authoritative expected
// count (each compiled item produces exactly one job below).
registerUniverseBuilderRun({ runId, universeId: universe.id, jobCount: compiled.length });
const recordRun = () => svc.recordRun({
id: runId,
universeId: universe.id,
collectionId: collection.id,
jobIds,
promptCount: compiled.length,
createdAt: new Date().toISOString(),
});
for (const item of compiled) {
const params = {
...baseParams,
prompt: item.prompt,
negativePrompt: item.negativePrompt || undefined,
...(item.promptAdditions?.length ? { promptAdditions: item.promptAdditions } : {}),
// Tag every job so the completion hook can route the result back
// into the run's collection without us having to thread additional
// arguments through the queue. `entryRef` (when present — variations
// and composite sheets gain it once the universe has been written
// through the current sanitizer) lets the hook also append the
// rendered filename to the source variation/sheet/canon entry's
// `imageRefs[]` so the Universe Builder can show the latest render
// as an avatar next to each item. The pre-resolved `collection` +
// shared `runId` are passed so each per-item tag reuses them without
// re-provisioning the collection.
universeRun: await buildUniverseRunTag({
universeId: universe.id,
collection,
runId,
category: item.category,
label: item.label,
entryRef: item.entryRef,
}),
};
// The queue dispatches directly to imageGen/{codex,local}.generateImage,
// bypassing imageGen/index.js's dispatcher that resolves cleaners for
// direct callers. Resolve here so the per-mode cleanC2PA + denoise
// settings apply to Universe Builder batch renders the same way they
// do for /api/image-gen/generate and pipeline renders.
const { cleanC2PA, denoise } = resolveImageCleaners(undefined, settings, mode);
const jobParams = cloud
? { ...cloud.jobParams, cleanC2PA, denoise, ...params }
// mode === IMAGE_GEN_MODE.LOCAL (validated upfront).
: { pythonPath: localModel.pythonPath, modelId: localModel.selectedModel.id, cleanC2PA, denoise, ...params };
const queued = await enqueueJob({ kind: 'image', params: jobParams }).catch(async (err) => {
// Refused part-way (another producer filled the queue after the
// preflight): the rest will never be enqueued, so release them from the
// run's pending count, keep a run record for the renders that DID land,
// and say how many that was.
shrinkUniverseBuilderRun(runId, compiled.length - jobIds.length);
if (jobIds.length) await recordRun();
throw partialBatchAdmissionError(err, { admitted: jobIds.length, total: compiled.length, noun: 'renders' });
});
jobIds.push(queued.jobId);
if (item.entryRef) entryJobs.push({ jobId: queued.jobId, entryRef: item.entryRef });
}
const run = await recordRun();
console.log(`🌍 Universe Builder render — universe=${universe.name} prompts=${compiled.length} mode=${mode} runId=${runId.slice(0, 8)}`);
return {
runId: run.id,
collectionId: collection.id,
collectionName: collection.name,
promptCount: compiled.length,
jobIds,
// Per-entry mapping for client-side pending-state UI. Empty when the
// batch only contains entries without stable ids (legacy fallback).
entryJobs,
mode,
};
}