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

package/dist/trpc/routers/workflows.js

@@ -3,16 +3,14 @@
  *
  * Retained on REST (file downloads):
  *   - GET  /api/workflows/:id/dsl-export   (text/plain file download)
- *   - POST /api/workflows/:id/gradio-export (501 stub, kept for API compat)
  *
  * Everything else is served via tRPC:
- *   - list, names, get, create, update, delete
- *   - run, autosave
- *   - tools, examples (list + search)
+ *   - list, get, create, update, delete
+ *   - autosave
+ *   - examples (list + search)
+ *   - recipes (shipped chains of examples)
  *   - public (list + get) — publicProcedure (no auth required)
- *   - app (metadata for workflow app page)
- *   - generateName
- *   - versions (list, create, get, restore, delete)
+ *   - versions (list, create, restore, delete)
  *
  * Auth note:
  *   - `public.*` endpoints use publicProcedure — no auth required, matches
@@ -21,17 +19,58 @@
  */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import nodePath from "node:path";
-import { Workflow, WorkflowVersion, Job } from "@nodetool-ai/models";
-import { PythonNodeExecutor } from "@nodetool-ai/runtime";
-import { WorkflowRunner } from "@nodetool-ai/kernel";
+import { z } from "zod";
+import { withCacheBuster } from "../../lib/example-thumbnail.js";
+import { Workflow, WorkflowVersion, WorkflowCollaborator, WorkflowShare } from "@nodetool-ai/models";
 import { loadPythonPackageMetadata } from "@nodetool-ai/node-sdk";
 import { createLogger } from "@nodetool-ai/config";
+import { deriveExampleAssetsDir } from "../../example-workflows.js";
+import { exampleRecipeSummary } from "@nodetool-ai/protocol/api-schemas/recipes.js";
+import { listExampleRecipes } from "../../lib/example-recipes.js";
 import { ApiErrorCode } from "../../error-codes.js";
 import { router, publicProcedure } from "../index.js";
 import { protectedProcedure } from "../middleware.js";
 import { throwApiError } from "../error-formatter.js";
-import { listInput, listOutput, namesOutput, getInput, createInput, updateInput, deleteInput, deleteOutput, runInput, runOutput, autosaveInput, autosaveOutput, toolsInput, toolsOutput, examplesInput, examplesOutput, publicListInput, publicListOutput, publicGetInput, appInput, appOutput, generateNameInput, generateNameOutput, versionsListInput, versionsListOutput, versionCreateInput, versionGetInput, versionResponse, versionRestoreInput, versionDeleteInput, versionDeleteOutput, workflowResponse, graph as graphSchema } from "@nodetool-ai/protocol/api-schemas/workflows.js";
+import { createWorkflow, deleteWorkflow, syncTriggerRegistrations, updateWorkflow, WorkflowServiceError } from "../../lib/workflow-service.js";
+import { listInput, listOutput, getInput, createInput, updateInput, deleteInput, deleteOutput, autosaveInput, autosaveOutput, examplesInput, examplesOutput, publicListInput, publicListOutput, publicGetInput, versionsListInput, versionsListOutput, versionCreateInput, versionResponse, versionRestoreInput, versionDeleteInput, versionDeleteOutput, terminalOutputsInput, terminalOutputsOutput, workflowResponse, graph as graphSchema, sharingGetInput, sharingGetOutput, sharingCreateLinkInput, sharingRevokeLinkInput, sharingSetRoleInput, sharingRemoveCollaboratorInput, sharingOkOutput, sharingAcceptInput, sharingAcceptOutput, shareItem, collaboratorItem, sharedWithMeInput, sharedWithMeOutput } from "@nodetool-ai/protocol/api-schemas/workflows.js";
+import { isString } from "../../lib/wire-values.js";
+import { getStorageRetentionSettings } from "../../storage-retention.js";
 const log = createLogger("nodetool.websocket.trpc.workflows");
+/** Map a `workflow-service` failure onto this router's tRPC error shape. */
+async function runWorkflowService(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof WorkflowServiceError) {
+            throwApiError(error.code, error.message);
+        }
+        throw error;
+    }
+}
+async function resolveWorkflowRole(workflow, userId) {
+    if (workflow.user_id === userId)
+        return "owner";
+    const grant = await WorkflowCollaborator.findFor(workflow.id, userId);
+    if (grant)
+        return grant.role;
+    if (workflow.access === "public")
+        return "viewer";
+    return null;
+}
+/** Load a workflow and require at least `minimum` access, else 404. */
+async function requireWorkflowRole(workflowId, userId, minimum) {
+    const workflow = (await Workflow.get(workflowId));
+    if (!workflow) {
+        throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
+    }
+    const role = await resolveWorkflowRole(workflow, userId);
+    const rank = { viewer: 1, editor: 2, owner: 3 };
+    if (!role || rank[role] < rank[minimum]) {
+        throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
+    }
+    return { workflow, role };
+}
 /**
  * Validate a workflow graph against the wire schema. Returns the graph if it
  * passes, or null if invalid — so list endpoints can still return the rest of
@@ -57,9 +96,43 @@ function safeGraph(workflowId, raw) {
     log.warn(`Workflow ${workflowId} has an invalid graph; returning null: ${summarizeGraphIssues(parsed.error.issues)}`);
     return null;
 }
+const OUTPUT_NODE_MEDIA_TYPES = {
+    "nodetool.output.ImageOutput": "image",
+    "nodetool.output.VideoOutput": "video",
+    "nodetool.output.AudioOutput": "audio"
+};
+function findTerminalMediaOutputNodes(workflow) {
+    const graph = safeGraph(workflow.id, workflow.graph);
+    const nodes = (graph?.nodes ?? []);
+    const edges = (graph?.edges ?? []);
+    const terminalOutputNodeIds = new Set(nodes
+        .filter((n) => Object.hasOwn(OUTPUT_NODE_MEDIA_TYPES, n.type))
+        .map((n) => n.id));
+    for (const edge of edges) {
+        const sourceId = edge.source;
+        if (sourceId && terminalOutputNodeIds.has(sourceId)) {
+            terminalOutputNodeIds.delete(sourceId);
+        }
+    }
+    return nodes.filter((n) => terminalOutputNodeIds.has(n.id));
+}
+function hasTerminalMediaOutput(workflow) {
+    return findTerminalMediaOutputNodes(workflow).length > 0;
+}
 // ── Rate-limit tracking for autosave ───────────────────────────────────────
 const lastAutosaveTime = new Map();
 const AUTOSAVE_RATE_LIMIT_MS = 30_000;
+// Entries older than the rate-limit window can never rate-limit again, so drop
+// them. Without this the map grows one permanent entry per workflow ever
+// autosaved (including deleted ones) for the lifetime of the process.
+function recordAutosave(workflowId, now) {
+    for (const [id, ts] of lastAutosaveTime) {
+        if (now - ts >= AUTOSAVE_RATE_LIMIT_MS) {
+            lastAutosaveTime.delete(id);
+        }
+    }
+    lastAutosaveTime.set(workflowId, now);
+}
 // ── toWorkflowResponse ─────────────────────────────────────────────────────
 function toWorkflowResponse(workflow) {
     return {
@@ -81,9 +154,11 @@ function toWorkflowResponse(workflow) {
         path: workflow.path ?? null,
         run_mode: workflow.run_mode ?? null,
         workspace_id: workflow.workspace_id ?? null,
+        project_id: workflow.project_id,
         required_providers: null,
         required_models: null,
         html_app: workflow.html_app ?? null,
+        app_doc: workflow.app_doc ?? null,
         etag: workflow.getEtag() ?? null
     };
 }
@@ -102,15 +177,31 @@ function toVersionResponse(v) {
         created_at: v.created_at ?? null
     };
 }
+function toCollaboratorItem(grant) {
+    return {
+        workflow_id: grant.workflow_id,
+        user_id: grant.user_id,
+        role: grant.role,
+        invited_by: grant.invited_by,
+        created_at: grant.created_at ?? null
+    };
+}
+function toShareItem(share) {
+    return {
+        id: share.id,
+        workflow_id: share.workflow_id,
+        token: share.token,
+        role: share.role,
+        created_at: share.created_at ?? null,
+        revoked_at: share.revoked_at ?? null
+    };
+}
 // ── Example workflow helpers ────────────────────────────────────────────────
 const EXAMPLES_THUMBNAILS_PREFIX = "/api/workflows/examples/thumbnails/";
-function deriveAssetsDir(examplesDir) {
-    return nodePath.join(nodePath.dirname(nodePath.dirname(examplesDir)), "assets", nodePath.basename(examplesDir));
-}
-function buildExamplesFromDir(examplesDir) {
+function buildExamplesFromDir(examplesDir, examplesAssetsFallbackDir) {
     if (!existsSync(examplesDir))
         return [];
-    const assetsDir = deriveAssetsDir(examplesDir);
+    const assetsDir = deriveExampleAssetsDir(examplesDir, examplesAssetsFallbackDir);
     const now = new Date().toISOString();
     const workflows = [];
     let files;
@@ -126,12 +217,15 @@ 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, "");
+            // Append ?v=<md5-8> via withCacheBuster so the browser invalidates
+            // its cached thumbnail whenever the JPG is regenerated on disk.
             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,
@@ -140,9 +234,9 @@ function buildExamplesFromDir(examplesDir) {
                 updated_at: now,
                 name,
                 tool_name: null,
-                description: typeof parsed.description === "string" ? parsed.description : "",
+                description: isString(parsed.description) ? parsed.description : "",
                 tags: Array.isArray(parsed.tags)
-                    ? parsed.tags.filter((t) => typeof t === "string")
+                    ? parsed.tags.filter((t) => isString(t))
                     : [],
                 thumbnail: thumbnailUrl ? jpgFile : null,
                 thumbnail_url: thumbnailUrl,
@@ -150,13 +244,16 @@ function buildExamplesFromDir(examplesDir) {
                 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: null,
                 etag: null
             });
         }
@@ -168,7 +265,7 @@ function buildExamplesFromDir(examplesDir) {
 }
 function buildExampleWorkflows(apiOptions) {
     if (apiOptions.examplesDir) {
-        return buildExamplesFromDir(apiOptions.examplesDir);
+        return buildExamplesFromDir(apiOptions.examplesDir, apiOptions.examplesAssetsFallbackDir);
     }
     const loaded = loadPythonPackageMetadata({
         roots: apiOptions.metadataRoots,
@@ -203,54 +300,13 @@ function buildExampleWorkflows(apiOptions) {
                 required_providers: null,
                 required_models: null,
                 html_app: null,
+                app_doc: null,
                 etag: null
             });
         }
     }
     return workflows;
 }
-function loadExampleGraph(packageName, exampleName, apiOptions) {
-    const loaded = loadPythonPackageMetadata({
-        roots: apiOptions.metadataRoots,
-        maxDepth: apiOptions.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;
-    }
-}
-// ── deriveWorkflowName ─────────────────────────────────────────────────────
-function deriveWorkflowName(workflow) {
-    const graph = workflow.graph;
-    const nodes = graph?.nodes ?? [];
-    if (nodes.length === 0) {
-        return workflow.name || "Untitled Workflow";
-    }
-    const categories = new Set();
-    for (const n of nodes) {
-        if (typeof n.type === "string") {
-            const parts = n.type.split(".");
-            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`;
-}
 // ── Router ─────────────────────────────────────────────────────────────────
 export const workflowsRouter = router({
     // ── list (GET /api/workflows) ─────────────────────────────────────────────
@@ -260,34 +316,28 @@ export const workflowsRouter = router({
         .query(async ({ ctx, input }) => {
         const [workflows, cursor] = await Workflow.paginate(ctx.userId, {
             limit: input.limit,
-            runMode: input.run_mode
+            runMode: input.run_mode,
+            tag: input.tag,
+            projectId: input.project_id,
+            startKey: input.cursor
         });
+        let filtered = workflows;
+        if (input.mediaOutput) {
+            filtered = filtered.filter((w) => hasTerminalMediaOutput(w));
+        }
         return {
-            workflows: workflows.map((w) => toWorkflowResponse(w)),
-            next: cursor || null
+            workflows: filtered.map((w) => toWorkflowResponse(w)),
+            // mediaOutput filtering happens in memory after DB pagination, so cursor
+            // pagination is intentionally disabled for this mode.
+            next: input.mediaOutput ? null : cursor || null
         };
     }),
-    // ── names (GET /api/workflows/names) ─────────────────────────────────────
-    names: protectedProcedure
-        .output(namesOutput)
-        .query(async ({ ctx }) => {
-        const [workflows] = await Workflow.paginate(ctx.userId, { limit: 1000 });
-        const names = {};
-        for (const wf of workflows)
-            names[wf.id] = wf.name;
-        return names;
-    }),
     // ── get (GET /api/workflows/:id) ─────────────────────────────────────────
     get: protectedProcedure
         .input(getInput)
         .output(workflowResponse)
         .query(async ({ ctx, input }) => {
-        const workflow = (await Workflow.get(input.id));
-        if (!workflow)
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        if (workflow.access !== "public" && workflow.user_id !== ctx.userId) {
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        }
+        const { workflow } = await requireWorkflowRole(input.id, ctx.userId, "viewer");
         return toWorkflowResponse(workflow);
     }),
     // ── create (POST /api/workflows) ─────────────────────────────────────────
@@ -295,36 +345,13 @@ export const workflowsRouter = router({
         .input(createInput)
         .output(workflowResponse)
         .mutation(async ({ ctx, input }) => {
-        if (!input.graph || !Array.isArray(input.graph.nodes) || !Array.isArray(input.graph.edges)) {
-            throwApiError(ApiErrorCode.INVALID_INPUT, "graph is required and must have nodes and edges arrays");
-        }
-        let graph = input.graph;
-        // Optionally seed from example
-        if (input.from_example_package &&
-            input.from_example_name &&
-            (!graph || graph.nodes?.length === 0)) {
-            const example = loadExampleGraph(input.from_example_package, input.from_example_name, ctx.apiOptions);
-            if (example?.graph) {
-                graph = example.graph;
+        const workflow = await runWorkflowService(() => createWorkflow(ctx.userId, input, input.from_example_name
+            ? {
+                packageName: input.from_example_package ?? undefined,
+                exampleName: input.from_example_name,
+                apiOptions: ctx.apiOptions
             }
-        }
-        const workflow = (await Workflow.create({
-            user_id: ctx.userId,
-            name: input.name,
-            tool_name: input.tool_name ?? null,
-            package_name: input.package_name ?? null,
-            path: input.path ?? null,
-            tags: input.tags ?? [],
-            description: input.description ?? "",
-            thumbnail: input.thumbnail ?? null,
-            thumbnail_url: input.thumbnail_url ?? null,
-            access: input.access === "public" ? "public" : "private",
-            graph,
-            settings: input.settings ?? null,
-            run_mode: input.run_mode ?? "workflow",
-            workspace_id: input.workspace_id ?? null,
-            html_app: input.html_app ?? null
-        }));
+            : undefined));
         return toWorkflowResponse(workflow);
     }),
     // ── update (PUT /api/workflows/:id) ──────────────────────────────────────
@@ -332,51 +359,7 @@ export const workflowsRouter = router({
         .input(updateInput)
         .output(workflowResponse)
         .mutation(async ({ ctx, input }) => {
-        if (!input.graph || !Array.isArray(input.graph.nodes) || !Array.isArray(input.graph.edges)) {
-            throwApiError(ApiErrorCode.INVALID_INPUT, "graph is required and must have nodes and edges arrays");
-        }
-        const graph = input.graph;
-        const existing = (await Workflow.get(input.id));
-        if (existing && existing.user_id !== ctx.userId) {
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        }
-        if (existing) {
-            existing.name = input.name;
-            existing.tool_name = input.tool_name ?? null;
-            existing.description = input.description ?? "";
-            existing.tags = input.tags ?? [];
-            existing.package_name = input.package_name ?? null;
-            if (input.thumbnail !== undefined)
-                existing.thumbnail = input.thumbnail;
-            existing.access = input.access === "public" ? "public" : "private";
-            existing.graph = graph;
-            existing.settings = input.settings ?? null;
-            if (input.run_mode !== undefined && input.run_mode !== null)
-                existing.run_mode = input.run_mode;
-            existing.workspace_id = input.workspace_id ?? null;
-            existing.html_app = input.html_app ?? null;
-            await existing.save();
-            return toWorkflowResponse(existing);
-        }
-        // Upsert: create if doesn't exist
-        const workflow = (await Workflow.create({
-            id: input.id,
-            user_id: ctx.userId,
-            name: input.name,
-            tool_name: input.tool_name ?? null,
-            package_name: input.package_name ?? null,
-            path: input.path ?? null,
-            tags: input.tags ?? [],
-            description: input.description ?? "",
-            thumbnail: input.thumbnail ?? null,
-            thumbnail_url: input.thumbnail_url ?? null,
-            access: input.access === "public" ? "public" : "private",
-            graph,
-            settings: input.settings ?? null,
-            run_mode: input.run_mode ?? "workflow",
-            workspace_id: input.workspace_id ?? null,
-            html_app: input.html_app ?? null
-        }));
+        const workflow = await runWorkflowService(() => updateWorkflow(ctx.userId, input.id, input));
         return toWorkflowResponse(workflow);
     }),
     // ── delete (DELETE /api/workflows/:id) ───────────────────────────────────
@@ -384,123 +367,19 @@ export const workflowsRouter = router({
         .input(deleteInput)
         .output(deleteOutput)
         .mutation(async ({ ctx, input }) => {
-        const workflow = (await Workflow.get(input.id));
-        if (!workflow)
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        if (workflow.user_id !== ctx.userId) {
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        }
-        await workflow.delete();
+        await runWorkflowService(() => deleteWorkflow(ctx.userId, input.id));
+        lastAutosaveTime.delete(input.id);
         return { ok: true };
     }),
-    // ── run (POST /api/workflows/:id/run) ────────────────────────────────────
-    run: protectedProcedure
-        .input(runInput)
-        .output(runOutput)
-        .mutation(async ({ ctx, input }) => {
-        const workflow = await Workflow.find(ctx.userId, input.id);
-        if (!workflow)
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        const runMode = workflow.run_mode ?? "workflow";
-        if (runMode !== "workflow") {
-            throwApiError(ApiErrorCode.INVALID_INPUT, `Workflow run mode "${runMode}" is not supported by the standalone backend`);
-        }
-        const params = input.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 registry = ctx.registry;
-        const pythonBridge = ctx.pythonBridge;
-        const getPythonBridgeReady = ctx.getPythonBridgeReady;
-        const hasPythonNode = runnableGraph.nodes.some((node) => {
-            const nodeType = typeof node.type === "string" ? node.type : "";
-            return (nodeType !== "" &&
-                Boolean(registry.getMetadata(nodeType)) &&
-                !registry.has(nodeType));
-        });
-        if (hasPythonNode) {
-            if (!getPythonBridgeReady()) {
-                await pythonBridge.ensureConnected();
-            }
-        }
-        const resolveExecutor = (node) => {
-            if (registry.has(node.type)) {
-                return registry.resolve(node);
-            }
-            if (getPythonBridgeReady() && pythonBridge.hasNodeType(node.type)) {
-                const meta = pythonBridge
-                    .getNodeMetadata()
-                    .find((n) => n.node_type === node.type);
-                const props = (node.properties ?? {});
-                return new PythonNodeExecutor(pythonBridge, node.type, props, Object.fromEntries((meta?.outputs ?? []).map((o) => [o.name, o.type.type])), meta?.required_settings ?? []);
-            }
-            return registry.resolve(node);
-        };
-        const job = await Job.create({
-            workflow_id: input.id,
-            user_id: ctx.userId,
-            status: "running",
-            params,
-            graph: runnableGraph
-        });
-        const runner = new WorkflowRunner(job.id, { resolveExecutor });
-        const result = await runner.run({ job_id: job.id, workflow_id: input.id, params }, runnableGraph);
-        if (result.status === "completed") {
-            job.markCompleted();
-        }
-        else if (result.status === "cancelled") {
-            job.markCancelled();
-        }
-        else {
-            job.markFailed(result.error ?? "Workflow run failed");
-        }
-        await job.save();
-        return {
-            job_id: job.id,
-            workflow_id: input.id,
-            status: result.status,
-            outputs: result.outputs ?? null,
-            error: result.error ?? null,
-            message_count: result.messages.length,
-            background: input.background ?? false
-        };
-    }),
     // ── autosave (POST/PUT /api/workflows/:id/autosave) ───────────────────────
     autosave: protectedProcedure
         .input(autosaveInput)
         .output(autosaveOutput)
         .mutation(async ({ ctx, input }) => {
-        const workflow = (await Workflow.get(input.id));
-        if (!workflow)
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        if (workflow.user_id !== ctx.userId) {
-            throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        }
+        const { workflow, role } = await requireWorkflowRole(input.id, ctx.userId, "editor");
         const force = input.force === true;
-        const maxVersions = typeof input.max_versions === "number" ? input.max_versions : 10;
+        const { policy: retentionPolicy } = await getStorageRetentionSettings(ctx.userId);
+        const maxVersions = retentionPolicy.maxAutosavesPerWorkflow;
         // Rate-limit
         if (!force) {
             const last = lastAutosaveTime.get(input.id);
@@ -508,19 +387,28 @@ export const workflowsRouter = router({
                 return {
                     version: null,
                     message: "Autosave skipped (rate limited)",
-                    skipped: true
+                    skipped: true,
+                    updated_at: workflow.updated_at ?? null
                 };
             }
         }
-        workflow.graph = input.graph;
+        const fields = {
+            graph: input.graph
+        };
         if (input.name !== undefined)
-            workflow.name = input.name;
+            fields.name = input.name;
         if (input.description !== undefined)
-            workflow.description = input.description;
-        if (input.access === "public" || input.access === "private")
-            workflow.access = input.access;
-        await workflow.save();
-        lastAutosaveTime.set(input.id, Date.now());
+            fields.description = input.description;
+        // Only the owner can change visibility; editors keep it as-is.
+        if (role === "owner" &&
+            (input.access === "public" || input.access === "private"))
+            fields.access = input.access;
+        const savedWorkflow = await Workflow.updateFieldsIfUnchanged(input.id, input.expected_updated_at ?? workflow.updated_at, fields);
+        if (!savedWorkflow) {
+            throwApiError(ApiErrorCode.ALREADY_EXISTS, "Workflow was modified since last read (optimistic concurrency conflict)");
+        }
+        await syncTriggerRegistrations(savedWorkflow);
+        recordAutosave(input.id, Date.now());
         let version = null;
         try {
             const nextVer = await WorkflowVersion.nextVersion(input.id);
@@ -530,8 +418,8 @@ export const workflowsRouter = router({
                 graph: input.graph,
                 version: nextVer,
                 save_type: "autosave",
-                name: workflow.name,
-                description: workflow.description
+                name: savedWorkflow.name,
+                description: savedWorkflow.description
             });
             await wv.save();
             version = {
@@ -541,7 +429,7 @@ export const workflowsRouter = router({
                 save_type: wv.save_type ?? "autosave",
                 created_at: wv.created_at ?? null
             };
-            await WorkflowVersion.pruneOldVersions(input.id, maxVersions);
+            await WorkflowVersion.pruneOldAutosaves(input.id, maxVersions);
         }
         catch {
             // non-fatal — version table may not exist
@@ -549,24 +437,8 @@ export const workflowsRouter = router({
         return {
             version,
             message: "Autosaved successfully",
-            skipped: false
-        };
-    }),
-    // ── tools (GET /api/workflows/tools) ─────────────────────────────────────
-    tools: protectedProcedure
-        .input(toolsInput)
-        .output(toolsOutput)
-        .query(async ({ ctx, input }) => {
-        const [workflows] = await Workflow.paginateTools(ctx.userId, {
-            limit: input.limit
-        });
-        return {
-            workflows: workflows.map((w) => ({
-                name: w.name,
-                tool_name: w.tool_name ?? null,
-                description: w.description ?? null
-            })),
-            next: null
+            skipped: false,
+            updated_at: savedWorkflow.updated_at ?? null
         };
     }),
     // ── examples (GET /api/workflows/examples) ────────────────────────────────
@@ -589,13 +461,21 @@ export const workflowsRouter = router({
             : workflows;
         return { workflows: filtered, next: null };
     }),
+    // ── recipes (shipped chains of example workflows) ─────────────────────────
+    // Manifest files on disk, like the examples they order: no user, no database,
+    // and each step resolved against the examples this install actually ships.
+    recipes: protectedProcedure
+        .output(z.array(exampleRecipeSummary))
+        .query(({ ctx }) => listExampleRecipes(ctx.apiOptions)),
     // ── public workflows ──────────────────────────────────────────────────────
     public: router({
         list: publicProcedure
             .input(publicListInput)
             .output(publicListOutput)
             .query(async ({ input }) => {
-            const [workflows] = await Workflow.paginatePublic({ limit: input.limit });
+            const [workflows] = await Workflow.paginatePublic({
+                limit: input.limit
+            });
             return {
                 workflows: workflows.map((w) => toWorkflowResponse(w)),
                 next: null
@@ -612,30 +492,26 @@ export const workflowsRouter = router({
             return toWorkflowResponse(workflow);
         })
     }),
-    // ── app (GET /api/workflows/:id/app) ─────────────────────────────────────
-    app: protectedProcedure
-        .input(appInput)
-        .output(appOutput)
+    // ── terminalOutputs (GET /api/workflows/:id/terminal-outputs) ─────────────
+    // Returns the terminal media-output nodes of a workflow for the multi-output
+    // selection prompt in AddClipMenu.
+    terminalOutputs: protectedProcedure
+        .input(terminalOutputsInput)
+        .output(terminalOutputsOutput)
         .query(async ({ ctx, input }) => {
-        const baseUrl = input.baseUrl ?? ctx.apiOptions.baseUrl ?? "http://127.0.0.1:7777";
-        return {
-            workflow_id: input.id,
-            api_url: baseUrl
-        };
-    }),
-    // ── generateName (POST /api/workflows/:id/generate-name) ─────────────────
-    generateName: protectedProcedure
-        .input(generateNameInput)
-        .output(generateNameOutput)
-        .mutation(async ({ ctx, input }) => {
         const workflow = (await Workflow.get(input.id));
         if (!workflow)
             throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-        if (workflow.user_id !== ctx.userId) {
+        if (workflow.access !== "public" && workflow.user_id !== ctx.userId) {
             throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
         }
-        const name = deriveWorkflowName(workflow);
-        return { name };
+        const outputs = findTerminalMediaOutputNodes(workflow).map((n) => ({
+            id: n.id,
+            type: n.type,
+            mediaType: OUTPUT_NODE_MEDIA_TYPES[n.type],
+            name: n.data?.name ?? ""
+        }));
+        return { outputs };
     }),
     // ── versions ──────────────────────────────────────────────────────────────
     versions: router({
@@ -644,11 +520,8 @@ export const workflowsRouter = router({
             .input(versionsListInput)
             .output(versionsListOutput)
             .query(async ({ ctx, input }) => {
-            // Check ownership via the parent workflow
-            const workflow = (await Workflow.get(input.id));
-            if (!workflow || workflow.user_id !== ctx.userId) {
-                throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-            }
+            // Owners and editors see version history
+            await requireWorkflowRole(input.id, ctx.userId, "editor");
             const versions = await WorkflowVersion.listForWorkflow(input.id, {
                 limit: input.limit
             });
@@ -659,12 +532,7 @@ export const workflowsRouter = router({
             .input(versionCreateInput)
             .output(versionResponse)
             .mutation(async ({ ctx, input }) => {
-            const workflow = (await Workflow.get(input.id));
-            if (!workflow)
-                throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-            if (workflow.user_id !== ctx.userId) {
-                throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-            }
+            const { workflow } = await requireWorkflowRole(input.id, ctx.userId, "editor");
             const nextVer = await WorkflowVersion.nextVersion(input.id);
             const version = (await WorkflowVersion.create({
                 workflow_id: input.id,
@@ -676,29 +544,12 @@ export const workflowsRouter = router({
             }));
             return toVersionResponse(version);
         }),
-        // GET /api/workflows/:id/versions/:version
-        get: protectedProcedure
-            .input(versionGetInput)
-            .output(versionResponse)
-            .query(async ({ ctx, input }) => {
-            const workflow = (await Workflow.get(input.id));
-            if (!workflow || workflow.user_id !== ctx.userId) {
-                throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-            }
-            const version = await WorkflowVersion.findByVersion(input.id, input.version);
-            if (!version)
-                throwApiError(ApiErrorCode.NOT_FOUND, "Version not found");
-            return toVersionResponse(version);
-        }),
         // POST /api/workflows/:id/versions/:version/restore
         restore: protectedProcedure
             .input(versionRestoreInput)
             .output(workflowResponse)
             .mutation(async ({ ctx, input }) => {
-            const workflow = (await Workflow.get(input.id));
-            if (!workflow || workflow.user_id !== ctx.userId) {
-                throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
-            }
+            const { workflow } = await requireWorkflowRole(input.id, ctx.userId, "editor");
             const version = await WorkflowVersion.findByVersion(input.id, input.version);
             if (!version)
                 throwApiError(ApiErrorCode.NOT_FOUND, "Version not found");
@@ -715,11 +566,141 @@ export const workflowsRouter = router({
             if (!version)
                 throwApiError(ApiErrorCode.NOT_FOUND, "Version not found");
             if (version.user_id !== ctx.userId) {
-                throwApiError(ApiErrorCode.NOT_FOUND, "Version not found");
+                // The workflow owner may prune versions saved by collaborators.
+                const parent = (await Workflow.get(version.workflow_id));
+                if (!parent || parent.user_id !== ctx.userId) {
+                    throwApiError(ApiErrorCode.NOT_FOUND, "Version not found");
+                }
             }
             await version.delete();
             return { ok: true };
         })
+    }),
+    // ── sharing ────────────────────────────────────────────────────────────────
+    // Private sharing via role-scoped links: the owner mints a link, any
+    // authenticated user who redeems it becomes a collaborator (viewer/editor).
+    sharing: router({
+        // Collaborators + share links for the dialog. Owner only.
+        get: protectedProcedure
+            .input(sharingGetInput)
+            .output(sharingGetOutput)
+            .query(async ({ ctx, input }) => {
+            await requireWorkflowRole(input.id, ctx.userId, "owner");
+            const [collaborators, shares] = await Promise.all([
+                WorkflowCollaborator.listForWorkflow(input.id),
+                WorkflowShare.listForWorkflow(input.id)
+            ]);
+            return {
+                collaborators: collaborators.map(toCollaboratorItem),
+                shares: shares.map(toShareItem)
+            };
+        }),
+        // Mint (or return the existing active) share link for a role.
+        createLink: protectedProcedure
+            .input(sharingCreateLinkInput)
+            .output(shareItem)
+            .mutation(async ({ ctx, input }) => {
+            await requireWorkflowRole(input.id, ctx.userId, "owner");
+            const share = await WorkflowShare.ensure({
+                workflowId: input.id,
+                role: input.role,
+                createdBy: ctx.userId
+            });
+            return toShareItem(share);
+        }),
+        // Stop new redemptions of a link. Existing collaborators keep access.
+        revokeLink: protectedProcedure
+            .input(sharingRevokeLinkInput)
+            .output(sharingOkOutput)
+            .mutation(async ({ ctx, input }) => {
+            await requireWorkflowRole(input.id, ctx.userId, "owner");
+            const share = (await WorkflowShare.get(input.share_id));
+            if (!share || share.workflow_id !== input.id) {
+                throwApiError(ApiErrorCode.NOT_FOUND, "Share not found");
+            }
+            if (!share.isRevoked)
+                await share.revoke();
+            return { ok: true };
+        }),
+        // Change a collaborator's role. Owner only.
+        setRole: protectedProcedure
+            .input(sharingSetRoleInput)
+            .output(collaboratorItem)
+            .mutation(async ({ ctx, input }) => {
+            await requireWorkflowRole(input.id, ctx.userId, "owner");
+            const grant = await WorkflowCollaborator.findFor(input.id, input.user_id);
+            if (!grant) {
+                throwApiError(ApiErrorCode.NOT_FOUND, "Collaborator not found");
+            }
+            if (grant.role !== input.role) {
+                grant.role = input.role;
+                await grant.save();
+            }
+            return toCollaboratorItem(grant);
+        }),
+        // Remove a collaborator. Owner removes anyone; a collaborator may
+        // remove themself ("leave").
+        removeCollaborator: protectedProcedure
+            .input(sharingRemoveCollaboratorInput)
+            .output(sharingOkOutput)
+            .mutation(async ({ ctx, input }) => {
+            if (input.user_id !== ctx.userId) {
+                await requireWorkflowRole(input.id, ctx.userId, "owner");
+            }
+            const removed = await WorkflowCollaborator.remove(input.id, input.user_id);
+            if (!removed) {
+                throwApiError(ApiErrorCode.NOT_FOUND, "Collaborator not found");
+            }
+            return { ok: true };
+        }),
+        // Redeem a share link: the caller becomes a collaborator with the
+        // link's role and gets the workflow back for navigation.
+        accept: protectedProcedure
+            .input(sharingAcceptInput)
+            .output(sharingAcceptOutput)
+            .mutation(async ({ ctx, input }) => {
+            const share = await WorkflowShare.findByToken(input.token);
+            if (!share || share.isRevoked) {
+                throwApiError(ApiErrorCode.NOT_FOUND, "Share link is invalid or revoked");
+            }
+            const workflow = (await Workflow.get(share.workflow_id));
+            if (!workflow) {
+                throwApiError(ApiErrorCode.WORKFLOW_NOT_FOUND, "Workflow not found");
+            }
+            // The owner opening their own link is a no-op, not a grant.
+            if (workflow.user_id !== ctx.userId) {
+                await WorkflowCollaborator.upsert({
+                    workflowId: workflow.id,
+                    userId: ctx.userId,
+                    role: share.role,
+                    invitedBy: share.created_by
+                });
+            }
+            return { workflow: toWorkflowResponse(workflow), role: share.role };
+        }),
+        // Workflows shared with the caller, with their role on each.
+        sharedWithMe: protectedProcedure
+            .input(sharedWithMeInput)
+            .output(sharedWithMeOutput)
+            .query(async ({ ctx, input }) => {
+            const grants = await WorkflowCollaborator.listForUser(ctx.userId);
+            const limited = grants.slice(0, input.limit);
+            const loaded = await Promise.all(limited.map(async (grant) => ({
+                grant,
+                workflow: (await Workflow.get(grant.workflow_id))
+            })));
+            const workflows = [];
+            for (const { grant, workflow } of loaded) {
+                // Skip grants pointing at deleted workflows.
+                if (!workflow)
+                    continue;
+                workflows.push({
+                    ...toWorkflowResponse(workflow),
+                    shared_role: grant.role
+                });
+            }
+            return { workflows };
+        })
     })
 });
 //# sourceMappingURL=workflows.js.map