@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/capabilities/workflows.js

@@ -0,0 +1,1557 @@
+/**
+ * The `workflows` capability module — the pilot namespace.
+ *
+ * Ten capabilities that used to be ten `Tool` subclasses in
+ * `../tools/mcp-tools.ts`: the nine the guest reaches as `nodetool.workflows.*`
+ * (`NODETOOL_API_NAMESPACE_TOOLS.workflows`) plus `export_workflow_digraph`,
+ * which the design's mapping table folds in here rather than leaving it beside
+ * the file tools.
+ *
+ * Wire names, descriptions and schemas are unchanged: `getAllMcpTools` builds
+ * these through `toolFromCapability`, so every consumer — runner, MCP, CLI,
+ * evals — sees the surface it saw before.
+ *
+ * What was a constructor argument is now a field on the run: the example
+ * catalog, the node registry, the run environment, the DSL exporter, and the
+ * model catalogs. Every heavy dependency (`@nodetool-ai/models`, the execution
+ * service, the graph validators, the DSL sandbox) is imported inside the
+ * implementation that needs it, so loading this module costs nothing.
+ *
+ * Design: docs/tool-class-retirement-design.md § "Worked example:
+ * `nodetool.workflows`".
+ */
+import { NO_EXAMPLES, RUNTIME_MODEL_CATALOGS, annotateEscalatedRun, jobRecord, leftoverWiringHandleError, lightWorkflowList, modelSelectionError, noRegistryError, normalizeWorkflowGraph, outcomeResult, resolveRunEnvironment, summarizeWorkflowGraph, unsetModelSelectionWarning, userIdOf, workflowRecord } from "../tools/mcp-tool-support.js";
+import { PLAN_CORE_NODE_TYPES, checkWorkflowPlan, planNodeShape, planToPlacement, parseWorkflowPlan, refineWorkflowPlan, resolveWorkflowPlan, readEntityMarker, GAME_DESIGNER_SYSTEM_PROMPT, GAME_DESIGN_TOOL_DESCRIPTION, GAME_DESIGN_TOOL_NAME, GAME_INSPIRATION_CHIPS, WORKFLOW_PLANNER_SYSTEM_PROMPT, WORKFLOW_PLAN_TOOL_DESCRIPTION, WORKFLOW_PLAN_TOOL_NAME, buildGameDesignSchema, buildWorkflowPlanSchema, designSourceOf, gameAudioChoice, gameGraphPlacement, parseGameDesign } from "@nodetool-ai/protocol";
+import { gameDesign, readGameSetup, readWorkflowSetup, workflowSetupPlan, writeGameSetup, writeWorkflowSetup } from "@nodetool-ai/protocol/api-schemas/workflows.js";
+import { declareDynamicOutputsInGraph } from "../dynamic-slots.js";
+import { findCapability } from "./registry.js";
+import { REQUEST_SECRET_TOOL_NAME } from "./settings.specs.js";
+import { listWorkflowsSpec, getWorkflowSpec, createWorkflowSpec, updateWorkflowSpec, deleteWorkflowSpec, listWorkflowVersionsSpec, getWorkflowVersionSpec, createWorkflowVersionSpec, restoreWorkflowVersionSpec, deleteWorkflowVersionSpec, setWorkflowAccessSpec, runWorkflowCapabilitySpec, debugWorkflowSpec, resolveWorkflowEscalationSpec, validateWorkflowSpec, startBackgroundJobSpec, getExampleWorkflowSpec, exportWorkflowDigraphSpec, setWorkflowSetupSpec, planWorkflowSpec, updateWorkflowPlanStepSpec, buildWorkflowFromPlanSpec, setGameSetupSpec, designGameSpec, updateGameDesignSpec, buildGameSpec, DEFAULT_VERSION_LIMIT, MAX_VERSION_LIMIT } from "./workflows.specs.js";
+import { isNumber, isObjectLike, isString } from "../utils/type-guards.js";
+import { resolveProjectId } from "./project-scope.js";
+/** The run environment this run can execute a workflow in, or null. */
+function runEnvironmentOf(run) {
+    return resolveRunEnvironment(run.workflowEnvironment, run.nodeRegistry);
+}
+async function listUserWorkflows(run, limit) {
+    const { Workflow } = await import("@nodetool-ai/models");
+    const [workflows, next] = await Workflow.paginate(userIdOf(run.context), {
+        limit,
+        projectId: run.projectId
+    });
+    return lightWorkflowList({
+        workflows: workflows.map((w) => workflowRecord(w)),
+        next: next || null
+    });
+}
+async function listExampleWorkflows(run, query, limit) {
+    if (!run.examples)
+        return NO_EXAMPLES;
+    const listOptions = { limit };
+    if (query)
+        listOptions.query = query;
+    return lightWorkflowList({
+        workflows: await run.examples.list(listOptions),
+        next: null
+    });
+}
+const listWorkflows = {
+    spec: listWorkflowsSpec,
+    impl: async (run, params) => {
+        const workflowType = String(params["workflow_type"] ?? "user");
+        const query = params["query"];
+        const limit = Number(params["limit"] ?? 100);
+        if (workflowType === "example") {
+            return listExampleWorkflows(run, query, limit);
+        }
+        if (workflowType === "all") {
+            return {
+                examples: await listExampleWorkflows(run, query, limit),
+                user: await listUserWorkflows(run, limit)
+            };
+        }
+        return listUserWorkflows(run, limit);
+    }
+};
+// ---------------------------------------------------------------------------
+// get_workflow
+// ---------------------------------------------------------------------------
+const getWorkflow = {
+    spec: getWorkflowSpec,
+    impl: async (run, params) => {
+        const { Workflow } = await import("@nodetool-ai/models");
+        const workflowId = String(params["workflow_id"]);
+        const workflow = await Workflow.find(userIdOf(run.context), workflowId);
+        if (!workflow)
+            return { error: `Workflow ${workflowId} was not found.` };
+        if (run.projectId !== undefined && workflow.project_id !== run.projectId) {
+            return { error: `Workflow ${workflowId} was not found.` };
+        }
+        return workflowRecord(workflow);
+    }
+};
+const createWorkflow = {
+    spec: createWorkflowSpec,
+    impl: async (run, params) => {
+        const { Project, Workflow } = await import("@nodetool-ai/models");
+        const projectId = resolveProjectId(run, params);
+        if (projectId !== "default" &&
+            !(await Project.findOwned(userIdOf(run.context), projectId))) {
+            return { error: "Project not found." };
+        }
+        // Declare before normalizing, so the handle is on the node the editor,
+        // the validator and every later run read. Without a registry this is the
+        // identity function and the graph is stored exactly as it arrived.
+        const authored = run.nodeRegistry
+            ? declareDynamicOutputsInGraph(params["graph"], run.nodeRegistry)
+            : params["graph"];
+        const graph = normalizeWorkflowGraph(authored);
+        const badModels = await modelSelectionError(graph, run.modelCatalogs ?? RUNTIME_MODEL_CATALOGS);
+        if (badModels)
+            return badModels;
+        const leftoverHandles = leftoverWiringHandleError(graph);
+        if (leftoverHandles)
+            return leftoverHandles;
+        const unselected = run.nodeRegistry
+            ? unsetModelSelectionWarning(graph, run.nodeRegistry)
+            : null;
+        const created = (await Workflow.create({
+            user_id: userIdOf(run.context),
+            name: String(params["name"]),
+            description: isString(params["description"]) ? params["description"] : "",
+            tags: Array.isArray(params["tags"]) ? params["tags"] : [],
+            access: params["access"] === "public" ? "public" : "private",
+            graph: graph,
+            run_mode: "workflow",
+            project_id: projectId
+        }));
+        return { ...workflowRecord(created), ...unselected };
+    }
+};
+/**
+ * The one ownership test the three lifecycle capabilities share.
+ *
+ * `Workflow.find` is deliberately not it: that answers for a public workflow
+ * and for one shared with the caller as well, so writing a mutation on top of
+ * it would let a run rewrite or publish a workflow it can merely read. Missing
+ * and not-yours are one answer, so a caller cannot probe for ids.
+ */
+async function findOwnedWorkflow(run, id) {
+    const { Workflow } = await import("@nodetool-ai/models");
+    const wf = (await Workflow.get(id));
+    if (!wf || wf.user_id !== userIdOf(run.context))
+        return null;
+    if (run.projectId !== undefined && wf.project_id !== run.projectId) {
+        return null;
+    }
+    return wf;
+}
+function notYours(id) {
+    return { error: `Workflow ${id} was not found, or it is not yours.` };
+}
+const updateWorkflow = {
+    spec: updateWorkflowSpec,
+    impl: async (run, params) => {
+        const { Workflow } = await import("@nodetool-ai/models");
+        const id = String(params["workflow_id"]);
+        const existing = await findOwnedWorkflow(run, id);
+        if (!existing)
+            return notYours(id);
+        const fields = {};
+        let unselected = null;
+        if (params["graph"] !== undefined) {
+            // The same three passes create_workflow runs, in the same order: an
+            // update that skipped them could store a graph the create path would
+            // have refused.
+            const authored = run.nodeRegistry
+                ? declareDynamicOutputsInGraph(params["graph"], run.nodeRegistry)
+                : params["graph"];
+            const graph = normalizeWorkflowGraph(authored);
+            const badModels = await modelSelectionError(graph, run.modelCatalogs ?? RUNTIME_MODEL_CATALOGS);
+            if (badModels)
+                return badModels;
+            const leftoverHandles = leftoverWiringHandleError(graph);
+            if (leftoverHandles)
+                return leftoverHandles;
+            if (run.nodeRegistry) {
+                unselected = unsetModelSelectionWarning(graph, run.nodeRegistry);
+            }
+            fields.graph = graph;
+        }
+        if (isString(params["name"]))
+            fields.name = params["name"];
+        if (isString(params["description"])) {
+            fields.description = params["description"];
+        }
+        if (Array.isArray(params["tags"]))
+            fields.tags = params["tags"];
+        if (Object.keys(fields).length === 0) {
+            return { error: "Nothing to update — pass graph, name, description or tags." };
+        }
+        // `access` is not in the field set on purpose. Publishing is its own
+        // capability because it is its own permission class.
+        const expected = isString(params["expected_updated_at"])
+            ? params["expected_updated_at"]
+            : existing.updated_at;
+        const updated = await Workflow.updateFieldsIfUnchanged(id, expected, fields, 
+        // A whole-graph write names no units, so an open editor falls back to
+        // diff-based touching instead of treating the graph as replaced.
+        "graph" in fields ? { ops: [{ tool: "update_graph", input: {} }] } : undefined);
+        if (!updated) {
+            return {
+                error: `Workflow ${id} changed since you read it — read it again and retry.`
+            };
+        }
+        return { ...workflowRecord(updated), ...unselected };
+    }
+};
+const deleteWorkflow = {
+    spec: deleteWorkflowSpec,
+    impl: async (run, params) => {
+        const { Workflow } = await import("@nodetool-ai/models");
+        const id = String(params["workflow_id"]);
+        const deleted = await Workflow.deleteOwned(userIdOf(run.context), id);
+        return deleted ? { workflow_id: id, deleted: true } : notYours(id);
+    }
+};
+function versionNumber(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        return {
+            error: "version must be a positive integer (use list_workflow_versions to see the available ones)."
+        };
+    }
+    return n;
+}
+function toVersionListItem(version) {
+    return {
+        id: version.id,
+        version: version.version,
+        name: version.name,
+        description: version.description,
+        save_type: version.save_type,
+        created_at: version.created_at
+    };
+}
+const listWorkflowVersions = {
+    spec: listWorkflowVersionsSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const existing = await findOwnedWorkflow(run, id);
+        if (!existing)
+            return notYours(id);
+        const { WorkflowVersion } = await import("@nodetool-ai/models");
+        const limit = Math.max(1, Math.min(Number(params["limit"]) || DEFAULT_VERSION_LIMIT, MAX_VERSION_LIMIT));
+        const versions = await WorkflowVersion.listForWorkflow(id, { limit });
+        return {
+            workflow_id: id,
+            name: existing.name,
+            versions: versions.map(toVersionListItem)
+        };
+    }
+};
+const getWorkflowVersion = {
+    spec: getWorkflowVersionSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const existing = await findOwnedWorkflow(run, id);
+        if (!existing)
+            return notYours(id);
+        const number = versionNumber(params["version"]);
+        if (typeof number !== "number")
+            return number;
+        const { WorkflowVersion } = await import("@nodetool-ai/models");
+        const version = await WorkflowVersion.findByVersion(id, number);
+        if (!version) {
+            return {
+                error: `Workflow ${id} has no version ${number}. Call list_workflow_versions to see the available ones.`
+            };
+        }
+        return {
+            workflow_id: id,
+            ...toVersionListItem(version),
+            graph: version.graph
+        };
+    }
+};
+const createWorkflowVersion = {
+    spec: createWorkflowVersionSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const existing = await findOwnedWorkflow(run, id);
+        if (!existing)
+            return notYours(id);
+        const { WorkflowVersion } = await import("@nodetool-ai/models");
+        const nextVer = await WorkflowVersion.nextVersion(id);
+        const version = (await WorkflowVersion.create({
+            workflow_id: id,
+            user_id: userIdOf(run.context),
+            name: isString(params["name"]) ? params["name"] : null,
+            description: isString(params["description"])
+                ? params["description"]
+                : null,
+            graph: existing.graph,
+            version: nextVer,
+            save_type: "manual"
+        }));
+        return {
+            ok: true,
+            workflow_id: id,
+            ...toVersionListItem(version)
+        };
+    }
+};
+const restoreWorkflowVersion = {
+    spec: restoreWorkflowVersionSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const existing = await findOwnedWorkflow(run, id);
+        if (!existing)
+            return notYours(id);
+        const number = versionNumber(params["version"]);
+        if (typeof number !== "number")
+            return number;
+        const { Workflow, WorkflowVersion } = await import("@nodetool-ai/models");
+        const version = await WorkflowVersion.findByVersion(id, number);
+        if (!version) {
+            return {
+                error: `Workflow ${id} has no version ${number}. Call list_workflow_versions to see the available ones.`
+            };
+        }
+        const undoVer = await WorkflowVersion.nextVersion(id);
+        const undo = (await WorkflowVersion.create({
+            workflow_id: id,
+            user_id: userIdOf(run.context),
+            name: `Before restore to v${number}`,
+            description: null,
+            graph: existing.graph,
+            version: undoVer,
+            save_type: "restore"
+        }));
+        const updated = await Workflow.updateFieldsIfUnchanged(id, existing.updated_at, { graph: version.graph }, 
+        // Whole-graph restore: no unit attribution, diff-based touching.
+        { ops: [{ tool: "restore_version", input: {} }] });
+        if (!updated) {
+            return {
+                error: `Workflow ${id} changed since you read it — read it again and retry.`,
+                undo_version: undo.version
+            };
+        }
+        return {
+            ok: true,
+            workflow_id: id,
+            restored_version: number,
+            undo_version: undo.version,
+            ...workflowRecord(updated)
+        };
+    }
+};
+const deleteWorkflowVersion = {
+    spec: deleteWorkflowVersionSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const existing = await findOwnedWorkflow(run, id);
+        if (!existing)
+            return notYours(id);
+        const number = versionNumber(params["version"]);
+        if (typeof number !== "number")
+            return number;
+        const { WorkflowVersion } = await import("@nodetool-ai/models");
+        const version = await WorkflowVersion.findByVersion(id, number);
+        if (!version) {
+            return {
+                error: `Workflow ${id} has no version ${number}. Call list_workflow_versions to see the available ones.`
+            };
+        }
+        await version.delete();
+        return {
+            ok: true,
+            workflow_id: id,
+            deleted_version: number
+        };
+    }
+};
+const setWorkflowAccess = {
+    spec: setWorkflowAccessSpec,
+    impl: async (run, params) => {
+        const { Workflow } = await import("@nodetool-ai/models");
+        const id = String(params["workflow_id"]);
+        const access = params["access"] === "public" ? "public" : "private";
+        const existing = await findOwnedWorkflow(run, id);
+        if (!existing)
+            return notYours(id);
+        const updated = await Workflow.updateFieldsIfUnchanged(id, existing.updated_at, { access }, { ops: [{ tool: "set_link", input: { access } }] });
+        if (!updated) {
+            return {
+                error: `Workflow ${id} changed since it was read — retry.`
+            };
+        }
+        return { workflow_id: id, access };
+    }
+};
+const runWorkflowCapability = {
+    spec: runWorkflowCapabilitySpec,
+    impl: async (run, params) => {
+        const env = await runEnvironmentOf(run);
+        if (!env)
+            return noRegistryError("run a workflow");
+        const { runWorkflow } = await import("@nodetool-ai/execution/service");
+        const outcome = await runWorkflow({
+            workflowId: String(params["workflow_id"]),
+            userId: userIdOf(run.context),
+            environment: env,
+            params: params["params"] ?? {},
+            interactive: params["interactive"] === true,
+            // A run started from a project's agent thread is that project's spend.
+            projectId: run.projectId ?? null
+        });
+        return annotateEscalatedRun(outcomeResult(outcome));
+    }
+};
+const debugWorkflow = {
+    spec: debugWorkflowSpec,
+    impl: async (run, params) => {
+        const env = await runEnvironmentOf(run);
+        if (!env)
+            return noRegistryError("debug a workflow");
+        const { Job, Workflow } = await import("@nodetool-ai/models");
+        const { runWorkflow } = await import("@nodetool-ai/execution/service");
+        const workflowId = String(params["workflow_id"]);
+        const userId = userIdOf(run.context);
+        const includeGraph = params["include_graph"] !== false;
+        const outcome = await runWorkflow({
+            workflowId,
+            userId,
+            debug: true,
+            environment: env,
+            params: params["params"] ?? {},
+            interactive: params["interactive"] === true,
+            projectId: run.projectId ?? null
+        });
+        // A run the service refused never started, so there is no report to nest.
+        // Nesting it under `run` put the failure where nothing looks: the caller
+        // reads a `{workflow_id, run}` record, and the sandbox dispatcher — which
+        // throws on a top-level `{error}` so a guest cannot compute with a
+        // failure — sees an ordinary object. A 404 came back as a value the guest
+        // logged as `Status: 404` and carried on from. `run_workflow` and
+        // `start_background_job` already return this at the top level.
+        if (outcome.kind !== "payload") {
+            return outcomeResult(outcome);
+        }
+        const result = outcomeResult(outcome);
+        // An escalated run has produced no report yet — the job is parked on the
+        // failing node. Hand the escalation back for a verdict; the final report
+        // arrives from resolve_workflow_escalation once the run settles.
+        if (isObjectLike(result) &&
+            result["status"] === "escalated") {
+            return { workflow_id: workflowId, run: annotateEscalatedRun(result) };
+        }
+        const report = {
+            workflow_id: workflowId,
+            run: result
+        };
+        const jobId = result?.["job_id"];
+        if (isString(jobId)) {
+            const job = await Job.find(userId, jobId);
+            if (job) {
+                const logLimit = Number(params["log_limit"] ?? 200);
+                const logs = job.logs ?? [];
+                report["job"] = {
+                    ...jobRecord(job),
+                    logs: logs.slice(Math.max(0, logs.length - logLimit))
+                };
+            }
+        }
+        if (includeGraph) {
+            const workflow = await Workflow.find(userId, workflowId);
+            if (workflow) {
+                report["workflow"] = summarizeWorkflowGraph(workflowRecord(workflow));
+            }
+        }
+        return report;
+    }
+};
+const resolveWorkflowEscalation = {
+    spec: resolveWorkflowEscalationSpec,
+    impl: async (run, params) => {
+        const { submitEscalationVerdict } = await import("@nodetool-ai/execution/service");
+        const action = String(params["action"]);
+        const verdict = { action };
+        if (action === "substitute" && params["outputs"] !== undefined) {
+            verdict["outputs"] = params["outputs"];
+        }
+        if (action === "fail" && isString(params["reason"])) {
+            verdict["reason"] = params["reason"];
+        }
+        if ((action === "skip" || action === "fail") &&
+            isString(params["apply_to"])) {
+            verdict["applyTo"] = params["apply_to"];
+        }
+        const outcome = await submitEscalationVerdict(String(params["session_id"]), userIdOf(run.context), String(params["escalation_id"]), verdict);
+        return annotateEscalatedRun(outcomeResult(outcome));
+    }
+};
+const validateWorkflow = {
+    spec: validateWorkflowSpec,
+    impl: async (run, params) => {
+        let graph = params["graph"];
+        const workflowId = params["workflow_id"];
+        const code = isString(params["code"]) ? params["code"] : "";
+        // A legacy graph program can be checked in the form it was authored in
+        // rather than hand-translated to JSON first.
+        if (code.trim()) {
+            const { evaluateGraphDsl } = await import("../graph-dsl.js");
+            const evaluated = await evaluateGraphDsl(code);
+            if (!evaluated.graph) {
+                const failure = {
+                    status: "code_error",
+                    error: evaluated.error ?? "Program produced no graph."
+                };
+                if (evaluated.logs?.length)
+                    failure.logs = evaluated.logs;
+                return failure;
+            }
+            graph = evaluated.graph;
+        }
+        if (!graph && workflowId) {
+            const { Workflow } = await import("@nodetool-ai/models");
+            const workflow = await Workflow.find(userIdOf(run.context), workflowId);
+            if (!workflow)
+                return { error: `Workflow ${workflowId} was not found.` };
+            graph = workflow.getGraph();
+        }
+        if (!graph || !Array.isArray(graph.nodes)) {
+            return {
+                error: "No graph to validate — pass a graph program as `code`, an inline `graph` ({nodes, edges}), or a valid `workflow_id`."
+            };
+        }
+        // `edges` reaches `.map()` inside validateGraph — a non-array would throw a
+        // raw TypeError past the tool's structured error shape.
+        if (graph.edges !== undefined && !Array.isArray(graph.edges)) {
+            return {
+                error: "`graph.edges` must be an array of edges ({source, sourceHandle, target, targetHandle})."
+            };
+        }
+        const registry = run.nodeRegistry;
+        if (!registry) {
+            // Returning the graph with a note read as a pass to every caller that
+            // checks for issues rather than for prose. A validator with no registry
+            // cannot validate; say so as an error.
+            return {
+                error: "Cannot validate: no node registry is available in this process. Run `nodetool validate` from the CLI, or call this tool from a server-side context with a registry.",
+                validated: false
+            };
+        }
+        // The provider and model catalogs are supplied by the run rather than
+        // living on NodeRegistry: the registry also runs in the browser, which has
+        // neither to reach. Without them `validateGraph` skips the
+        // `unknown_provider` and `unknown_model` checks entirely, so a model
+        // naming a provider the runtime cannot construct — or an id that provider
+        // does not offer — would pass silently on the agent surface, which is
+        // exactly where hallucinated ids come from. This capability always runs
+        // server-side, so the runtime's own catalogs are the right default.
+        const catalogs = run.modelCatalogs ?? RUNTIME_MODEL_CATALOGS;
+        // An outgoing edge declares the source's dynamic output handle. The tool
+        // path does this in `GraphBuilder`; a graph the DSL pack authors arrives
+        // here as data and has never seen one, so the same rule runs on the JSON.
+        const declared = declareDynamicOutputsInGraph(graph, registry);
+        const { collectSecretRequirementSites, validateGraph } = await import("@nodetool-ai/node-sdk");
+        const registryView = {
+            has: (type) => registry.has(type),
+            getMetadata: (type) => registry.getMetadata(type),
+            validateNode: (descriptor, connectedHandles) => registry.validateNode(descriptor, connectedHandles),
+            listProviderIds: () => catalogs.listProviderIds(),
+            listModelIds: (provider, modelType) => catalogs.listModelIds(provider, modelType),
+            listRequiredTextInputs: (provider, modelType, modelId) => catalogs.listRequiredTextInputs?.(provider, modelType, modelId)
+        };
+        const checked = {
+            nodes: declared.nodes,
+            edges: (declared.edges ?? [])
+        };
+        // The credentials the graph's nodes declare are collected first so the
+        // host resolves exactly those names — one store round trip per
+        // requirement, not one per key it holds. A run with no reachable store
+        // carries no resolver and the check is skipped: reporting every declared
+        // key as missing because nothing could answer is the false alarm this
+        // whole path fails toward silence to avoid.
+        let availableSecrets;
+        if (run.availableSecrets) {
+            const sites = collectSecretRequirementSites(checked, registryView);
+            if (sites.length > 0) {
+                availableSecrets = await run.availableSecrets(sites.map((site) => site.key));
+            }
+        }
+        const report = validateGraph(checked, registryView, { availableSecrets });
+        return await withSecretRemediation(run, report);
+    }
+};
+/**
+ * Tell the agent what to do about a `missing_secret` warning.
+ *
+ * The validator says a key is missing; only the run knows how this agent can
+ * get one set. Settings → Credentials is always the answer a person can act
+ * on; `request_secret` is added only where this run can actually serve it —
+ * it needs the capability *and* a host that can raise the dialog, and a
+ * headless run has neither, so naming it there sends the agent at a call that
+ * fails closed.
+ */
+async function withSecretRemediation(run, report) {
+    if (!report.issues.some((issue) => issue.code === "missing_secret")) {
+        return report;
+    }
+    const canAsk = run.secretPrompt !== undefined &&
+        (await findCapability(REQUEST_SECRET_TOOL_NAME)) !== undefined;
+    const remediation = canAsk
+        ? "Ask the user to set it in Settings → Credentials, or call " +
+            `\`${REQUEST_SECRET_TOOL_NAME}\` to have them enter it now.`
+        : "Ask the user to set it in Settings → Credentials.";
+    return {
+        ...report,
+        issues: report.issues.map((issue) => issue.code === "missing_secret"
+            ? { ...issue, message: `${issue.message} ${remediation}` }
+            : issue)
+    };
+}
+// ---------------------------------------------------------------------------
+// start_background_job
+// ---------------------------------------------------------------------------
+const startBackgroundJob = {
+    spec: startBackgroundJobSpec,
+    impl: async (run, params) => {
+        const env = await runEnvironmentOf(run);
+        if (!env)
+            return noRegistryError("start a background job");
+        const { runWorkflow } = await import("@nodetool-ai/execution/service");
+        const outcome = await runWorkflow({
+            workflowId: String(params["workflow_id"]),
+            userId: userIdOf(run.context),
+            environment: env,
+            params: params["params"] ?? {},
+            background: true,
+            projectId: run.projectId ?? null
+        });
+        return outcomeResult(outcome);
+    }
+};
+// ---------------------------------------------------------------------------
+// get_example_workflow
+// ---------------------------------------------------------------------------
+const getExampleWorkflow = {
+    spec: getExampleWorkflowSpec,
+    impl: async (run, params) => {
+        if (!run.examples)
+            return NO_EXAMPLES;
+        const packageName = String(params["package_name"]);
+        const exampleName = String(params["example_name"]);
+        const example = await run.examples.get(packageName, exampleName);
+        return (example ?? {
+            error: `No example named "${exampleName}" in package "${packageName}".`
+        });
+    }
+};
+// ---------------------------------------------------------------------------
+// export_workflow_digraph
+// ---------------------------------------------------------------------------
+const exportWorkflowDigraph = {
+    spec: exportWorkflowDigraphSpec,
+    // `workflowToDsl` lives in `@nodetool-ai/dsl`, which sits above this package
+    // in the dependency order, so the exporter rides on the run rather than
+    // being imported.
+    impl: async (run, params) => {
+        const exportDsl = run.exportDsl;
+        if (!exportDsl) {
+            return {
+                error: "Cannot export: no DSL exporter is available in this process. Run " +
+                    "`nodetool workflows export-dsl` from the CLI instead."
+            };
+        }
+        const { Workflow } = await import("@nodetool-ai/models");
+        const workflowId = String(params["workflow_id"]);
+        const workflow = await Workflow.find(userIdOf(run.context), workflowId);
+        if (!workflow)
+            return { error: `Workflow ${workflowId} was not found.` };
+        if (!workflow.graph)
+            return { error: "Workflow has no graph to export." };
+        try {
+            return {
+                workflow_id: workflowId,
+                source: exportDsl(workflow.graph, { workflowName: workflow.name })
+            };
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+};
+// ── Guided setup (PRD § 11.6) ────────────────────────────────────────────────
+//
+// The headless half of the Workflow creation flow: write the setup answers,
+// plan the steps, edit one step, build the graph from the plan. The browser
+// drives the same four through `ui_workflow_set_setup`, `ui_workflow_plan`,
+// `ui_workflow_update_plan_step` and `ui_workflow_build_from_plan`, and both
+// halves share the planner contract and the plan→graph builder in
+// `@nodetool-ai/protocol`, so a plan built here places the nodes the editor
+// would have placed.
+//
+// Two rules carry the phase and both are asserted:
+//
+//  - `plan_workflow` places no node (criterion 3). It writes text and nothing
+//    else.
+//  - `build_workflow_from_plan` refuses a plan that still names an unknown node
+//    type or an unavailable model role (D23), and reports the wiring it could
+//    not do rather than reporting a graph that validates and produces nothing
+//    (R6).
+/** How many candidate node types the planner prompt lists. */
+const CANDIDATE_LIMIT = 60;
+/**
+ * Which model role each provider capability answers. Read to decide whether a
+ * step's role is covered — the same question the review step's amber marker
+ * asks in the browser (D23).
+ */
+const ROLE_CAPABILITY = {
+    language: "generate_message",
+    image: "text_to_image",
+    video: "text_to_video",
+    audio: "text_to_speech"
+};
+async function loadOwned(run, id) {
+    const { Workflow } = await import("@nodetool-ai/models");
+    const row = (await Workflow.get(id));
+    if (!row || row.user_id !== userIdOf(run.context)) {
+        return { error: `Workflow ${id} was not found, or it is not yours.` };
+    }
+    return { row, setup: readWorkflowSetup(row.settings) };
+}
+const isError = (value) => isObjectLike(value) && isString(value.error);
+/** Write a setup patch back onto the row, leaving the rest of `settings` alone. */
+async function persistSetup(row, patch, extra = {}) {
+    const { Workflow } = await import("@nodetool-ai/models");
+    const fields = {
+        settings: writeWorkflowSetup(row.settings, patch)
+    };
+    if (extra.graph !== undefined) {
+        fields.graph = extra.graph;
+    }
+    const updated = await Workflow.updateFieldsIfUnchanged(row.id, row.updated_at, fields);
+    if (!updated) {
+        return {
+            error: `Workflow ${row.id} changed since you read it — read it again and retry.`
+        };
+    }
+    return updated;
+}
+/** The plan on the row, or the reason there is none to act on. */
+function requirePlan(setup) {
+    const plan = setup?.plan;
+    if (!plan) {
+        return {
+            error: "This workflow has no plan yet. Run plan_workflow first, or store one with plan_workflow's `plan` argument."
+        };
+    }
+    return plan;
+}
+/** Grade a plan against the live registry and this install's providers. */
+async function reviewPlan(run, plan) {
+    const registry = run.nodeRegistry;
+    const providers = run.providers ?? {};
+    const capabilities = new Set();
+    for (const provider of Object.values(providers)) {
+        for (const capability of provider.getCapabilities()) {
+            capabilities.add(capability);
+        }
+    }
+    return resolveWorkflowPlan(plan, {
+        // With no registry nothing can be confirmed, so every step reads unknown
+        // and the build is blocked — the same answer validate_workflow gives.
+        knownNodeType: (type) => registry?.has(type) === true,
+        providerConfigured: (role) => {
+            const capability = ROLE_CAPABILITY[role];
+            // A role nothing maps to is not a provider question; do not block on it.
+            if (capability === undefined)
+                return true;
+            return capabilities.size === 0 ? false : capabilities.has(capability);
+        }
+    });
+}
+/** Shape the review into the marker list the caller renders (D23). */
+function reviewReport(resolved) {
+    return {
+        can_continue: resolved.canContinue,
+        missing_roles: resolved.missingRoles,
+        steps: resolved.steps.map((entry) => ({
+            id: entry.step.id,
+            title: entry.step.title,
+            summary: entry.step.summary,
+            node_type: entry.step.node_type,
+            model_role: entry.step.model_role ?? null,
+            unknown_node_type: entry.unknownNodeType,
+            missing_provider: entry.missingProvider,
+            block: entry.block
+        }))
+    };
+}
+/** The registry lookup the builder wires from. */
+function registryLookup(registry) {
+    return (nodeType) => {
+        const meta = registry.getMetadata(nodeType);
+        return meta ? planNodeShape(meta) : null;
+    };
+}
+/**
+ * A placement as a workflow graph. The Workflow flow's build and the Game
+ * flow's build write the same node shape, so one function answers both — a
+ * second copy is how `setup_step_id` or `dynamic_properties` goes missing on
+ * one of them.
+ */
+function placementToGraph(placement) {
+    return {
+        nodes: placement.nodes.map((node) => ({
+            id: node.id,
+            type: node.type,
+            data: node.properties,
+            ui_properties: { position: node.position, setup_step_id: node.setupStepId },
+            dynamic_properties: node.dynamicProperties ?? {},
+            dynamic_outputs: node.dynamicOutputs ?? {}
+        })),
+        edges: placement.edges.map((edge, index) => ({
+            id: `e${index + 1}`,
+            source: edge.source,
+            sourceHandle: edge.sourceHandle,
+            target: edge.target,
+            targetHandle: edge.targetHandle
+        }))
+    };
+}
+// ── set_workflow_setup ──────────────────────────────────────────────────────
+const setWorkflowSetup = {
+    spec: setWorkflowSetupSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwned(run, id);
+        if (isError(owned))
+            return owned;
+        const patch = {};
+        if (isString(params["brief"]))
+            patch.brief = params["brief"];
+        if (isString(params["category"]))
+            patch.category = params["category"];
+        if (isString(params["run_mode"])) {
+            patch.run_mode = params["run_mode"];
+        }
+        if (isString(params["stage"])) {
+            patch.stage = params["stage"];
+        }
+        if (Object.keys(patch).length === 0) {
+            return {
+                error: "Nothing to set — pass brief, category, run_mode or stage."
+            };
+        }
+        const saved = await persistSetup(owned.row, patch);
+        if (isError(saved))
+            return saved;
+        return { workflow_id: id, setup: readWorkflowSetup(saved.settings) };
+    }
+};
+// ── plan_workflow ───────────────────────────────────────────────────────────
+/**
+ * Candidate node types for the planner prompt: the general-purpose nodes
+ * first, then the registry's ranking against the brief.
+ */
+function candidateLines(registry, terms) {
+    const core = PLAN_CORE_NODE_TYPES.flatMap((nodeType) => {
+        const meta = registry.getMetadata(nodeType);
+        return meta ? [meta] : [];
+    });
+    const seen = new Set(core.map((meta) => meta.node_type));
+    const ranked = registry
+        .searchMetadata(terms)
+        .map((entry) => entry.meta)
+        .filter((meta) => !seen.has(meta.node_type));
+    return [...core, ...ranked]
+        .slice(0, CANDIDATE_LIMIT)
+        .map((meta) => `- ${meta.node_type}: ${meta.title} — ${meta.description.split("\n")[0]}`);
+}
+const planWorkflow = {
+    spec: planWorkflowSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwned(run, id);
+        if (isError(owned))
+            return owned;
+        const brief = owned.setup?.brief?.trim() ?? "";
+        const supplied = params["plan"];
+        let plan = null;
+        let planProblems = [];
+        if (supplied !== undefined) {
+            // A plan handed in replaces the model call outright: it is how a harness
+            // case and a replay reach the builder with no provider at all.
+            const parsed = workflowSetupPlan.safeParse(parseWorkflowPlan(supplied) ?? supplied);
+            if (!parsed.success) {
+                return { error: "`plan` is not a plan ({inputs, steps, outputs})." };
+            }
+            plan = parsed.data;
+        }
+        else {
+            if (brief.length === 0) {
+                return {
+                    error: "This workflow has no brief, so there is nothing to plan. Write one with set_workflow_setup first."
+                };
+            }
+            const registry = run.nodeRegistry;
+            if (!registry) {
+                return {
+                    error: "Cannot plan: no node registry is available in this process, so no step could name a node type that exists."
+                };
+            }
+            const provider = isString(params["provider"]) ? params["provider"] : "";
+            const model = isString(params["model"]) ? params["model"] : "";
+            if (provider.length === 0 || model.length === 0) {
+                return {
+                    error: "Pass provider and model to plan, or pass a `plan` to store without calling one."
+                };
+            }
+            const { generateStructured } = await import("@nodetool-ai/runtime");
+            const { plannedCodeStepProblems } = await import("@nodetool-ai/node-sdk/code-analysis");
+            const category = owned.setup?.category ?? "";
+            const terms = brief
+                .split(/\s+/)
+                .filter((term) => term.length > 2);
+            const candidates = candidateLines(registry, terms);
+            const planner = await run.context.getProvider(provider);
+            // The same check-and-repair loop the browser flow runs: a plan reaches
+            // review only after it builds, or after the round limit with its
+            // remaining problems reported.
+            const refined = await refineWorkflowPlan({
+                messages: [
+                    { role: "system", content: WORKFLOW_PLANNER_SYSTEM_PROMPT },
+                    {
+                        role: "user",
+                        content: [
+                            `Task: ${brief}`,
+                            category ? `Kind of workflow: ${category}` : "",
+                            "",
+                            "Candidate node types:",
+                            ...candidates
+                        ]
+                            .filter((line) => line !== "")
+                            .join("\n")
+                    }
+                ],
+                generate: (messages) => generateStructured(planner, {
+                    model,
+                    maxTokens: 4096,
+                    messages: [...messages],
+                    toolName: WORKFLOW_PLAN_TOOL_NAME,
+                    toolDescription: WORKFLOW_PLAN_TOOL_DESCRIPTION,
+                    schema: buildWorkflowPlanSchema()
+                }),
+                check: (draft) => checkWorkflowPlan(draft, {
+                    lookup: registryLookup(registry),
+                    checkCode: plannedCodeStepProblems
+                })
+            });
+            plan = refined.plan;
+            planProblems = refined.problems;
+            if (!plan) {
+                return { error: "The planner did not return a plan." };
+            }
+        }
+        // Nothing below places a node — criterion 3. The plan is text on the row.
+        const saved = await persistSetup(owned.row, { plan, stage: "review" });
+        if (isError(saved))
+            return saved;
+        const resolved = await reviewPlan(run, plan);
+        return {
+            workflow_id: id,
+            stage: "review",
+            plan,
+            review: reviewReport(resolved),
+            plan_problems: planProblems,
+            nodes_placed: 0
+        };
+    }
+};
+// ── update_workflow_plan_step ───────────────────────────────────────────────
+const updateWorkflowPlanStep = {
+    spec: updateWorkflowPlanStepSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwned(run, id);
+        if (isError(owned))
+            return owned;
+        const plan = requirePlan(owned.setup);
+        if (isError(plan))
+            return plan;
+        const op = isString(params["op"]) ? params["op"] : "update";
+        const stepId = isString(params["step_id"]) ? params["step_id"] : null;
+        const steps = [...plan.steps];
+        const at = stepId === null ? -1 : steps.findIndex((s) => s.id === stepId);
+        if (op !== "add" && at === -1) {
+            return {
+                error: `No plan step "${stepId ?? ""}". The step ids are: ${steps
+                    .map((step) => step.id)
+                    .join(", ")}.`
+            };
+        }
+        const fields = {};
+        if (isString(params["title"]))
+            fields.title = params["title"];
+        if (isString(params["summary"]))
+            fields.summary = params["summary"];
+        if (params["node_type"] !== undefined) {
+            fields.node_type = isString(params["node_type"])
+                ? params["node_type"]
+                : null;
+        }
+        if (isString(params["model_role"])) {
+            fields.model_role = params["model_role"];
+        }
+        if (op === "remove") {
+            steps.splice(at, 1);
+        }
+        else if (op === "move") {
+            if (!isNumber(params["index"])) {
+                return { error: "op 'move' needs an `index`." };
+            }
+            const [moved] = steps.splice(at, 1);
+            steps.splice(Math.max(0, Math.min(steps.length, params["index"])), 0, moved);
+        }
+        else if (op === "add") {
+            const added = {
+                id: stepId ?? `step-${steps.length + 1}`,
+                title: fields.title ?? "New step",
+                summary: fields.summary ?? "",
+                node_type: fields.node_type ?? null
+            };
+            if (fields.model_role !== undefined) {
+                added.model_role = fields.model_role;
+            }
+            steps.splice(isNumber(params["index"])
+                ? Math.max(0, Math.min(steps.length, params["index"]))
+                : steps.length, 0, added);
+        }
+        else {
+            steps[at] = { ...steps[at], ...fields };
+        }
+        const next = workflowSetupPlan.parse({ ...plan, steps });
+        const saved = await persistSetup(owned.row, { plan: next });
+        if (isError(saved))
+            return saved;
+        const resolved = await reviewPlan(run, next);
+        return { workflow_id: id, plan: next, review: reviewReport(resolved) };
+    }
+};
+// ── build_workflow_from_plan ────────────────────────────────────────────────
+const buildWorkflowFromPlan = {
+    spec: buildWorkflowFromPlanSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwned(run, id);
+        if (isError(owned))
+            return owned;
+        const plan = requirePlan(owned.setup);
+        if (isError(plan))
+            return plan;
+        const registry = run.nodeRegistry;
+        if (!registry) {
+            return {
+                built: false,
+                submitted: false,
+                verified_result: false,
+                error: "Cannot build: no node registry is available in this process, so no node type could be resolved."
+            };
+        }
+        // D23: an unknown type blocks the build, and names itself.
+        const resolved = await reviewPlan(run, plan);
+        const unknown = resolved.steps.filter((entry) => entry.unknownNodeType);
+        if (unknown.length > 0) {
+            return {
+                built: false,
+                submitted: false,
+                verified_result: false,
+                error: "Every step must name a node type the registry has before the graph is built. " +
+                    `Unresolved: ${unknown
+                        .map((entry) => `${entry.step.id} (${entry.step.node_type ?? "no type"})`)
+                        .join(", ")}. Fix them with update_workflow_plan_step.`,
+                review: reviewReport(resolved)
+            };
+        }
+        if (resolved.missingRoles.length > 0) {
+            return {
+                built: false,
+                submitted: false,
+                verified_result: false,
+                error: "Cannot build until every model role is available in this install. " +
+                    `Missing provider roles: ${resolved.missingRoles.join(", ")}. ` +
+                    "Configure a provider or choose a different model role.",
+                review: reviewReport(resolved)
+            };
+        }
+        const models = isObjectLike(params["models"])
+            ? params["models"]
+            : undefined;
+        const placement = planToPlacement(plan, registryLookup(registry), models === undefined ? {} : { models });
+        const graph = placementToGraph(placement);
+        const validation = await validateBuiltGraph(run, graph);
+        const save = params["save"] !== false;
+        let savedRow = null;
+        if (save) {
+            const written = await persistSetup(owned.row, { stage: "done" }, { graph: graph });
+            if (isError(written))
+                return written;
+            savedRow = written;
+        }
+        return {
+            workflow_id: id,
+            built: true,
+            submitted: savedRow !== null,
+            verified_result: false,
+            saved: savedRow !== null,
+            stage: save ? "done" : owned.setup?.stage ?? "setup",
+            graph,
+            /** Plan input name → the sample a test run should send. */
+            sample_inputs: Object.fromEntries(plan.inputs.map((input) => [
+                input.name,
+                input.sample ?? ""
+            ])),
+            /**
+             * What the builder could not wire. Empty is the only value that means the
+             * graph does what the plan described — a validated graph with issues here
+             * is exactly the R6 failure: it runs and produces nothing.
+             */
+            issues: placement.issues,
+            validation
+        };
+    }
+};
+/** Run the same static checks `validate_workflow` runs, on a built graph. */
+async function validateBuiltGraph(run, graph) {
+    return validateWorkflow.impl(run, { graph });
+}
+async function loadOwnedGame(run, id) {
+    const { Workflow } = await import("@nodetool-ai/models");
+    const row = (await Workflow.get(id));
+    if (!row || row.user_id !== userIdOf(run.context)) {
+        return { error: `Workflow ${id} was not found, or it is not yours.` };
+    }
+    return { row, game: readGameSetup(row.settings) };
+}
+/** Write a game patch back onto the row, leaving the rest of `settings` alone. */
+async function persistGame(row, patch, extra = {}) {
+    const { Workflow } = await import("@nodetool-ai/models");
+    const fields = {
+        settings: writeGameSetup(row.settings, patch)
+    };
+    if (extra.graph !== undefined) {
+        fields.graph = extra.graph;
+    }
+    if (extra.workspaceId !== undefined) {
+        fields.workspace_id = extra.workspaceId;
+    }
+    const updated = await Workflow.updateFieldsIfUnchanged(row.id, row.updated_at, fields);
+    if (!updated) {
+        return {
+            error: `Workflow ${row.id} changed since you read it — read it again and retry.`
+        };
+    }
+    return updated;
+}
+/** The template's manifest, or the reason there is none to work from. */
+async function requireGameTemplate(game) {
+    const id = game?.template?.trim() ?? "";
+    if (id === "") {
+        return {
+            error: "This workflow has no native game template yet. Pick topdown with set_game_setup."
+        };
+    }
+    const { getNativeTemplate, listNativeTemplates } = await import("@nodetool-ai/game-nodes");
+    try {
+        return getNativeTemplate(id);
+    }
+    catch {
+        return {
+            error: `Unknown template ${id}. Templates: ${listNativeTemplates()
+                .map((t) => t.id)
+                .join(", ")}.`
+        };
+    }
+}
+/** `provider:model_id` as the model value a node's model prop takes. */
+function modelValue(tileId, type) {
+    const at = tileId.indexOf(":");
+    if (at <= 0 || at === tileId.length - 1)
+        return null;
+    const provider = tileId.slice(0, at);
+    const id = tileId.slice(at + 1);
+    return { type, provider, id, name: id, path: null };
+}
+/** The style entity's name and descriptor, read off the library row. */
+async function loadStyle(run, entityId) {
+    if (!entityId)
+        return null;
+    const { Asset } = await import("@nodetool-ai/models");
+    const asset = await Asset.find(userIdOf(run.context), entityId);
+    const marker = readEntityMarker(asset?.metadata ?? null);
+    if (!marker || marker.kind !== "style")
+        return null;
+    const style = { name: marker.name, descriptor: marker.descriptor };
+    const referenceAssetId = marker.reference_asset_id ??
+        (asset?.content_type.startsWith("image/") ? asset.id : undefined);
+    if (referenceAssetId)
+        style.referenceAssetId = referenceAssetId;
+    return style;
+}
+/**
+ * What the Look step's `Continue` is blocked on (criterion 4): every cast
+ * entry named and described, every slot prompt written.
+ */
+function designGaps(design) {
+    const gaps = [];
+    for (const member of design.cast) {
+        if (member.name.trim() === "") {
+            gaps.push(`cast "${member.slot_id}" has no name`);
+        }
+        if (member.descriptor.trim() === "") {
+            gaps.push(`cast "${member.slot_id}" has no descriptor`);
+        }
+    }
+    for (const entry of design.slot_prompts) {
+        if (entry.prompt.trim() === "") {
+            gaps.push(`slot "${entry.slot_id}" has no prompt`);
+        }
+    }
+    return gaps;
+}
+// ── set_game_setup ──────────────────────────────────────────────────────────
+const SET_GAME_STRING_FIELDS = [
+    "brief",
+    "template",
+    "style_entity_id",
+    "image_model",
+    "sfx_node_type",
+    "music_model",
+    "project_name",
+    "game_id",
+    "stage"
+];
+const setGameSetup = {
+    spec: setGameSetupSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwnedGame(run, id);
+        if (isError(owned))
+            return owned;
+        const patch = {};
+        for (const field of SET_GAME_STRING_FIELDS) {
+            if (isString(params[field]))
+                patch[field] = params[field];
+        }
+        if (Object.keys(patch).length === 0) {
+            return {
+                error: "Nothing to set — pass brief, template, style_entity_id, image_model, sfx_node_type, music_model, project_name or stage."
+            };
+        }
+        const saved = await persistGame(owned.row, patch);
+        if (isError(saved))
+            return saved;
+        return { workflow_id: id, game: readGameSetup(saved.settings) };
+    }
+};
+// ── design_game ─────────────────────────────────────────────────────────────
+const designGame = {
+    spec: designGameSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwnedGame(run, id);
+        if (isError(owned))
+            return owned;
+        const template = await requireGameTemplate(owned.game);
+        if (isError(template))
+            return template;
+        const brief = owned.game?.brief?.trim() ?? "";
+        const supplied = params["design"];
+        const provider = isString(params["provider"]) ? params["provider"] : "";
+        const model = isString(params["model"]) ? params["model"] : "";
+        let raw;
+        if (supplied !== undefined) {
+            raw = supplied;
+        }
+        else if (provider.length > 0 && model.length > 0) {
+            if (brief.length === 0) {
+                return {
+                    error: "This workflow has no game brief, so there is nothing to design. Write one with set_game_setup first."
+                };
+            }
+            const { generateStructured } = await import("@nodetool-ai/runtime");
+            raw = await generateStructured(await run.context.getProvider(provider), {
+                model,
+                maxTokens: 4096,
+                messages: [
+                    { role: "system", content: GAME_DESIGNER_SYSTEM_PROMPT },
+                    {
+                        role: "user",
+                        content: [
+                            `Brief: ${brief}`,
+                            `Template: ${template.id}`,
+                            "",
+                            "Asset manifest:",
+                            JSON.stringify(template.manifest.slots, null, 2)
+                        ].join("\n")
+                    }
+                ],
+                toolName: GAME_DESIGN_TOOL_NAME,
+                toolDescription: GAME_DESIGN_TOOL_DESCRIPTION,
+                schema: buildGameDesignSchema(template.manifest)
+            });
+        }
+        else {
+            // No model: the shipped chip whose brief this is carries a pinned design,
+            // so a keyless install still reaches the review step.
+            const chip = GAME_INSPIRATION_CHIPS.find((entry) => entry.template === template.id &&
+                entry.brief.trim().toLowerCase() === brief.toLowerCase());
+            if (!chip) {
+                return {
+                    error: "Pass provider and model to design, or pass a `design` to store without calling one. " +
+                        `Without either, only a shipped inspiration chip's brief designs: ${GAME_INSPIRATION_CHIPS.map((entry) => `"${entry.brief}"`).join(", ")}.`
+                };
+            }
+            raw = chip.design;
+        }
+        const parsed = parseGameDesign(raw, template.manifest);
+        if (!parsed) {
+            return { error: "The designer did not return a design." };
+        }
+        // Nothing below places a node: the design is text on the row.
+        const saved = await persistGame(owned.row, {
+            design: parsed.design,
+            design_source: designSourceOf(template.id, brief),
+            stage: "review"
+        });
+        if (isError(saved))
+            return saved;
+        return {
+            workflow_id: id,
+            stage: "review",
+            design: parsed.design,
+            /** Slots the designer skipped, filled from the template's own prompt. */
+            filled_from_manifest: parsed.filled,
+            gaps: designGaps(parsed.design),
+            nodes_placed: 0
+        };
+    }
+};
+// ── update_game_design ──────────────────────────────────────────────────────
+/** Merge `patch` entries into `current` by `slot_id`, keeping order. */
+function mergeBySlot(current, patch) {
+    if (!Array.isArray(patch))
+        return [...current];
+    const merged = [...current];
+    for (const entry of patch) {
+        if (!isObjectLike(entry) || !isString(entry.slot_id))
+            continue;
+        const slotId = entry.slot_id;
+        const at = merged.findIndex((item) => item.slot_id === slotId);
+        if (at === -1) {
+            merged.push(entry);
+        }
+        else {
+            merged[at] = { ...merged[at], ...entry };
+        }
+    }
+    return merged;
+}
+const GAME_DESIGN_TEXT_FIELDS = [
+    "title",
+    "premise",
+    "core_loop",
+    "level",
+    "win",
+    "lose"
+];
+const updateGameDesign = {
+    spec: updateGameDesignSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwnedGame(run, id);
+        if (isError(owned))
+            return owned;
+        const current = owned.game?.design;
+        if (!current) {
+            return {
+                error: "This workflow has no game design yet. Run design_game first, or store one with design_game's `design` argument."
+            };
+        }
+        const next = { ...current };
+        for (const field of GAME_DESIGN_TEXT_FIELDS) {
+            if (isString(params[field]))
+                next[field] = params[field];
+        }
+        if (Array.isArray(params["player_verbs"])) {
+            next["player_verbs"] = params["player_verbs"].filter(isString);
+        }
+        next["cast"] = mergeBySlot(current.cast, params["cast"]);
+        next["enemies"] = mergeBySlot(current.enemies, params["enemies"]);
+        next["slot_prompts"] = mergeBySlot(current.slot_prompts, params["slot_prompts"]);
+        const parsed = gameDesign.safeParse(next);
+        if (!parsed.success) {
+            return { error: `The edited design is malformed: ${parsed.error.message}` };
+        }
+        const saved = await persistGame(owned.row, { design: parsed.data });
+        if (isError(saved))
+            return saved;
+        return {
+            workflow_id: id,
+            design: parsed.data,
+            gaps: designGaps(parsed.data)
+        };
+    }
+};
+// ── build_game ──────────────────────────────────────────────────────────────
+const buildGame = {
+    spec: buildGameSpec,
+    impl: async (run, params) => {
+        const id = String(params["workflow_id"]);
+        const owned = await loadOwnedGame(run, id);
+        if (isError(owned))
+            return owned;
+        const template = await requireGameTemplate(owned.game);
+        if (isError(template))
+            return template;
+        const design = owned.game?.design;
+        if (!design) {
+            return {
+                error: "This workflow has no game design yet. Run design_game first, then build_game."
+            };
+        }
+        const gaps = designGaps(design);
+        if (gaps.length > 0) {
+            return {
+                error: "Every cast member needs a name and a descriptor and every slot needs a prompt before the graph is built. " +
+                    `Unfinished: ${gaps.join("; ")}. Fix them with update_game_design.`,
+                gaps
+            };
+        }
+        const registry = run.nodeRegistry;
+        if (!registry) {
+            return {
+                error: "Cannot build: no node registry is available in this process, so no node type could be resolved."
+            };
+        }
+        const imageTile = owned.game?.image_model ?? "";
+        const imageModel = modelValue(imageTile, "image_model");
+        if (!imageModel) {
+            return {
+                error: "No image model is chosen. Set image_model to `provider:model_id` with set_game_setup — find_model has the ids."
+            };
+        }
+        // A setup saved in the browser keeps "the template's own audio" as the
+        // placeholder sentinel, not as an absent field, so both audio answers are
+        // normalized the way the flow normalizes them (D27). Handing the sentinel
+        // on would fail this as an invalid model id and reach the registry as a
+        // node type nothing answers for.
+        const musicTile = gameAudioChoice(owned.game?.music_model);
+        const musicModel = musicTile === null ? null : modelValue(musicTile, "music_model");
+        if (musicTile !== null && !musicModel) {
+            return {
+                error: `music_model "${musicTile}" is not \`provider:model_id\`. Omit it to keep the template's placeholder music.`
+            };
+        }
+        const projectName = owned.game?.project_name?.trim() ||
+            design.title.trim() ||
+            template.id;
+        const { Game } = await import("@nodetool-ai/models");
+        let nativeGame = owned.game?.game_id
+            ? await Game.findOwned(userIdOf(run.context), owned.game.game_id)
+            : null;
+        if (nativeGame && nativeGame.project_id !== owned.row.project_id) {
+            return { error: "The selected game belongs to another project" };
+        }
+        if (owned.game?.game_id && !nativeGame) {
+            return { error: "The selected native game was not found" };
+        }
+        if (!nativeGame && params["save"] === false) {
+            return { error: "Create or select a native game before previewing the asset graph" };
+        }
+        if (!nativeGame) {
+            const { createNativeGame } = await import("./game.js");
+            const created = await createNativeGame(userIdOf(run.context), owned.row.project_id, projectName);
+            if ("error" in created)
+                return created;
+            nativeGame = created.game;
+        }
+        const choices = {
+            imageModel,
+            sfxNodeType: gameAudioChoice(owned.game?.sfx_node_type),
+            musicModel,
+            style: await loadStyle(run, owned.game?.style_entity_id),
+            projectName,
+            gameId: nativeGame.id,
+            directory: nativeGame.source_root,
+            verify: true
+        };
+        const placement = gameGraphPlacement(template.manifest, design, choices, registryLookup(registry));
+        const graph = placementToGraph(placement);
+        const validation = await validateBuiltGraph(run, graph);
+        const save = params["save"] !== false;
+        let savedRow = null;
+        if (save) {
+            const written = await persistGame(owned.row, { stage: "done", project_name: projectName, game_id: nativeGame.id }, { graph: graph, workspaceId: nativeGame.workspace_id });
+            if (isError(written))
+                return written;
+            savedRow = written;
+        }
+        return {
+            workflow_id: id,
+            game_id: nativeGame.id,
+            saved: savedRow !== null,
+            stage: save ? "done" : owned.game?.stage ?? "look",
+            graph,
+            node_count: placement.nodes.length,
+            directory: choices.directory,
+            /**
+             * The slots the builder could not wire. Empty is the only value that
+             * means the graph fills every slot the template needs — a validated graph
+             * with issues here exports a project with holes in it.
+             */
+            issues: placement.issues,
+            validation
+        };
+    }
+};
+/** Every workflow capability, in the order `getAllMcpTools` offered them. */
+export const WORKFLOW_CAPABILITIES = [
+    listWorkflows,
+    getWorkflow,
+    createWorkflow,
+    updateWorkflow,
+    deleteWorkflow,
+    listWorkflowVersions,
+    getWorkflowVersion,
+    createWorkflowVersion,
+    restoreWorkflowVersion,
+    deleteWorkflowVersion,
+    setWorkflowAccess,
+    runWorkflowCapability,
+    debugWorkflow,
+    resolveWorkflowEscalation,
+    validateWorkflow,
+    getExampleWorkflow,
+    exportWorkflowDigraph,
+    startBackgroundJob,
+    setWorkflowSetup,
+    planWorkflow,
+    updateWorkflowPlanStep,
+    buildWorkflowFromPlan,
+    setGameSetup,
+    designGame,
+    updateGameDesign,
+    buildGame
+];
+export const module = {
+    module: "workflows",
+    exports: [...WORKFLOW_CAPABILITIES]
+};
+export { listWorkflows, getWorkflow, createWorkflow, updateWorkflow, deleteWorkflow, listWorkflowVersions, getWorkflowVersion, createWorkflowVersion, restoreWorkflowVersion, deleteWorkflowVersion, setWorkflowAccess, runWorkflowCapability, debugWorkflow, resolveWorkflowEscalation, validateWorkflow, getExampleWorkflow, exportWorkflowDigraph, startBackgroundJob, setWorkflowSetup, planWorkflow, updateWorkflowPlanStep, buildWorkflowFromPlan, setGameSetup, designGame, updateGameDesign, buildGame, registryLookup };
+//# sourceMappingURL=workflows.js.map