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 { Router, raw } from 'express';
import { createReadStream } from 'node:fs';
import { z } from 'zod';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { streamAttachment } from '../lib/streamAttachment.js';
import { validateRequest } from '../lib/validation.js';
import { getTarget, listTargets, detectHostCapabilities, unavailableReason, unavailableReasonLabel, IMAGE_TO_3D_TARGET_IDS, renderOptionSupportFor } from '../services/imageTo3d/targets.js';
import { getTargetAdapter } from '../services/imageTo3d/adapters.js';
import {
listModels,
getModel,
createModel,
startGeneration,
deleteModel,
getModelAsset,
getModelFullMesh,
getModelUsdz,
saveModelUsdz,
USDZ_MAX_BYTES,
} from '../services/imageTo3d/models.js';
import {
RENDER_STEPS_MIN, RENDER_STEPS_MAX, RENDER_SEED_MAX, DETAIL_TIERS, ALPHA_MODES,
SUBJECT_SCALE_MIN_EXCLUSIVE, SUBJECT_SCALE_MAX,
} from '../services/imageTo3d/renderOptions.js';
import { createInstallLogger } from '../lib/installLogger.js';
import { onClientDisconnect, openSseStream } from '../lib/sseDownload.js';
const router = Router();
const galleryFilenameSchema = z.string().trim().min(1).max(256)
.regex(/^[^/\\]+\.(png|jpe?g|webp)$/i, 'filename must be a gallery image basename');
// PER-RUN sampler knobs, shared by create and re-generate. Nothing persists
// between runs: absent steps → the pipeline default, absent seed → a fresh
// random roll for that run, absent keyBackground → no keying (the pipeline's own
// learned matte runs instead), absent subjectScale → the source's own framing.
const renderOptionsSchema = z.object({
steps: z.number().int().min(RENDER_STEPS_MIN).max(RENDER_STEPS_MAX).optional(),
seed: z.number().int().min(0).max(RENDER_SEED_MAX).optional(),
keyBackground: z.boolean().optional(),
// Abstract tier, not a lane's raw pipeline value — the target maps it (see
// renderOptions.js). Enums come from there so the route can't accept a tier the
// normalizer would silently discard.
detail: z.enum([...DETAIL_TIERS]).optional(),
alphaMode: z.enum([...ALPHA_MODES]).optional(),
normalMap: z.boolean().optional(),
// Open at zero, closed at one — `1` is the identity (no reframing) and the
// default; bounds come from renderOptions.js so the route can't accept a value
// the normalizer would silently discard.
subjectScale: z.number()
.gt(SUBJECT_SCALE_MIN_EXCLUSIVE)
.max(SUBJECT_SCALE_MAX)
.optional(),
});
const createModelSchema = z.object({
name: z.string().trim().min(1).max(120),
filename: galleryFilenameSchema,
target: z.enum([...IMAGE_TO_3D_TARGET_IDS]).optional(),
}).extend(renderOptionsSchema.shape);
// Target ids with an install currently running — a rapid double-click would
// otherwise race two clone/setup processes against the same install dir.
// isInstalled() can't gate the second click (the first install hasn't produced
// the venv yet). Mirrors imageGenSetup.js's flux2InstallInFlight, generalized
// per-target.
const installsInFlight = new Set();
/**
* The selectable image→3D targets, each annotated with whether it can run on
* this host (Apple Silicon / memory gating) and whether its local model is
* installed — so the client can render a target selector with disabled /
* needs-install / ready states. Read-only, no LLM/GPU work — safe to call on
* load. Availability/installed-state/extra diagnostics resolve through each
* target's adapter (`services/imageTo3d/adapters.js`) — adding a target needs no
* new branch here.
*/
const annotateTargetStatus = async (target) => {
const adapter = getTargetAdapter(target.id);
const installed = adapter ? adapter.isInstalled() : null;
// An installed target can still be silently degraded (e.g. TRELLIS.2's Metal
// texture bake — #2952); a target's adapter opts into reporting that via
// `describeInstallState()`. Only probed once installed — there is nothing to
// report before then.
const state = installed && adapter?.describeInstallState ? await adapter.describeInstallState() : null;
return { ...target, installed, ...state?.fields };
};
router.get('/targets', asyncHandler(async (_req, res) => {
const capabilities = await detectHostCapabilities();
const targets = await Promise.all(listTargets(capabilities).map(annotateTargetStatus));
res.json({ capabilities, targets });
}));
const requireInstallableTarget = (targetId) => {
const target = getTarget(targetId);
const adapter = getTargetAdapter(targetId);
if (!target || !adapter?.install) {
throw new ServerError(`Unknown or non-installable image-to-3D target: ${targetId}`, {
status: 400,
code: 'IMAGE_TO_3D_TARGET_NOT_INSTALLABLE',
});
}
return { target, adapter };
};
const sendTargetInstallStatus = async (targetId, res) => {
requireInstallableTarget(targetId);
const capabilities = await detectHostCapabilities();
const target = listTargets(capabilities).find((candidate) => candidate.id === targetId) || getTarget(targetId);
res.json({ capabilities, target: await annotateTargetStatus(target) });
};
const installQuerySchema = z.object({ repair: z.enum(['0', '1']).optional() });
/**
* SSE-driven target install/repair, shared by every registered target. The
* client opens a POST fetch stream and gets staged progress (`stage` → `log` →
* `complete` / `error`) while the target's adapter installs. Gated on hardware
* support and single-flighted per target; killed if the client navigates away.
* Only fires the real install on this explicit user request — never from boot
* (AGENTS.md no-cold-bootstrap policy). Mirrors imageGenSetup.js's `/flux2-install`.
*/
async function handleTargetInstall(targetId, target, adapter, repair, req, res) {
const { send, safeEnd } = openSseStream(res);
// `repair=1` re-runs setup over an existing install. That is the documented fix
// for a degraded install (e.g. TRELLIS.2's Metal texture bake — #2952): without
// it, "Repair install" would hit the already-installed short-circuit below and
// do nothing.
if (adapter.isInstalled() && !repair) {
send({ type: 'stage', stage: 'verify', message: `${target.label} already installed.` });
// "Installed" is not the same as "installed well" — surface any adapter
// warning (e.g. a degraded TRELLIS.2 texture bake) instead of a bare
// "nothing to do".
const state = adapter.describeInstallState ? await adapter.describeInstallState() : null;
(state?.warnings || []).forEach((message) => send({ type: 'log', stage: 'verify', message: `⚠️ ${message}` }));
send({ type: 'complete', message: 'Already installed — nothing to do.' });
return safeEnd();
}
// Refuse on unsupported hardware rather than clone a multi-GB install that can
// never run.
const capabilities = await detectHostCapabilities();
// `unavailableReason` is what `isTargetAvailable` asks anyway — take the reason
// directly so the refusal doesn't re-run the gate to name what blocked it.
const blockedReason = unavailableReason(targetId, capabilities);
if (blockedReason !== null) {
send({
type: 'error',
// The label, not the raw kebab-case code — this string is read by a human
// in the install log, and `requires-linux-host` doesn't tell them to use WSL2.
message: `This host cannot run ${target.label} (${unavailableReasonLabel(blockedReason)}). Install skipped.`,
});
return safeEnd();
}
if (installsInFlight.has(targetId)) {
send({ type: 'error', message: `A ${target.label} install is already running. Wait for it to finish or restart PortOS.` });
return safeEnd();
}
// Claim the in-flight slot synchronously, before any await, so two
// near-simultaneous requests for the same target can't both pass the check above.
installsInFlight.add(targetId);
// Server-console visibility for the multi-GB install (start / stages / outcome).
const installLog = createInstallLogger({ installer: target.label, target: targetId });
const emit = (event) => { installLog.onEvent(event); send(event); };
installLog.start();
// Disconnect bookkeeping wired BEFORE the env-resolution await below (the same
// hazard `lib/sseDownload.js` documents): that await can do a settings read plus
// a token-file read (e.g. TRELLIS.2's `resolveEnv`), and a client closing during
// it would otherwise land with no listener — the handler would go on to spawn a
// multi-GB clone with no kill path, leaving the in-flight slot pinned until it
// finished on its own and blocking every later Install click.
let currentKill = null;
let aborted = false;
// `adapter.install()` itself can run an async preflight (e.g. a toolchain
// probe) BEFORE returning { promise, kill } — during that window `currentKill`
// is still null, so a naive close handler would release the slot even though
// the adapter may already be spawning its first child. Track that window
// explicitly so the slot is held through it, and release exactly once via a
// single guarded function — never eagerly in the close handler for a window
// where nothing is killable yet AND an install may already be starting.
let installStarting = false;
let slotReleased = false;
const releaseSlot = () => {
if (slotReleased) return;
slotReleased = true;
installsInFlight.delete(targetId);
};
onClientDisconnect(req, res, () => {
aborted = true;
installLog.cancel();
// `close` also fires on normal completion; only a live handle means an
// install was actually mid-flight.
if (currentKill) {
// A real install is tracked in installsInFlight. Ask the child to
// terminate, but let the install promise's own `.finally()` (below)
// release the slot once the kill actually lands — releasing it here,
// before the child has exited, would let a second install for the same
// target start while the first is still shutting down.
currentKill();
} else if (!installStarting) {
// Nothing has spawned yet (still resolving env) — the code below will
// see `aborted` and bail without ever registering a `.finally()`, so
// release the slot here or it would leak forever.
releaseSlot();
}
// Else: `adapter.install()`'s own preflight is in flight and `kill` isn't
// available yet — do NOT release here. The code right after that await
// (below) sees `aborted` and calls `kill()` + `releaseSlot()` itself once
// it actually has something to kill.
safeEnd();
});
// Each target declares its own credential/env needs via `resolveEnv` — omit it
// for a target with nothing to resolve. Guarded because the SSE headers are
// already flushed by this point — a throw here (e.g. an unparseable
// settings.json) can't reach the error middleware as JSON, so it has to surface
// as a terminal `error` frame or the client hangs on a half-open stream.
let installEnv;
try {
installEnv = adapter.resolveEnv ? await adapter.resolveEnv() : undefined;
} catch (err) {
console.error(`❌ ${target.label} install could not resolve its environment: ${err.message}`);
emit({ type: 'error', message: `Could not prepare the ${target.label} install environment: ${err.message}` });
releaseSlot();
return safeEnd();
}
// The client hung up during the await — don't start a multi-GB install nobody
// is listening to.
if (aborted) return safeEnd();
installStarting = true;
const { promise, kill } = await adapter.install({ onEvent: emit, env: installEnv });
// The client may have hung up while the adapter ran its own async preflight
// (e.g. a toolchain probe) — terminate whatever it just spawned rather than
// let an orphaned install run unattended, and release the slot now that we
// finally have something to kill (the close handler deliberately did not).
if (aborted) {
kill();
releaseSlot();
return;
}
currentKill = kill;
promise
.then(() => installLog.success())
.catch((err) => {
// A transient network drop that survived the in-install retries: partial
// clones on disk are typically idempotent (resumable), so re-running Install
// resumes rather than restarts.
const hint = err?.transient
? ' This looks like a network hiccup — click Install again to resume (already-downloaded pieces are kept).'
: '';
emit({ type: 'error', message: `${err?.message || 'Install failed'}${hint}`, stage: err?.stage });
})
.finally(() => {
currentKill = null;
releaseSlot();
safeEnd();
});
}
router.get('/targets/:targetId/install', asyncHandler(async (req, res) => {
await sendTargetInstallStatus(req.params.targetId, res);
}));
router.post('/targets/:targetId/install', asyncHandler(async (req, res) => {
const { target, adapter } = requireInstallableTarget(req.params.targetId);
const { repair } = validateRequest(installQuerySchema, req.query);
await handleTargetInstall(req.params.targetId, target, adapter, repair === '1', req, res);
}));
// Compatibility alias for the pre-#3080 TRELLIS.2-specific install URL — existing
// client bookmarks/links keep working.
router.get('/trellis2/install', asyncHandler(async (_req, res) => {
await sendTargetInstallStatus('trellis2', res);
}));
router.post('/trellis2/install', asyncHandler(async (req, res) => {
const { target, adapter } = requireInstallableTarget('trellis2');
const { repair } = validateRequest(installQuerySchema, req.query);
await handleTargetInstall('trellis2', target, adapter, repair === '1', req, res);
}));
// ── Image-to-3D model records ─────────────────────────────────────────────
// Namespaced under /models so `/:id` never shadows the `/targets` and
// `/trellis2/install` routes above. These drive the /3d page: create a
// record from a gallery image (which kicks off the local render), poll the
// record for status, re-generate, delete, and download the exported GLB.
router.get('/models', asyncHandler(async (_req, res) => {
res.json(await listModels());
}));
/**
* Attach the target's render-option support to a model response.
*
* Projected at the response boundary, never stored: the detail view loads a RECORD
* rather than the target list, and still has to know which per-run knobs this record's
* target honors. Derived from the descriptor on every read, so it cannot go stale.
*
* Applied to EVERY response that returns a model, not just the GET. The client does
* `setRecord(next)` with the POST body, so a create/re-render response that omitted the
* field would blank it — flipping the disabled Quality control and its hint back on
* until the next poll restored them.
*/
const withRenderSupport = (model) => {
const supportsRenderOptions = renderOptionSupportFor(model.target);
return supportsRenderOptions ? { ...model, supportsRenderOptions } : model;
};
router.post('/models', asyncHandler(async (req, res) => {
const input = validateRequest(createModelSchema, req.body);
const model = await createModel(input);
res.status(202).json(withRenderSupport(model));
}));
router.get('/models/:id/asset', asyncHandler(async (req, res) => {
const { path, filename } = await getModelAsset(req.params.id);
streamAttachment(res, createReadStream(path), {
filename,
contentType: 'model/gltf-binary',
failure: new ServerError('Mesh file not found', { status: 404, code: 'ASSET_MISSING' }),
label: 'Image-to-3D asset',
});
}));
// The decoder's pre-decimation mesh. Registered before `/models/:id` so the more
// specific path wins, and kept off `/asset` because it is a different artifact
// with a different failure mode (see getModelFullMesh) rather than a variant of
// the served GLB.
router.get('/models/:id/full-mesh', asyncHandler(async (req, res) => {
const { path, filename } = await getModelFullMesh(req.params.id);
streamAttachment(res, createReadStream(path), {
filename,
contentType: 'model/obj',
failure: new ServerError('Mesh file not found', { status: 404, code: 'ASSET_MISSING' }),
label: 'Image-to-3D asset',
});
}));
// ── AR Quick Look (USDZ) ──────────────────────────────────────────────────
// The conversion runs in the VIEWER (three's USDZExporter over the scene it has
// already parsed and decoded), not on the server — PortOS ships no USD toolchain
// and would otherwise have to re-decode the GLB and its textures in Node to
// produce a file the browser already holds in memory. The server's job is to
// persist the result: a blob URL is not reliably openable by AR Quick Look and
// does not survive a reload, so the bytes are stored as a sibling artifact and
// re-served on every later visit instead of being re-exported.
/**
* A raw USDZ body. `express.json()` is mounted app-wide but only claims
* `application/json`, so these content types reach the route unparsed. The limit
* is enforced here (a 413 from the parser) AND in `saveModelUsdz` — the parser
* guards memory before the body is buffered, the service guards the invariant for
* any other caller.
*/
const usdzBody = raw({
type: ['model/vnd.usdz+zip', 'application/octet-stream'],
limit: USDZ_MAX_BYTES,
});
router.post('/models/:id/usdz', usdzBody, asyncHandler(async (req, res) => {
// Body-shape validation is byte-level (non-empty, under cap, zip magic), not a
// Zod object schema — there is no JSON here to describe.
const model = await saveModelUsdz(req.params.id, Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0));
res.status(201).json(withRenderSupport(model));
}));
// Served `inline`, unlike the GLB/OBJ downloads: AR Quick Look will not engage on
// an attachment response, and it needs the exact `model/vnd.usdz+zip` type.
router.get('/models/:id/usdz', asyncHandler(async (req, res) => {
const { path, filename } = await getModelUsdz(req.params.id);
streamAttachment(res, createReadStream(path), {
filename,
contentType: 'model/vnd.usdz+zip',
disposition: 'inline',
failure: new ServerError('USDZ file not found', { status: 404, code: 'ASSET_MISSING' }),
label: 'Image-to-3D AR export',
});
}));
router.get('/models/:id', asyncHandler(async (req, res) => {
const model = await getModel(req.params.id);
if (!model) throw new ServerError('Image-to-3D model not found', { status: 404, code: 'NOT_FOUND' });
res.json(withRenderSupport(model));
}));
router.post('/models/:id/generate', asyncHandler(async (req, res) => {
// Re-render accepts the same per-run knobs as create; they apply to this run
// only and are recorded on its run entry.
const options = validateRequest(renderOptionsSchema, req.body ?? {});
const model = await startGeneration(req.params.id, { options });
res.status(202).json(withRenderSupport(model));
}));
router.delete('/models/:id', asyncHandler(async (req, res) => {
res.json(await deleteModel(req.params.id));
}));
export default router;