@nodetool-ai/websocket 0.7.0-rc.22 → 0.8.1

package/dist/http-api.js

@@ -1,30 +1,46 @@
 import { createServer } from "node:http";
 import { gzipSync } from "node:zlib";
-import { mkdir, writeFile, stat, readFile } from "node:fs/promises";
-import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { once } from "node:events";
+import { readFileSync, readdirSync, existsSync, promises as fsp } from "node:fs";
 import nodePath from "node:path";
-import { createLogger, buildAssetUrl } from "@nodetool-ai/config";
+import os from "node:os";
+import { GZIP_THRESHOLD } from "./lib/compression.js";
+import { withCacheBuster } from "./lib/example-thumbnail.js";
+import { loadExampleGraph, deriveExampleAssetsDir } from "./example-workflows.js";
+import { createLogger } from "@nodetool-ai/config";
 import { workflowToDsl } from "@nodetool-ai/dsl";
-import { Workflow, WorkflowVersion, Job, Asset } from "@nodetool-ai/models";
-import { loadPythonPackageMetadata, NodeRegistry } from "@nodetool-ai/node-sdk";
-import { registerBaseNodes } from "@nodetool-ai/base-nodes";
-import { registerElevenLabsNodes } from "@nodetool-ai/elevenlabs-nodes";
-import { registerTransformersJsNodes } from "@nodetool-ai/transformers-js-nodes";
-import { registerFalNodes } from "@nodetool-ai/fal-nodes";
-import { registerKieNodes } from "@nodetool-ai/kie-nodes";
-import { registerReplicateNodes } from "@nodetool-ai/replicate-nodes";
-import { PythonNodeExecutor, PythonStdioBridge } from "@nodetool-ai/runtime";
-import { WorkflowRunner } from "@nodetool-ai/kernel";
+import { Workflow, WorkflowCollaborator, Asset, Project } from "@nodetool-ai/models";
+import { loadPythonPackageMetadata } from "@nodetool-ai/node-sdk";
+import { bootstrapNodeRegistry } from "./node-registry-setup.js";
+import { PythonNodeExecutor, createPythonBridge, logPythonWorkerStderr } from "@nodetool-ai/runtime";
+import { createAssetModelInterface, updateAssetBytesModelInterface } from "./lib/asset-model-interface.js";
+import { probeAssetDurationSeconds } from "./lib/asset-duration.js";
+import { verdictSchema } from "@nodetool-ai/protocol";
+import { cancelDebugSession, debugSessions, peekDebugSession, runWorkflow, submitEscalationVerdict } from "@nodetool-ai/execution/service";
+import { resolveWorkflowWorkspace } from "./lib/workflow-workspace.js";
 import { handleOpenAIRequest } from "./openai-api.js";
 import { handleOAuthRequest } from "./oauth-api.js";
 import { createStorageHandler } from "./storage-api.js";
 import { handleFileRequest } from "./file-api.js";
+import { storeAssetWithThumbnail, storeAssetFileWithThumbnail, generateThumbnailForStoredAsset } from "./lib/thumbnail.js";
+import { FileStorageAdapter } from "@nodetool-ai/storage";
+import { getAssetAdapter, getTempAdapter } from "./lib/storage.js";
+import { probeHasAudio, extractAudio, MediaToolingMissingError } from "./lib/media.js";
+import { packWorkflowsBundle, importWorkflowBundle } from "./lib/workflow-bundle.js";
+import { listExampleApps } from "./lib/example-apps.js";
+import { createWorkflow, deleteWorkflow, updateWorkflow, WorkflowServiceError } from "./lib/workflow-service.js";
+import { isNonEmptyString, isObjectLike, isRecord, isString } from "./lib/wire-values.js";
+import { assetCreateBodySchema, escalationVerdictBodySchema, workflowRequestBodySchema, workflowRunBodySchema, workflowsExportBundleBodySchema } from "./http-body-schemas.js";
 const log = createLogger("nodetool.websocket.http");
 // ── Content type to file extension mapping ─────────────────────────
 // Asset filename + storage-path helpers live in `./lib/asset-paths.ts` so the
 // tRPC router can import them without dragging in the full http-api module
 // graph. Re-exported here for any remaining REST callers.
-import { getAssetFileName, getAssetStoragePath } from "./lib/asset-paths.js";
+import { getAssetFileName, getAssetStorageKey, getAssetStoragePath, retrieveAssetBytes, localAssetPath, normalizeAssetContentType } from "./lib/asset-paths.js";
+import { resolveAssetBytesForExport } from "./lib/asset-export.js";
+import { toAssetResponse } from "./lib/asset-response.js";
+import { scheduleVideoProxy } from "./lib/video-proxy.js";
+export { toAssetResponse };
 export { getAssetFileName, getAssetStoragePath };
 // Lazily created storage handler — recreated if options change
 let _storageHandler = null;
@@ -37,23 +53,18 @@ function getStorageHandler(opts) {
     }
     return _storageHandler;
 }
-async function getWorkflowRuntimeEnvironment(options = {}) {
+export async function getWorkflowRuntimeEnvironment(options = {}) {
     if (!workflowRuntimePromise) {
         workflowRuntimePromise = (async () => {
-            const registry = options.registry ?? new NodeRegistry();
-            if (!options.registry) {
-                registry.loadPythonMetadata({
-                    roots: options.metadataRoots,
-                    maxDepth: options.metadataMaxDepth ?? 8
-                });
-                registerBaseNodes(registry);
-                registerElevenLabsNodes(registry);
-                registerTransformersJsNodes(registry);
-                registerFalNodes(registry);
-                registerKieNodes(registry);
-                registerReplicateNodes(registry);
+            const bootstrapOptions = {
+                metadataMaxDepth: options.metadataMaxDepth ?? 8,
+                log
+            };
+            if (options.metadataRoots) {
+                bootstrapOptions.metadataRoots = options.metadataRoots;
             }
-            const pythonBridge = new PythonStdioBridge({
+            const registry = options.registry ?? (await bootstrapNodeRegistry(bootstrapOptions));
+            const pythonBridge = createPythonBridge({
                 workerArgs: process.env["NODETOOL_WORKER_NAMESPACES"]
                     ? ["--namespaces", process.env["NODETOOL_WORKER_NAMESPACES"]]
                     : []
@@ -70,10 +81,13 @@ async function getWorkflowRuntimeEnvironment(options = {}) {
             let pythonBridgeReady = false;
             pythonBridge.on("stderr", (msg) => {
                 for (const line of msg.split("\n")) {
-                    if (line.trim())
-                        log.debug(`[python-worker] ${line}`);
+                    logPythonWorkerStderr(line, log);
                 }
             });
+            pythonBridge.on("error", (err) => {
+                log.error(`HTTP API Python bridge protocol error: ${err.message}`);
+                pythonBridgeReady = false;
+            });
             pythonBridge.on("exit", (code) => {
                 log.warn(`HTTP API Python worker exited with code ${code}`);
                 pythonBridgeReady = false;
@@ -118,7 +132,7 @@ async function getWorkflowRuntimeEnvironment(options = {}) {
                         .getNodeMetadata()
                         .find((n) => n.node_type === node.type);
                     const props = (node.properties ?? node.data ?? {});
-                    return new PythonNodeExecutor(pythonBridge, node.type, props, Object.fromEntries((meta?.outputs ?? []).map((o) => [o.name, o.type.type])), meta?.required_settings ?? []);
+                    return new PythonNodeExecutor(pythonBridge, node.type, props, Object.fromEntries((meta?.outputs ?? []).map((o) => [o.name, o.type.type])), meta?.required_settings ?? [], node.id, meta?.requires_vram_gb);
                 }
                 if (registry.getMetadata(node.type) && !registry.has(node.type)) {
                     const stderrSummary = pythonBridge.getRecentStderrSummary?.() ?? null;
@@ -131,14 +145,30 @@ async function getWorkflowRuntimeEnvironment(options = {}) {
                 }
                 return registry.resolve(node);
             };
-            return { registry, pythonBridge, ensurePythonBridge, resolveExecutor };
+            return {
+                registry,
+                pythonBridge,
+                ensurePythonBridge,
+                resolveExecutor,
+                // Asset persistence for the run's ProcessingContext — an Output node
+                // that stores an image needs it on every host, not just chat turns.
+                configureContext: (context) => {
+                    context.setModelInterfaces({
+                        createAsset: createAssetModelInterface,
+                        updateAssetBytes: updateAssetBytesModelInterface
+                    });
+                },
+                // The stores the run reads through. `asset://<id>` inputs — every
+                // uploaded image wired into a graph — live in the asset store; without
+                // it the reference resolves to nothing and the node runs on an empty
+                // input. Same pair the streaming WebSocket runner uses.
+                assetStorage: getAssetAdapter(),
+                storage: getTempAdapter()
+            };
         })();
     }
     return workflowRuntimePromise;
 }
-// Rate-limit tracking for autosave: maps workflow_id -> last autosave timestamp (ms)
-const lastAutosaveTime = new Map();
-const AUTOSAVE_RATE_LIMIT_MS = 30_000;
 function normalizePath(pathname) {
     if (pathname.length > 1 && pathname.endsWith("/")) {
         return pathname.slice(0, -1);
@@ -160,18 +190,39 @@ function errorResponse(status, detail) {
 export function getUserId(request, headerName) {
     return (request.headers.get(headerName) ?? request.headers.get("x-user-id") ?? "1");
 }
-async function parseJsonBody(request) {
+/** The raw JSON body, or null when there is nothing readable to parse. */
+async function readJsonBody(request) {
     const contentType = request.headers.get("content-type") ?? "";
     if (!contentType.toLowerCase().includes("application/json")) {
         return null;
     }
     try {
-        return (await request.json());
+        return await request.json();
     }
     catch {
         return null;
     }
 }
+/**
+ * Parse a request body once, at the route boundary.
+ *
+ * `null` means "no body the route can read": a non-JSON content type,
+ * unparseable JSON, or a falsy JSON value (`null`, `0`, `""`) — the cases
+ * every route already answered with its own 400 via `if (!body)`.
+ *
+ * A truthy non-object body (a number, a string, an array) parses as a record
+ * with every field absent, which is exactly what the routes saw when they read
+ * `.name` off a number, so their own error messages still fire.
+ */
+function parseBodyValue(raw, schema) {
+    if (!raw) {
+        return null;
+    }
+    return schema.parse(isRecord(raw) ? raw : {});
+}
+async function parseBody(request, schema) {
+    return parseBodyValue(await readJsonBody(request), schema);
+}
 export function toWorkflowResponse(workflow) {
     return {
         id: workflow.id,
@@ -192,9 +243,11 @@ export function toWorkflowResponse(workflow) {
         path: workflow.path,
         run_mode: workflow.run_mode,
         workspace_id: workflow.workspace_id,
+        project_id: workflow.project_id,
         required_providers: null,
         required_models: null,
         html_app: workflow.html_app,
+        app_doc: workflow.app_doc ?? null,
         etag: workflow.getEtag()
     };
 }
@@ -276,236 +329,89 @@ export function parseLimit(url, defaultLimit = 100) {
         return defaultLimit;
     return Math.min(parsed, 500);
 }
-async function createWorkflow(body, userId) {
-    if (!body || typeof body.name !== "string") {
-        throw new Error("Invalid workflow");
-    }
-    if (!body.graph ||
-        !Array.isArray(body.graph.nodes) ||
-        !Array.isArray(body.graph.edges)) {
-        throw new Error("graph is required and must have nodes and edges arrays");
-    }
-    const graph = body.graph;
-    return (await Workflow.create({
-        user_id: userId,
-        name: body.name,
-        tool_name: body.tool_name ?? null,
-        package_name: body.package_name ?? null,
-        path: body.path ?? null,
-        tags: body.tags ?? [],
-        description: body.description ?? "",
-        thumbnail: body.thumbnail ?? null,
-        thumbnail_url: body.thumbnail_url ?? null,
-        access: body.access === "public" ? "public" : "private",
-        graph,
-        settings: body.settings ?? null,
-        run_mode: body.run_mode ?? "workflow",
-        workspace_id: body.workspace_id ?? null,
-        html_app: body.html_app ?? null
-    }));
-}
-async function updateWorkflow(id, body, userId) {
-    if (!body || typeof body.name !== "string") {
-        throw new Error("Invalid workflow");
-    }
-    if (!body.graph ||
-        !Array.isArray(body.graph.nodes) ||
-        !Array.isArray(body.graph.edges)) {
-        throw new Error("graph is required and must have nodes and edges arrays");
-    }
-    const graph = body.graph;
-    const existing = (await Workflow.get(id));
-    if (existing && existing.user_id !== userId) {
-        throw new Error("Workflow not found");
-    }
-    if (existing) {
-        existing.name = body.name;
-        existing.tool_name = body.tool_name ?? null;
-        existing.description = body.description ?? "";
-        existing.tags = body.tags ?? [];
-        existing.package_name = body.package_name ?? null;
-        if (body.thumbnail !== undefined)
-            existing.thumbnail = body.thumbnail;
-        existing.access = body.access === "public" ? "public" : "private";
-        existing.graph = graph;
-        existing.settings = body.settings ?? null;
-        if (body.run_mode !== undefined && body.run_mode !== null)
-            existing.run_mode = body.run_mode;
-        existing.workspace_id = body.workspace_id ?? null;
-        existing.html_app = body.html_app ?? null;
-        await existing.save();
-        return existing;
-    }
-    // Upsert: create the workflow if it doesn't exist
-    return (await Workflow.create({
-        id,
-        user_id: userId,
-        name: body.name,
-        tool_name: body.tool_name ?? null,
-        package_name: body.package_name ?? null,
-        path: body.path ?? null,
-        tags: body.tags ?? [],
-        description: body.description ?? "",
-        thumbnail: body.thumbnail ?? null,
-        thumbnail_url: body.thumbnail_url ?? null,
-        access: body.access === "public" ? "public" : "private",
-        graph: body.graph,
-        settings: body.settings ?? null,
-        run_mode: body.run_mode ?? "workflow",
-        workspace_id: body.workspace_id ?? null,
-        html_app: body.html_app ?? null
-    }));
-}
-export async function handleWorkflowRun(request, workflowId, options = {}) {
+export async function handleWorkflowRun(request, workflowId, options = {}, 
+/** Return the full debug report (summary + verdict) instead of the run row. */
+debug = false) {
     if (request.method !== "POST") {
         return errorResponse(405, "Method not allowed");
     }
     const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
-    const workflow = await Workflow.find(userId, workflowId);
-    if (!workflow) {
-        return errorResponse(404, "Workflow not found");
-    }
-    const runMode = workflow.run_mode ?? "workflow";
-    if (runMode !== "workflow") {
-        return errorResponse(400, `Workflow run mode "${runMode}" is not supported by the standalone backend`);
-    }
-    const body = await parseJsonBody(request);
-    const params = body?.params ?? {};
-    const graph = workflow.getGraph();
-    const runnableGraph = {
-        nodes: graph.nodes.map((node) => {
-            const record = node;
-            return {
-                ...record,
-                id: String(record.id ?? ""),
-                type: String(record.type ?? ""),
-                properties: (record.properties ?? record.data ?? {})
-            };
-        }),
-        edges: graph.edges.map((edge) => {
-            const record = edge;
-            return {
-                ...record,
-                id: typeof record.id === "string" || record.id == null
-                    ? record.id
-                    : String(record.id),
-                source: String(record.source ?? ""),
-                target: String(record.target ?? ""),
-                sourceHandle: String(record.sourceHandle ?? ""),
-                targetHandle: String(record.targetHandle ?? ""),
-                edge_type: record.edge_type === "control" ? "control" : "data"
-            };
-        })
+    const body = await parseBody(request, workflowRunBodySchema);
+    const runOptions = {
+        workflowId,
+        userId,
+        debug,
+        // Lazy: a nonexistent workflow 404s before the runtime bootstraps — a
+        // cold-start bootstrap failure must not turn that into a 500.
+        environment: () => getWorkflowRuntimeEnvironment(options),
+        params: body?.params ?? {},
+        projectId: body?.project_id ?? null,
+        background: body?.background ?? false,
+        interactive: body?.interactive === true,
+        // The server's own import site, so a test that mocks it still governs.
+        resolveWorkspace: resolveWorkflowWorkspace
     };
-    const runtime = await getWorkflowRuntimeEnvironment(options);
-    const hasPythonNode = runnableGraph.nodes.some((node) => {
-        const nodeType = typeof node.type === "string" ? node.type : "";
-        return (nodeType !== "" &&
-            Boolean(runtime.registry.getMetadata(nodeType)) &&
-            !runtime.registry.has(nodeType));
-    });
-    if (hasPythonNode) {
-        await runtime.ensurePythonBridge();
-    }
-    const job = await Job.create({
-        workflow_id: workflowId,
-        user_id: userId,
-        status: "running",
-        params,
-        graph: runnableGraph
-    });
-    const runner = new WorkflowRunner(job.id, {
-        resolveExecutor: (node) => runtime.resolveExecutor(node)
-    });
-    const result = await runner.run({ job_id: job.id, workflow_id: workflowId, params }, runnableGraph);
-    if (result.status === "completed") {
-        job.markCompleted();
+    if (body?.max_decisions !== undefined) {
+        runOptions.maxDecisions = body.max_decisions;
     }
-    else if (result.status === "cancelled") {
-        job.markCancelled();
+    if (body?.max_retries_per_node !== undefined) {
+        runOptions.maxRetriesPerNode = body.max_retries_per_node;
     }
-    else {
-        job.markFailed(result.error ?? "Workflow run failed");
+    if (body?.decision_timeout_ms !== undefined) {
+        runOptions.decisionTimeoutMs = body.decision_timeout_ms;
     }
-    await job.save();
-    return jsonResponse({
-        job_id: job.id,
-        workflow_id: workflowId,
-        status: result.status,
-        outputs: result.outputs,
-        error: result.error ?? null,
-        message_count: result.messages.length,
-        background: body?.background ?? false
-    });
-}
-export async function handleWorkflowAutosave(request, workflowId, options) {
-    if (request.method !== "POST" && request.method !== "PUT") {
-        return errorResponse(405, "Method not allowed");
+    const outcome = await runWorkflow(runOptions);
+    if (outcome.kind === "error") {
+        return errorResponse(outcome.status, outcome.detail);
     }
+    return jsonResponse(outcome.payload);
+}
+/**
+ * `/api/debug/sessions/:id[/verdict|/cancel]` — the caller's half of an
+ * interactive run. GET peeks at the session, `verdict` answers the parked
+ * escalation and waits for the next event, `cancel` cancels the run and
+ * returns the final report.
+ */
+export async function handleDebugSessionRequest(request, sessionId, subPath, options = {}) {
     const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
-    const workflow = (await Workflow.get(workflowId));
-    if (!workflow)
-        return errorResponse(404, "Workflow not found");
-    if (workflow.user_id !== userId)
-        return errorResponse(404, "Workflow not found");
-    const body = await parseJsonBody(request);
-    if (!body || !body.graph) {
-        return errorResponse(400, "Invalid body: graph is required");
-    }
-    const graph = body.graph;
-    const force = body?.force === true;
-    const maxVersions = typeof body?.max_versions === "number" ? body.max_versions : 10;
-    // Rate-limit: skip if last autosave < 30s ago and force is false
-    if (!force) {
-        const last = lastAutosaveTime.get(workflowId);
-        if (last !== undefined && Date.now() - last < AUTOSAVE_RATE_LIMIT_MS) {
-            return jsonResponse({
-                version: null,
-                message: "Autosave skipped (rate limited)",
-                skipped: true
-            });
+    // Session existence (scoped to the caller) is checked before anything else —
+    // a malformed verdict against a foreign or expired session answers 404, not
+    // 400, exactly as it did when this handler owned the registry.
+    if (!debugSessions.get(sessionId, userId)) {
+        return errorResponse(404, "Debug session not found");
+    }
+    const answer = (outcome) => outcome.kind === "error"
+        ? errorResponse(outcome.status, outcome.detail)
+        : jsonResponse(outcome.payload);
+    if (subPath === null) {
+        if (request.method !== "GET") {
+            return errorResponse(405, "Method not allowed");
         }
+        return answer(peekDebugSession(sessionId, userId));
     }
-    workflow.graph = graph;
-    if (body.name !== undefined)
-        workflow.name = body.name;
-    if (body.description !== undefined)
-        workflow.description = body.description;
-    if (body.access === "public" || body.access === "private")
-        workflow.access = body.access;
-    await workflow.save();
-    lastAutosaveTime.set(workflowId, Date.now());
-    // Create a version and prune old ones if WorkflowVersion table is available
-    let version = null;
-    try {
-        const nextVer = await WorkflowVersion.nextVersion(workflowId);
-        const wv = new WorkflowVersion({
-            workflow_id: workflowId,
-            user_id: userId,
-            graph,
-            version: nextVer,
-            save_type: "autosave",
-            name: workflow.name,
-            description: workflow.description
-        });
-        await wv.save();
-        version = {
-            id: wv.id,
-            version: wv.version,
-            workflow_id: wv.workflow_id,
-            save_type: wv.save_type,
-            created_at: wv.created_at
-        };
-        await WorkflowVersion.pruneOldVersions(workflowId, maxVersions);
+    if (subPath === "verdict") {
+        if (request.method !== "POST") {
+            return errorResponse(405, "Method not allowed");
+        }
+        const body = await parseBody(request, escalationVerdictBodySchema);
+        if (!body || body.escalation_id === undefined) {
+            return errorResponse(400, "Body must carry escalation_id and verdict");
+        }
+        const parsed = verdictSchema.safeParse(body.verdict);
+        if (!parsed.success) {
+            return errorResponse(400, `Invalid verdict: ${parsed.error.issues
+                .map((issue) => issue.message)
+                .join("; ")}`);
+        }
+        return answer(await submitEscalationVerdict(sessionId, userId, body.escalation_id, parsed.data));
     }
-    catch {
-        // non-fatal — version table may not exist
+    if (subPath === "cancel") {
+        if (request.method !== "POST") {
+            return errorResponse(405, "Method not allowed");
+        }
+        return answer(await cancelDebugSession(sessionId, userId));
     }
-    return jsonResponse({
-        version,
-        message: "Autosaved successfully",
-        skipped: false
-    });
+    return errorResponse(404, "Not found");
 }
 // ── Workflow tools ─────────────────────────────────────────────────────
 export async function handleWorkflowTools(request, options) {
@@ -528,13 +434,6 @@ export async function handleWorkflowTools(request, options) {
 // ── Workflow examples ──────────────────────────────────────────────────
 /** URL prefix for example workflow thumbnail images served by this API. */
 const EXAMPLES_THUMBNAILS_PREFIX = "/api/workflows/examples/thumbnails/";
-/**
- * Given an `examplesDir` (e.g. `.../nodetool/examples/nodetool-base`), return
- * the sibling assets directory (`.../nodetool/assets/nodetool-base`).
- */
-function deriveAssetsDir(examplesDir) {
-    return nodePath.join(nodePath.dirname(nodePath.dirname(examplesDir)), "assets", nodePath.basename(examplesDir));
-}
 /**
  * Read example workflow metadata from a directory of JSON files.
  * Returns lightweight objects (no graph data) suitable for the /examples list.
@@ -544,11 +443,10 @@ function deriveAssetsDir(examplesDir) {
  * pointing to `/api/workflows/examples/thumbnails/<name>` is set so the
  * frontend can display the pre-generated JPG thumbnails.
  */
-function buildExamplesFromDir(examplesDir) {
+function buildExamplesFromDir(examplesDir, examplesAssetsFallbackDir) {
     if (!existsSync(examplesDir))
         return [];
-    // Derive the assets directory from the examples directory.
-    const assetsDir = deriveAssetsDir(examplesDir);
+    const assetsDir = deriveExampleAssetsDir(examplesDir, examplesAssetsFallbackDir);
     const now = new Date().toISOString();
     const workflows = [];
     let files;
@@ -565,13 +463,16 @@ function buildExamplesFromDir(examplesDir) {
         try {
             const raw = readFileSync(nodePath.join(examplesDir, file), "utf8");
             const parsed = JSON.parse(raw);
-            const name = typeof parsed.name === "string"
+            const name = isString(parsed.name)
                 ? parsed.name
                 : file.replace(/\.json$/i, "");
-            // Point thumbnail_url to the served JPG when the file exists in assets.
+            // Point thumbnail_url to the served JPG when the file exists in
+            // assets. withCacheBuster() appends ?v=<md5-8> so the browser cache
+            // invalidates whenever the JPG is regenerated.
             const jpgFile = `${name}.jpg`;
-            const thumbnailUrl = existsSync(nodePath.join(assetsDir, jpgFile))
-                ? `${EXAMPLES_THUMBNAILS_PREFIX}${encodeURIComponent(jpgFile)}`
+            const jpgPath = nodePath.join(assetsDir, jpgFile);
+            const thumbnailUrl = existsSync(jpgPath)
+                ? withCacheBuster(`${EXAMPLES_THUMBNAILS_PREFIX}${encodeURIComponent(jpgFile)}`, jpgPath)
                 : null;
             workflows.push({
                 id: file,
@@ -580,23 +481,24 @@ function buildExamplesFromDir(examplesDir) {
                 updated_at: now,
                 name,
                 tool_name: null,
-                description: typeof parsed.description === "string" ? parsed.description : "",
-                tags: Array.isArray(parsed.tags)
-                    ? parsed.tags.filter((t) => typeof t === "string")
-                    : [],
+                description: isString(parsed.description) ? parsed.description : "",
+                tags: Array.isArray(parsed.tags) ? parsed.tags.filter(isString) : [],
                 thumbnail: thumbnailUrl ? jpgFile : null,
                 thumbnail_url: thumbnailUrl,
                 graph: { nodes: [], edges: [] },
                 input_schema: null,
                 output_schema: null,
                 settings: null,
-                package_name: typeof parsed.package_name === "string" ? parsed.package_name : null,
+                package_name: isString(parsed.package_name)
+                    ? parsed.package_name
+                    : null,
                 path: null,
                 run_mode: null,
                 workspace_id: null,
                 required_providers: null,
                 required_models: null,
                 html_app: null,
+                app_doc: isObjectLike(parsed.app_doc) ? parsed.app_doc : null,
                 etag: null
             });
         }
@@ -606,10 +508,10 @@ function buildExamplesFromDir(examplesDir) {
     }
     return workflows;
 }
-function buildExampleWorkflows(options) {
+export function buildExampleWorkflows(options) {
     // If a static examples directory is configured, use it directly — no Python needed.
     if (options.examplesDir) {
-        return buildExamplesFromDir(options.examplesDir);
+        return buildExamplesFromDir(options.examplesDir, options.examplesAssetsFallbackDir);
     }
     const loaded = loadPythonPackageMetadata({
         roots: options.metadataRoots,
@@ -644,29 +546,13 @@ function buildExampleWorkflows(options) {
                 required_providers: null,
                 required_models: null,
                 html_app: null,
+                app_doc: null,
                 etag: null
             });
         }
     }
     return workflows;
 }
-function loadExampleGraph(packageName, exampleName, options) {
-    const loaded = loadPythonPackageMetadata({
-        roots: options.metadataRoots,
-        maxDepth: options.metadataMaxDepth
-    });
-    const pkg = loaded.packages.find((p) => p.name === packageName);
-    if (!pkg?.sourceFolder)
-        return null;
-    const examplePath = nodePath.join(pkg.sourceFolder, "nodetool", "examples", packageName, `${exampleName}.json`);
-    try {
-        const raw = readFileSync(examplePath, "utf8");
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
 export async function handleWorkflowExamples(request, options) {
     if (request.method !== "GET") {
         return errorResponse(405, "Method not allowed");
@@ -674,6 +560,27 @@ export async function handleWorkflowExamples(request, options) {
     const workflows = buildExampleWorkflows(options);
     return jsonResponse({ workflows, next: null });
 }
+/**
+ * GET /api/workflows/examples/:package/:name — one example workflow, graph
+ * included. The `get_example_workflow` agent tool and the `nodetool` object
+ * model (`nodetool.workflows.example`) call this to feed graphs into
+ * `copyFrom`; the create-from-example flow stays on POST /api/workflows.
+ */
+export async function handleWorkflowExampleByName(request, packageName, exampleName, options) {
+    if (request.method !== "GET") {
+        return errorResponse(405, "Method not allowed");
+    }
+    const example = loadExampleGraph(packageName, exampleName, {
+        examplesDir: options.examplesDir,
+        examplesAssetsFallbackDir: options.examplesAssetsFallbackDir,
+        metadataRoots: options.metadataRoots,
+        metadataMaxDepth: options.metadataMaxDepth
+    });
+    if (!example) {
+        return errorResponse(404, `Example '${exampleName}' not found in package '${packageName}'`);
+    }
+    return jsonResponse(example);
+}
 export async function handleWorkflowExamplesSearch(request, options) {
     if (request.method !== "GET") {
         return errorResponse(405, "Method not allowed");
@@ -706,7 +613,7 @@ export async function handleWorkflowExamplesThumbnail(request, filename, options
         return errorResponse(404, "Examples not configured");
     }
     // Derive the assets directory from the examples directory.
-    const assetsDir = deriveAssetsDir(options.examplesDir);
+    const assetsDir = deriveExampleAssetsDir(options.examplesDir, options.examplesAssetsFallbackDir);
     // Prevent path traversal — only allow a plain filename (no slashes).
     const safe = nodePath.basename(filename);
     const safeLower = safe.toLowerCase();
@@ -746,69 +653,6 @@ export async function handleWorkflowExamplesThumbnail(request, filename, options
         }
     });
 }
-// ── Workflow app page ──────────────────────────────────────────────────
-export async function handleWorkflowApp(request, workflowId, options) {
-    if (request.method !== "GET") {
-        return errorResponse(405, "Method not allowed");
-    }
-    const baseUrl = options.baseUrl ?? "http://127.0.0.1:7777";
-    const html = `<!DOCTYPE html><html><head><title>Workflow App</title>
-<script>window.WORKFLOW_ID=${JSON.stringify(workflowId)};window.API_URL=${JSON.stringify(baseUrl)};</script>
-</head><body><div id="app"></div></body></html>`;
-    return new Response(html, {
-        status: 200,
-        headers: { "content-type": "text/html" }
-    });
-}
-// ── Workflow generate-name ─────────────────────────────────────────────
-/**
- * Generate a descriptive name for a workflow based on its node types.
- * The Python backend uses an LLM for this; the TS standalone mode derives
- * a name from the workflow graph's node types instead.
- *
- * Node types follow the pattern `<root>.<category>[.<subcategory>...]`,
- * e.g. `nodetool.text.Generate`. We collect unique category segments
- * (parts[1]) to form a human-readable label.
- */
-function deriveWorkflowName(workflow) {
-    const graph = workflow.graph;
-    const nodes = graph?.nodes ?? [];
-    if (nodes.length === 0) {
-        return workflow.name || "Untitled Workflow";
-    }
-    // Collect unique category segments from node types (second dotted segment).
-    const categories = new Set();
-    for (const n of nodes) {
-        if (typeof n.type === "string") {
-            const parts = n.type.split(".");
-            // Require at least root.category format.
-            if (parts.length >= 2 && parts[1]) {
-                categories.add(parts[1]);
-            }
-        }
-    }
-    const segments = Array.from(categories).slice(0, 3);
-    if (segments.length === 0) {
-        return workflow.name || "Untitled Workflow";
-    }
-    const label = segments
-        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
-        .join(" + ");
-    return `${label} Workflow`;
-}
-export async function handleWorkflowGenerateName(request, workflowId, options) {
-    if (request.method !== "POST") {
-        return errorResponse(405, "Method not allowed");
-    }
-    const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
-    const workflow = (await Workflow.get(workflowId));
-    if (!workflow)
-        return errorResponse(404, "Workflow not found");
-    if (workflow.user_id !== userId)
-        return errorResponse(404, "Workflow not found");
-    const name = deriveWorkflowName(workflow);
-    return jsonResponse({ name });
-}
 // ── Workflow DSL export (stub) ─────────────────────────────────────────
 export async function handleWorkflowDslExport(request, workflowId, options) {
     if (request.method !== "GET") {
@@ -841,107 +685,178 @@ export async function handleWorkflowDslExport(request, workflowId, options) {
         return errorResponse(400, message);
     }
 }
-// ── Workflow Gradio export (stub) ──────────────────────────────────────
-export async function handleWorkflowGradioExport(request, workflowId, options) {
-    if (request.method !== "POST") {
-        return errorResponse(405, "Method not allowed");
-    }
-    const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
+// ── Workflow bundle export/import (.nodetool) ──────────────────────────
+export { resolveAssetBytesForExport };
+async function loadBundledWorkflow(workflowId, userId) {
     const workflow = (await Workflow.get(workflowId));
-    if (!workflow)
-        return errorResponse(404, "Workflow not found");
-    if (workflow.user_id !== userId) {
-        return errorResponse(404, "Workflow not found");
+    if (!workflow) {
+        return { error: errorResponse(404, `Workflow not found: ${workflowId}`) };
+    }
+    if (workflow.access !== "public" && workflow.user_id !== userId) {
+        return { error: errorResponse(404, `Workflow not found: ${workflowId}`) };
+    }
+    if (!workflow.graph) {
+        return { error: errorResponse(400, "Workflow has no graph to export") };
     }
-    // Gradio export requires the Python Gradio library; return 501 in standalone TS mode.
-    return errorResponse(501, "Workflow Gradio export is not available in standalone mode");
-}
-// ── Workflow versions ──────────────────────────────────────────────────
-function toVersionResponse(v) {
     return {
-        id: v.id,
-        workflow_id: v.workflow_id,
-        user_id: v.user_id,
-        name: v.name,
-        description: v.description,
-        graph: v.graph,
-        version: v.version,
-        save_type: v.save_type ?? "manual",
-        autosave_metadata: v.autosave_metadata ?? null,
-        created_at: v.created_at
+        id: workflow.id,
+        name: workflow.name,
+        description: workflow.description ?? "",
+        tags: workflow.tags ?? [],
+        run_mode: workflow.run_mode ?? null,
+        settings: workflow.settings ?? null,
+        graph: workflow.graph
     };
 }
-export async function handleWorkflowVersions(request, workflowId, options) {
-    const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
-    if (request.method === "POST") {
-        const workflow = (await Workflow.get(workflowId));
-        if (!workflow)
-            return errorResponse(404, "Workflow not found");
-        if (workflow.user_id !== userId)
-            return errorResponse(404, "Workflow not found");
-        const body = await parseJsonBody(request);
-        const nextVer = await WorkflowVersion.nextVersion(workflowId);
-        const version = (await WorkflowVersion.create({
-            workflow_id: workflowId,
-            user_id: userId,
-            name: body?.name ?? null,
-            description: body?.description ?? null,
-            graph: workflow.graph,
-            version: nextVer
-        }));
-        return jsonResponse(toVersionResponse(version));
+function bundleResponse(bytes, name) {
+    const safe = name.replace(/[^A-Za-z0-9._-]+/g, "_") || "workflows";
+    // Copy into an ArrayBuffer-backed view so it satisfies BodyInit.
+    const body = new Uint8Array(bytes);
+    return new Response(body, {
+        status: 200,
+        headers: {
+            "content-type": "application/zip",
+            "content-length": String(bytes.byteLength),
+            "content-disposition": `attachment; filename="${safe}.nodetool"`,
+            "cache-control": "no-store"
+        }
+    });
+}
+/** GET /api/workflows/:id/export-bundle — single workflow as a .nodetool zip. */
+export async function handleWorkflowExportBundle(request, workflowId, options) {
+    if (request.method !== "GET") {
+        return errorResponse(405, "Method not allowed");
     }
-    if (request.method === "GET") {
-        const url = new URL(request.url);
-        const limit = parseLimit(url, 100);
-        const versions = await WorkflowVersion.listForWorkflow(workflowId, {
-            limit
-        });
-        return jsonResponse({ versions: versions.map(toVersionResponse) });
+    const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
+    const loaded = await loadBundledWorkflow(workflowId, userId);
+    if ("error" in loaded) {
+        return loaded.error;
     }
-    return errorResponse(405, "Method not allowed");
+    const { bytes } = await packWorkflowsBundle({
+        workflows: [loaded],
+        fetchAssetBytes: resolveAssetBytesForExport
+    });
+    return bundleResponse(bytes, loaded.name);
 }
-export async function handleWorkflowVersionByNumber(request, workflowId, versionNumber, options) {
+/** POST /api/workflows/export-bundle {workflow_ids} — multiple workflows. */
+export async function handleWorkflowsExportBundle(request, options) {
+    if (request.method !== "POST") {
+        return errorResponse(405, "Method not allowed");
+    }
     const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
-    if (request.method === "GET") {
-        const version = await WorkflowVersion.findByVersion(workflowId, versionNumber);
-        if (!version)
-            return errorResponse(404, "Version not found");
-        const workflow = (await Workflow.get(workflowId));
-        if (!workflow)
-            return errorResponse(404, "Workflow not found");
-        if (workflow.user_id !== userId)
-            return errorResponse(404, "Workflow not found");
-        return jsonResponse(toVersionResponse(version));
+    const body = await parseBody(request, workflowsExportBundleBodySchema);
+    const ids = body?.workflow_ids ?? [];
+    if (ids.length === 0) {
+        return errorResponse(400, "workflow_ids (non-empty array) is required");
     }
-    if (request.method === "POST") {
-        // restore: copy version graph back to workflow
-        const version = await WorkflowVersion.findByVersion(workflowId, versionNumber);
-        if (!version)
-            return errorResponse(404, "Version not found");
-        const workflow = (await Workflow.get(workflowId));
-        if (!workflow)
-            return errorResponse(404, "Workflow not found");
-        if (workflow.user_id !== userId)
-            return errorResponse(404, "Workflow not found");
-        workflow.graph = version.graph;
-        await workflow.save();
-        return jsonResponse(toWorkflowResponse(workflow));
+    const loadedResults = await Promise.all(ids.map((id) => loadBundledWorkflow(id, userId)));
+    const workflows = [];
+    for (const loaded of loadedResults) {
+        if ("error" in loaded) {
+            return loaded.error;
+        }
+        workflows.push(loaded);
     }
-    return errorResponse(405, "Method not allowed");
+    const { bytes } = await packWorkflowsBundle({
+        workflows,
+        fetchAssetBytes: resolveAssetBytesForExport
+    });
+    const name = workflows.length === 1
+        ? workflows[0].name
+        : `${workflows.length}-workflows`;
+    return bundleResponse(bytes, name);
 }
-export async function handleWorkflowVersionDeleteById(request, _workflowId, versionId, options) {
-    if (request.method !== "DELETE") {
+/** POST /api/workflows/import-bundle — multipart .nodetool upload. */
+export async function handleWorkflowImportBundle(request, options) {
+    if (request.method !== "POST") {
         return errorResponse(405, "Method not allowed");
     }
     const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
-    const version = (await WorkflowVersion.get(versionId));
-    if (!version)
-        return errorResponse(404, "Version not found");
-    if (version.user_id !== userId)
-        return errorResponse(404, "Version not found");
-    await version.delete();
-    return new Response(null, { status: 204 });
+    let projectId = new URL(request.url).searchParams.get("project_id") ?? "default";
+    let zipBytes = null;
+    const contentType = request.headers.get("content-type") ?? "";
+    if (contentType.toLowerCase().includes("multipart/form-data")) {
+        try {
+            const fd = await request.formData();
+            const file = fd.get("file");
+            const formProjectId = fd.get("project_id");
+            if (typeof formProjectId === "string" && formProjectId) {
+                projectId = formProjectId;
+            }
+            if (file) {
+                zipBytes = new Uint8Array(await file.arrayBuffer());
+            }
+        }
+        catch {
+            return errorResponse(400, "Invalid multipart form data");
+        }
+    }
+    else {
+        const buf = await request.arrayBuffer();
+        if (buf.byteLength > 0) {
+            zipBytes = new Uint8Array(buf);
+        }
+    }
+    if (!zipBytes) {
+        return errorResponse(400, "A .nodetool bundle file is required");
+    }
+    if (projectId !== "default") {
+        try {
+            await Project.requireOwned(userId, projectId);
+        }
+        catch {
+            return errorResponse(400, "Project not found");
+        }
+    }
+    let result;
+    try {
+        result = await importWorkflowBundle(zipBytes, {
+            storeAsset: async ({ bytes, fileName, contentType: assetType }) => {
+                const asset = (await Asset.create({
+                    user_id: userId,
+                    name: fileName,
+                    content_type: assetType,
+                    parent_id: userId,
+                    project_id: projectId,
+                    size: bytes.byteLength
+                }));
+                const storedName = getAssetFileName(asset.id, asset.content_type);
+                await storeAssetWithThumbnail(asset.user_id, asset.id, storedName, bytes, asset.content_type);
+                return { uri: `asset://${storedName}`, assetId: asset.id };
+            }
+        });
+    }
+    catch (error) {
+        return errorResponse(400, `Invalid bundle: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const created = [];
+    try {
+        for (const wf of result.workflows) {
+            const workflow = await createWorkflow(userId, {
+                name: wf.name,
+                description: wf.description ?? "",
+                tags: wf.tags ?? [],
+                access: "private",
+                graph: wf.graph,
+                settings: wf.settings ?? null,
+                run_mode: wf.run_mode ?? "workflow"
+            });
+            created.push(toWorkflowResponse(workflow));
+        }
+    }
+    catch (error) {
+        // createWorkflow throws on a malformed graph (e.g. missing edges array),
+        // which unpackWorkflowBundle does not validate. Surface it as a 400 rather
+        // than an unhandled 500. (Earlier-created workflows in the loop remain —
+        // the import is not transactional; reported as a bad-bundle error.)
+        return errorResponse(400, `Invalid bundle: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return jsonResponse({
+        workflows: created,
+        imported: result.imported.length,
+        missing: result.missing,
+        checksum_mismatches: result.checksumMismatches
+    });
 }
 export async function handleWorkflowsRoot(request, options) {
     const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
@@ -949,11 +864,14 @@ export async function handleWorkflowsRoot(request, options) {
     if (request.method === "GET") {
         const limit = parseLimit(url, 100);
         const runMode = url.searchParams.get("run_mode")?.trim() ?? undefined;
-        // cursor and columns params accepted for Python parity (cursor ignored in memory adapter)
-        // columns param is Python-specific (column selection) — ignored here
+        const projectId = url.searchParams.get("project_id")?.trim() || undefined;
+        const startKey = url.searchParams.get("cursor")?.trim() || undefined;
+        // columns is Python-specific (column selection) and is ignored here.
         const [workflows, cursor] = await Workflow.paginate(userId, {
             limit,
-            runMode
+            runMode,
+            projectId,
+            startKey
         });
         return jsonResponse({
             workflows: workflows.map((w) => toWorkflowResponse(w)),
@@ -961,24 +879,25 @@ export async function handleWorkflowsRoot(request, options) {
         });
     }
     if (request.method === "POST") {
-        const body = await parseJsonBody(request);
+        const body = await parseBody(request, workflowRequestBodySchema);
         if (!body)
             return errorResponse(400, "Invalid JSON body");
+        const exampleName = url.searchParams.get("from_example_name")?.trim() || undefined;
         try {
-            const fromPkg = url.searchParams.get("from_example_package")?.trim() ?? undefined;
-            const fromName = url.searchParams.get("from_example_name")?.trim() ?? undefined;
-            if (fromPkg &&
-                fromName &&
-                (!body.graph || body.graph.nodes?.length === 0)) {
-                const example = loadExampleGraph(fromPkg, fromName, options);
-                if (example?.graph) {
-                    body.graph = example.graph;
+            const workflow = await createWorkflow(userId, body, exampleName
+                ? {
+                    packageName: url.searchParams.get("from_example_package")?.trim() ||
+                        undefined,
+                    exampleName,
+                    apiOptions: options
                 }
-            }
-            const workflow = await createWorkflow(body, userId);
+                : undefined);
             return jsonResponse(toWorkflowResponse(workflow));
         }
         catch (error) {
+            if (error instanceof WorkflowServiceError) {
+                return errorResponse(error.status, error.message);
+            }
             const message = error instanceof Error ? error.message : "Invalid workflow";
             return errorResponse(400, message);
         }
@@ -1013,42 +932,48 @@ export async function handleWorkflowById(request, workflowId, options) {
         const workflow = (await Workflow.get(workflowId));
         if (!workflow)
             return errorResponse(404, "Workflow not found");
-        if (workflow.access !== "public" && workflow.user_id !== userId) {
+        const collaborator = workflow.user_id === userId
+            ? null
+            : await WorkflowCollaborator.findFor(workflowId, userId);
+        if (workflow.access !== "public" &&
+            workflow.user_id !== userId &&
+            !collaborator) {
             return errorResponse(404, "Workflow not found");
         }
         return jsonResponse(toWorkflowResponse(workflow));
     }
     if (request.method === "PUT") {
-        const body = await parseJsonBody(request);
+        const body = await parseBody(request, workflowRequestBodySchema);
         if (!body)
             return errorResponse(400, "Invalid JSON body");
         try {
-            const workflow = await updateWorkflow(workflowId, body, userId);
+            const workflow = await updateWorkflow(userId, workflowId, body);
             return jsonResponse(toWorkflowResponse(workflow));
         }
         catch (error) {
+            if (error instanceof WorkflowServiceError) {
+                return errorResponse(error.status, error.message);
+            }
             const message = error instanceof Error ? error.message : "Invalid workflow";
-            if (message === "Workflow not found")
-                return errorResponse(404, message);
             return errorResponse(400, message);
         }
     }
     if (request.method === "DELETE") {
-        const workflow = (await Workflow.get(workflowId));
-        if (!workflow)
-            return errorResponse(404, "Workflow not found");
-        if (workflow.user_id !== userId)
-            return errorResponse(404, "Workflow not found");
-        await workflow.delete();
+        try {
+            await deleteWorkflow(userId, workflowId);
+        }
+        catch (error) {
+            if (error instanceof WorkflowServiceError) {
+                return errorResponse(error.status, error.message);
+            }
+            throw error;
+        }
         return new Response(null, { status: 204 });
     }
     return errorResponse(405, "Method not allowed");
 }
 // ── Job types & helpers ───────────────────────────────────────────
-/**
- * Full job response — still exported here because `mcp-server.ts` consumes it
- * when serving job metadata over MCP. Consider relocating if MCP also migrates.
- */
+/** Full job response, shared by the REST routes that serve job metadata. */
 export function toJobResponse(job) {
     return {
         id: job.id,
@@ -1056,94 +981,45 @@ export function toJobResponse(job) {
         job_type: "workflow",
         status: job.status,
         workflow_id: job.workflow_id,
+        project_id: job.project_id,
         started_at: job.started_at ?? null,
         finished_at: job.finished_at ?? null,
         error: job.error ?? null,
-        cost: null
-    };
-}
-// ── Trigger job stubs ─────────────────────────────────────────────
-export async function handleTriggersRunning(request) {
-    if (request.method !== "GET") {
-        return errorResponse(405, "Method not allowed");
-    }
-    return jsonResponse({ workflows: [] });
-}
-export async function handleTriggerStart(request, _workflowId) {
-    if (request.method !== "POST") {
-        return errorResponse(405, "Method not allowed");
-    }
-    return errorResponse(501, "Trigger workflows not available in standalone mode");
-}
-export async function handleTriggerStop(request, _workflowId) {
-    if (request.method !== "POST") {
-        return errorResponse(405, "Method not allowed");
-    }
-    return errorResponse(501, "Trigger workflows not available in standalone mode");
-}
-// ── Nodes dummy ───────────────────────────────────────────────────
-export async function handleNodesDummy(request) {
-    if (request.method !== "GET") {
-        return errorResponse(405, "Method not allowed");
-    }
-    return jsonResponse({
-        type: "asset",
-        uri: "",
-        asset_id: null,
-        data: null,
-        metadata: null
-    });
-}
-export function toAssetResponse(asset) {
-    const isFolder = asset.content_type === "folder";
-    const fileName = isFolder
-        ? null
-        : getAssetFileName(asset.id, asset.content_type);
-    const getUrl = fileName ? buildAssetUrl(fileName) : null;
-    const hasThumbnail = asset.content_type.startsWith("image/") ||
-        asset.content_type.startsWith("video/");
-    const updatedTs = asset.updated_at
-        ? Math.floor(new Date(asset.updated_at).getTime() / 1000)
-        : 0;
-    const thumbUrl = hasThumbnail
-        ? `/api/assets/${asset.id}/thumbnail?t=${updatedTs}`
-        : null;
-    return {
-        id: asset.id,
-        user_id: asset.user_id,
-        workflow_id: asset.workflow_id ?? null,
-        parent_id: asset.parent_id ?? null,
-        name: asset.name,
-        content_type: asset.content_type,
-        size: asset.size ?? null,
-        metadata: asset.metadata ?? null,
-        created_at: asset.created_at,
-        get_url: getUrl,
-        thumb_url: thumbUrl,
-        duration: asset.duration ?? null,
-        node_id: asset.node_id ?? null,
-        job_id: asset.job_id ?? null
+        cost: job.cost ?? null,
+        outputs: job.runOutputs()
     };
 }
 /**
  * Handle multipart file upload at POST /api/assets. JSON-only creation has
  * moved to the tRPC `assets.create` procedure.
  */
-export async function handleAssetsRoot(request, options) {
+export async function handleAssetsRoot(request, options, staged) {
     const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
     if (request.method === "POST") {
         const contentType = request.headers.get("content-type") ?? "";
         let body = null;
         let fileBuffer = null;
         let fileSize = null;
-        if (contentType.toLowerCase().includes("multipart/form-data")) {
+        if (staged) {
+            body = parseBodyValue(staged.metadata, assetCreateBodySchema);
+            if (staged.file) {
+                body = {
+                    ...body,
+                    name: body?.name || staged.file.name,
+                    content_type: body?.content_type || staged.file.contentType,
+                    parent_id: body?.parent_id || userId
+                };
+                fileSize = staged.file.size;
+            }
+        }
+        else if (contentType.toLowerCase().includes("multipart/form-data")) {
             try {
                 const fd = await request.formData();
                 const file = fd.get("file");
                 // Frontend sends metadata as "json" field
                 const assetJson = fd.get("json") ?? fd.get("asset");
-                if (assetJson && typeof assetJson === "string") {
-                    body = JSON.parse(assetJson);
+                if (isNonEmptyString(assetJson)) {
+                    body = parseBodyValue(JSON.parse(assetJson), assetCreateBodySchema);
                 }
                 if (file) {
                     const arrayBuffer = await file.arrayBuffer();
@@ -1170,93 +1046,164 @@ export async function handleAssetsRoot(request, options) {
             }
         }
         else {
-            body = await parseJsonBody(request);
+            body = await parseBody(request, assetCreateBodySchema);
         }
         if (!body ||
-            typeof body.name !== "string" ||
-            typeof body.content_type !== "string" ||
-            typeof body.parent_id !== "string") {
+            body.name === undefined ||
+            body.content_type === undefined ||
+            body.parent_id === undefined) {
             return errorResponse(400, "Invalid JSON body: name, content_type, and parent_id are required");
         }
         const metadata = body.metadata ?? {};
+        if (body.project_id && body.project_id !== "default") {
+            try {
+                await Project.requireOwned(userId, body.project_id);
+            }
+            catch {
+                return errorResponse(400, "Project not found");
+            }
+        }
+        const assetContentType = normalizeAssetContentType(body.content_type, body.name);
+        const duration = staged?.file
+            ? await probeAssetDurationSeconds(assetContentType, {
+                path: staged.file.path
+            })
+            : fileBuffer
+                ? await probeAssetDurationSeconds(assetContentType, {
+                    bytes: fileBuffer
+                })
+                : null;
         const asset = (await Asset.create({
             user_id: userId,
             name: body.name,
-            content_type: body.content_type,
+            content_type: assetContentType,
             parent_id: body.parent_id,
             workflow_id: body.workflow_id ?? null,
             node_id: body.node_id ?? null,
             job_id: body.job_id ?? null,
             metadata: Object.keys(metadata).length > 0 ? metadata : (body.metadata ?? null),
-            size: fileSize ?? body.size ?? null
+            project_id: body.project_id ?? "default",
+            size: fileSize ?? body.size ?? null,
+            duration
         }));
-        // Write file to storage directory so it's accessible via /api/storage/
-        if (fileBuffer) {
-            const storagePath = getAssetStoragePath(options.storage);
+        if (fileBuffer || staged?.file) {
             const fileName = getAssetFileName(asset.id, asset.content_type);
-            const filePath = nodePath.join(storagePath, fileName);
-            await mkdir(storagePath, { recursive: true });
-            await writeFile(filePath, fileBuffer);
+            log.info("asset upload (multipart)", {
+                assetId: asset.id,
+                fileName,
+                contentType: asset.content_type,
+                bytes: fileSize
+            });
+            try {
+                if (staged?.file) {
+                    const adapter = getAssetAdapter();
+                    if (!(adapter instanceof FileStorageAdapter)) {
+                        throw new Error("Staged uploads require local storage");
+                    }
+                    await adapter.storeFile(getAssetStorageKey(asset.user_id, asset.id, asset.content_type), staged.file.path);
+                    // The stored file is local, so the thumbnail reads it in place at
+                    // any size.
+                    await generateThumbnailForStoredAsset(asset.user_id, asset.id, asset.content_type);
+                }
+                else if (fileBuffer) {
+                    await storeAssetWithThumbnail(asset.user_id, asset.id, fileName, new Uint8Array(fileBuffer), asset.content_type);
+                }
+            }
+            catch (error) {
+                // The row was created before the bytes were written. If the store
+                // rejects (over the upload cap, or any S3/Supabase failure) drop the
+                // row rather than leave it pointing at bytes that never landed.
+                try {
+                    await asset.delete();
+                }
+                catch (deleteError) {
+                    log.warn("failed to delete asset row after upload failure", {
+                        assetId: asset.id,
+                        error: String(deleteError)
+                    });
+                }
+                throw error instanceof Error ? error : new Error(String(error));
+            }
+            scheduleVideoProxy(asset);
         }
-        return jsonResponse(toAssetResponse(asset));
+        return jsonResponse(await toAssetResponse(asset));
     }
     return errorResponse(405, "Method not allowed");
 }
-export async function handleAssetThumbnail(request, assetId, options) {
-    if (request.method === "POST") {
-        return errorResponse(501, "Thumbnail generation not available");
-    }
-    if (request.method !== "GET")
-        return errorResponse(405, "Method not allowed");
+/**
+ * POST /api/assets/:id/extract-audio
+ *
+ * Extracts the audio track of a video asset into a new audio (WAV) asset and
+ * returns it. If the video has no audio track, responds `{ has_audio: false }`
+ * with no asset. Used by the timeline to create a linked, independently
+ * editable audio clip when a video is imported.
+ */
+export async function handleExtractAudio(request, options, assetId) {
     const userId = getUserId(request, options.userIdHeader ?? "x-user-id");
-    const asset = await Asset.find(userId, assetId);
-    if (!asset)
+    const source = (await Asset.get(assetId));
+    if (!source) {
         return errorResponse(404, "Asset not found");
-    if (!asset.hasThumbnail) {
-        return errorResponse(400, `Asset type '${asset.content_type}' does not support thumbnails`);
     }
-    const storagePath = getAssetStoragePath(options.storage);
-    // Try to serve a pre-generated thumbnail ({id}_thumb.jpg)
-    const thumbFileName = `${asset.id}_thumb.jpg`;
-    const thumbFilePath = nodePath.join(storagePath, thumbFileName);
-    try {
-        const thumbStat = await stat(thumbFilePath);
-        const data = await readFile(thumbFilePath);
-        return new Response(data, {
-            status: 200,
-            headers: {
-                "Content-Type": "image/jpeg",
-                "Content-Length": String(thumbStat.size),
-                "Cache-Control": "no-cache",
-                "Last-Modified": thumbStat.mtime.toUTCString()
-            }
-        });
+    // Ownership guard: in multi-user mode an asset is only visible to its owner.
+    if (source.user_id !== userId) {
+        return errorResponse(404, "Asset not found");
     }
-    catch {
-        // No pre-generated thumbnail, fall through
+    if (!source.content_type.startsWith("video/")) {
+        return errorResponse(400, "Asset is not a video");
     }
-    // Fall back to serving the original file (for images)
-    if (asset.content_type.startsWith("image/")) {
-        const fileName = getAssetFileName(asset.id, asset.content_type);
-        const filePath = nodePath.join(storagePath, fileName);
+    // ffmpeg reads a local file (managed or external) in place. Only a backend
+    // with no local file has its bytes loaded and written to a temp input.
+    const adapter = getAssetAdapter();
+    const dir = await fsp.mkdtemp(nodePath.join(os.tmpdir(), "nodetool-extract-"));
+    try {
+        let inputPath = await localAssetPath(adapter, source.user_id, source.id, source.content_type);
+        if (!inputPath) {
+            const videoBytes = await retrieveAssetBytes(adapter, source.user_id, source.id, source.content_type);
+            if (!videoBytes) {
+                return errorResponse(404, "Asset bytes not found");
+            }
+            inputPath = nodePath.join(dir, "input");
+            await fsp.writeFile(inputPath, videoBytes);
+        }
+        // The WAV stays on disk: it is stored from the file and thumbnailed from
+        // it, never held in memory whole.
+        const wavPath = nodePath.join(dir, "audio.wav");
+        let durationMs;
         try {
-            const fileStat = await stat(filePath);
-            const data = await readFile(filePath);
-            return new Response(data, {
-                status: 200,
-                headers: {
-                    "Content-Type": asset.content_type,
-                    "Content-Length": String(fileStat.size),
-                    "Cache-Control": "no-cache",
-                    "Last-Modified": fileStat.mtime.toUTCString()
-                }
-            });
+            if (!(await probeHasAudio(inputPath))) {
+                return jsonResponse({ has_audio: false });
+            }
+            ({ durationMs } = await extractAudio(inputPath, wavPath));
         }
-        catch {
-            // File not found on disk
+        catch (err) {
+            if (err instanceof MediaToolingMissingError) {
+                return errorResponse(503, "ffmpeg is required to extract audio from video. Install the ffmpeg runtime.");
+            }
+            throw err;
         }
+        const { size } = await fsp.stat(wavPath);
+        const audioAsset = (await Asset.create({
+            user_id: userId,
+            name: `${source.name} (audio)`,
+            content_type: "audio/wav",
+            parent_id: source.id,
+            workflow_id: source.workflow_id ?? null,
+            project_id: source.project_id,
+            node_id: null,
+            job_id: null,
+            metadata: null,
+            size,
+            duration: durationMs != null ? durationMs / 1000 : null
+        }));
+        await storeAssetFileWithThumbnail(audioAsset.user_id, audioAsset.id, getAssetFileName(audioAsset.id, audioAsset.content_type), wavPath, audioAsset.content_type);
+        return jsonResponse({
+            has_audio: true,
+            asset: await toAssetResponse(audioAsset)
+        });
+    }
+    finally {
+        await fsp.rm(dir, { recursive: true, force: true });
     }
-    return errorResponse(404, "No thumbnail available");
 }
 export async function handleApiRequest(request, options = {}) {
     const url = new URL(request.url);
@@ -1272,20 +1219,31 @@ export async function handleApiRequest(request, options = {}) {
         if (response)
             return response;
     }
+    // Restored: the REST-to-tRPC migration on this branch dropped this route as a
+    // side effect, with no tRPC replacement, and its suite (ws-phase2, T-WS-8)
+    // still covers it. Whether to retire a public endpoint is a deliberate
+    // decision, not a refactor's leftover. Note it never consulted storage —
+    // `available` has always been unconditionally true.
     if (pathname === "/api/users/validate_username") {
-        if (request.method !== "GET")
+        if (request.method !== "GET") {
             return errorResponse(405, "Method not allowed");
+        }
         const url = new URL(request.url);
         const username = url.searchParams.get("username")?.trim() ?? null;
-        if (username === null)
+        if (username === null) {
             return errorResponse(400, "username parameter is required");
-        if (!username)
+        }
+        if (!username) {
             return errorResponse(400, "username cannot be empty");
+        }
         const valid = /^[a-zA-Z0-9_-]{3,32}$/.test(username);
         return jsonResponse({ valid, available: true });
     }
-    if (pathname === "/api/nodes/dummy") {
-        return handleNodesDummy(request);
+    if (pathname === "/api/applications/examples") {
+        if (request.method !== "GET") {
+            return errorResponse(405, "Method not allowed");
+        }
+        return jsonResponse(listExampleApps(options));
     }
     if (pathname === "/api/nodes/metadata" || pathname === "/api/node/metadata") {
         return handleNodeMetadata(request, options);
@@ -1306,6 +1264,12 @@ export async function handleApiRequest(request, options = {}) {
     if (pathname === "/api/workflows/tools") {
         return handleWorkflowTools(request, options);
     }
+    if (pathname === "/api/workflows/export-bundle") {
+        return handleWorkflowsExportBundle(request, options);
+    }
+    if (pathname === "/api/workflows/import-bundle") {
+        return handleWorkflowImportBundle(request, options);
+    }
     if (pathname === "/api/workflows/examples") {
         return handleWorkflowExamples(request, options);
     }
@@ -1316,8 +1280,14 @@ export async function handleApiRequest(request, options = {}) {
         const filename = decodeURIComponent(pathname.slice("/api/workflows/examples/thumbnails/".length));
         return handleWorkflowExamplesThumbnail(request, filename, options);
     }
+    // /api/workflows/examples/{package}/{name} — one example with its graph.
     if (pathname.startsWith("/api/workflows/examples/")) {
-        return errorResponse(404, "Examples not available in standalone mode");
+        const rest = pathname.slice("/api/workflows/examples/".length);
+        const slash = rest.indexOf("/");
+        if (slash > 0) {
+            return handleWorkflowExampleByName(request, decodeURIComponent(rest.slice(0, slash)), decodeURIComponent(rest.slice(slash + 1)), options);
+        }
+        return errorResponse(404, "Not found");
     }
     if (pathname === "/api/workflows/public") {
         return handlePublicWorkflows(request);
@@ -1328,6 +1298,14 @@ export async function handleApiRequest(request, options = {}) {
             return errorResponse(404, "Not found");
         return handlePublicWorkflowById(request, workflowId);
     }
+    // ── Interactive debug sessions ─────────────────────────────────────
+    // Pattern: /api/debug/sessions/{id}[/verdict|/cancel]
+    {
+        const debugSessionMatch = pathname.match(/^\/api\/debug\/sessions\/([^/]+)(?:\/([a-z]+))?$/);
+        if (debugSessionMatch) {
+            return handleDebugSessionRequest(request, decodeURIComponent(debugSessionMatch[1]), debugSessionMatch[2] ?? null, options);
+        }
+    }
     // ── Workflow sub-resource routes ───────────────────────────────────
     // Pattern: /api/workflows/{id}/...
     {
@@ -1338,41 +1316,14 @@ export async function handleApiRequest(request, options = {}) {
             if (subPath === "run") {
                 return handleWorkflowRun(request, workflowId, options);
             }
-            if (subPath === "autosave") {
-                return handleWorkflowAutosave(request, workflowId, options);
-            }
-            if (subPath === "app") {
-                return handleWorkflowApp(request, workflowId, options);
-            }
-            if (subPath === "generate-name") {
-                return handleWorkflowGenerateName(request, workflowId, options);
+            if (subPath === "debug") {
+                return handleWorkflowRun(request, workflowId, options, true);
             }
             if (subPath === "dsl-export") {
                 return handleWorkflowDslExport(request, workflowId, options);
             }
-            if (subPath === "gradio-export") {
-                return handleWorkflowGradioExport(request, workflowId, options);
-            }
-            if (subPath === "versions") {
-                return handleWorkflowVersions(request, workflowId, options);
-            }
-            // /api/workflows/{id}/versions/{version}/restore
-            const versionRestoreMatch = subPath.match(/^versions\/(\d+)\/restore$/);
-            if (versionRestoreMatch) {
-                const versionNum = Number.parseInt(versionRestoreMatch[1], 10);
-                return handleWorkflowVersionByNumber(request, workflowId, versionNum, options);
-            }
-            // /api/workflows/{id}/versions/{version} (GET by version number)
-            const versionNumMatch = subPath.match(/^versions\/(\d+)$/);
-            if (versionNumMatch) {
-                const versionNum = Number.parseInt(versionNumMatch[1], 10);
-                return handleWorkflowVersionByNumber(request, workflowId, versionNum, options);
-            }
-            // /api/workflows/{id}/versions/{version_id} (DELETE by id — version_id is not numeric)
-            const versionIdMatch = subPath.match(/^versions\/([^/]+)$/);
-            if (versionIdMatch) {
-                const versionId = decodeURIComponent(versionIdMatch[1]);
-                return handleWorkflowVersionDeleteById(request, workflowId, versionId, options);
+            if (subPath === "export-bundle") {
+                return handleWorkflowExportBundle(request, workflowId, options);
             }
         }
     }
@@ -1444,19 +1395,36 @@ export async function handleNodeHttpRequest(req, res, options = {}) {
         res.end();
         return;
     }
-    const bodyBuffer = Buffer.from(await response.arrayBuffer());
-    // Gzip-compress large JSON responses for performance (e.g. /api/nodes/metadata
-    // is ~5 MB uncompressed, ~550 KB compressed).
-    const GZIP_THRESHOLD = 256 * 1024;
     const acceptEncoding = req.headers["accept-encoding"] ?? "";
-    if (bodyBuffer.length > GZIP_THRESHOLD && acceptEncoding.includes("gzip")) {
-        const compressed = gzipSync(bodyBuffer);
-        res.setHeader("content-encoding", "gzip");
-        res.setHeader("content-length", compressed.length);
-        res.end(compressed);
+    const contentType = response.headers.get("content-type") ?? "";
+    const mayCompress = response.status !== 206 &&
+        !response.headers.has("content-range") &&
+        (contentType.includes("json") || contentType.startsWith("text/")) &&
+        acceptEncoding.includes("gzip");
+    if (mayCompress) {
+        const bodyBuffer = Buffer.from(await response.arrayBuffer());
+        if (bodyBuffer.length > GZIP_THRESHOLD) {
+            const compressed = gzipSync(bodyBuffer);
+            res.setHeader("content-encoding", "gzip");
+            res.setHeader("content-length", compressed.length);
+            res.end(compressed);
+        }
+        else {
+            res.end(bodyBuffer);
+        }
         return;
     }
-    res.end(bodyBuffer);
+    const reader = response.body.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        if (!res.write(value)) {
+            await once(res, "drain");
+        }
+    }
+    res.end();
 }
 export function createHttpApiServer(options = {}) {
     return createServer((req, res) => {
@@ -1464,8 +1432,7 @@ export function createHttpApiServer(options = {}) {
             log.error("Request failed", error instanceof Error ? error : new Error(String(error)));
             res.statusCode = 500;
             res.setHeader("content-type", "application/json");
-            const detail = error instanceof Error ? error.message : String(error);
-            res.end(JSON.stringify({ detail }));
+            res.end(JSON.stringify({ detail: "Internal server error" }));
         });
     });
 }