stageflow 0.3.0 → 0.9.0

package/dist/config/normalizePipelineStageEntry.d.ts

@@ -13,4 +13,6 @@ export declare function toWiringRefs(entries: NormalizedPipelineStageEntry[]): A
         select: "one" | "subset";
         allow_none?: boolean;
     };
+    clonable?: boolean;
+    clone_cap?: number;
 }>;

package/dist/config/normalizePipelineStageEntry.js

@@ -28,7 +28,21 @@ function extractBodyRaw(raw) {
     return body;
 }
 function hasBodyKey(raw) {
-    return Object.keys(raw).some((key) => BODY_KEYS.has(key));
+    return Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill");
+}
+function readSkill(raw) {
+    if (raw.skill === undefined)
+        return undefined;
+    if (typeof raw.skill !== "string" || raw.skill.trim() === "") {
+        return loadFailure([
+            {
+                code: "stage.invalid_skill",
+                message: "skill must be a non-empty string",
+                category: "stage",
+            },
+        ]);
+    }
+    return loadSuccess(raw.skill.trim());
 }
 function stringStageRefMessage(index, declaringPath, entry) {
     const hint = entry
@@ -74,6 +88,11 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
         }
         const uses = typeof raw.uses === "string" ? raw.uses : undefined;
         const hasBody = hasBodyKey(raw);
+        const skillOutcome = readSkill(raw);
+        if (skillOutcome !== undefined && !skillOutcome.ok) {
+            return skillOutcome;
+        }
+        const skill = skillOutcome?.ok ? skillOutcome.value : undefined;
         if (uses && hasBody) {
             return loadFailure([
                 {
@@ -161,6 +180,9 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             body,
             ...(typeof raw.needs === "string" ? { needs: raw.needs } : {}),
             ...(forkValue !== undefined ? { fork: forkValue } : {}),
+            ...(raw.clonable !== undefined ? { clonable: raw.clonable } : {}),
+            ...(raw.clone_cap !== undefined ? { clone_cap: raw.clone_cap } : {}),
+            ...(skill !== undefined ? { skill } : {}),
         };
         const priorPath = normalized.find((e) => e.id === id)?.declaringPath;
         if (priorPath) {
@@ -182,5 +204,7 @@ export function toWiringRefs(entries) {
         id: entry.id,
         ...(entry.needs !== undefined ? { needs: entry.needs } : {}),
         ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
+        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
+        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
     }));
 }

package/dist/config/pipelineStageKeys.js

@@ -1,4 +1,4 @@
-export const WIRING_KEYS = new Set(["id", "needs", "fork", "uses"]);
+export const WIRING_KEYS = new Set(["id", "needs", "fork", "uses", "clonable", "clone_cap"]);
 export const BODY_KEYS = new Set([
     "system_prompt",
     "model",

package/dist/config/resolveForkEmitContext.d.ts

@@ -1,3 +1,4 @@
-import type { ForkEmitContext } from "../types/forkChoice.js";
+import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
+export declare function resolveCloneEmitContext(dag: ResolvedPipelineDag, stageId: string): CloneEmitContext | undefined;
 export declare function resolveForkEmitContext(dag: ResolvedPipelineDag, stageId: string): ForkEmitContext | undefined;

package/dist/config/resolveForkEmitContext.js

@@ -1,9 +1,31 @@
+export function resolveCloneEmitContext(dag, stageId) {
+    const childIds = dag.childrenOf[stageId] ?? [];
+    const clonableSuccessors = [];
+    for (const childId of childIds) {
+        const node = dag.nodes.find((n) => n.id === childId);
+        if (node?.clonable === true) {
+            clonableSuccessors.push({
+                successorId: childId,
+                cloneCap: node.clone_cap,
+            });
+        }
+    }
+    if (clonableSuccessors.length === 0)
+        return undefined;
+    return { clonableSuccessors };
+}
 export function resolveForkEmitContext(dag, stageId) {
     const dagNode = dag.nodes.find((n) => n.id === stageId);
     if (!dagNode?.fork)
         return undefined;
+    const immediateSuccessorIds = (dag.childrenOf[stageId] ?? []).filter((childId) => {
+        const child = dag.nodes.find((n) => n.id === childId);
+        return child?.clonable !== true;
+    });
+    if (immediateSuccessorIds.length === 0)
+        return undefined;
     return {
-        immediateSuccessorIds: dag.childrenOf[stageId] ?? [],
+        immediateSuccessorIds,
         forkShape: {
             cardinality: dagNode.fork.select,
             allowNone: dagNode.fork.allow_none,

package/dist/config/resolvePipelineDag.js

@@ -49,8 +49,16 @@ export function parsePipelineStageEntries(raw, ctx) {
             }
             forkValue = entry.fork;
         }
+        const clonableFields = {
+            ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
+            ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
+        };
         if (entry.needs === undefined) {
-            entries.push(forkValue !== undefined ? { id: entry.id, fork: forkValue } : { id: entry.id });
+            entries.push({
+                id: entry.id,
+                ...(forkValue !== undefined ? { fork: forkValue } : {}),
+                ...clonableFields,
+            });
             continue;
         }
         if (Array.isArray(entry.needs)) {
@@ -62,9 +70,12 @@ export function parsePipelineStageEntries(raw, ctx) {
         if (typeof entry.needs !== "string" || !entry.needs) {
             throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a non-empty string`));
         }
-        entries.push(forkValue !== undefined
-            ? { id: entry.id, needs: entry.needs, fork: forkValue }
-            : { id: entry.id, needs: entry.needs });
+        entries.push({
+            id: entry.id,
+            needs: entry.needs,
+            ...(forkValue !== undefined ? { fork: forkValue } : {}),
+            ...clonableFields,
+        });
     }
     return entries;
 }
@@ -74,6 +85,8 @@ function normalizeToEdges(entries) {
         needs: entry.needs ?? null,
         stageIndex: index,
         ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
+        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
+        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
     }));
 }
 function detectDuplicateIds(edges, ctx) {
@@ -213,6 +226,9 @@ function buildResolvedPipelineDag(edges) {
         ...(edge.fork !== undefined
             ? { fork: { select: edge.fork.select, allow_none: edge.fork.allow_none ?? false } }
             : {}),
+        ...(edge.clonable === true
+            ? { clonable: true, clone_cap: edge.clone_cap ?? 5 }
+            : {}),
     }));
     return { nodes, roots, childrenOf };
 }
@@ -228,6 +244,21 @@ function validateForkFields(edges, dag, ctx) {
         }
     }
 }
+function validateClonableFields(edges, dag, ctx) {
+    for (const edge of edges) {
+        if (edge.clone_cap !== undefined && edge.clonable !== true) {
+            throw new Error(formatError(ctx, `stage "${edge.id}": clone_cap requires clonable: true`));
+        }
+        if (edge.clonable === true && edge.clone_cap !== undefined) {
+            if (!Number.isInteger(edge.clone_cap) || edge.clone_cap < 2) {
+                throw new Error(formatError(ctx, `stage "${edge.id}": clone_cap must be an integer greater than or equal to 2`));
+            }
+        }
+        if (edge.clonable === true && (dag.childrenOf[edge.id] ?? []).length === 0) {
+            throw new Error(formatError(ctx, `clonable on stage "${edge.id}": no children in the DAG`));
+        }
+    }
+}
 export function resolvePipelineDagFromRefs(refs, ctx) {
     const edges = normalizeToEdges(refs);
     detectDuplicateIds(edges, ctx);
@@ -239,6 +270,7 @@ export function resolvePipelineDagFromRefs(refs, ctx) {
         .map((edge) => edge.id);
     const dag = buildResolvedPipelineDag(edges);
     validateForkFields(edges, dag, ctx);
+    validateClonableFields(edges, dag, ctx);
     return { stages, dag };
 }
 export function resolvePipelineDag(rawStages, ctx) {

package/dist/envelope/check.d.ts

@@ -1,3 +1,5 @@
 import { type StageEnvelope } from "../types/envelope.js";
+import type { CloneForkItem } from "../types/forkChoice.js";
+export declare function parseCloneForks(raw: unknown): CloneForkItem[];
 export declare function assertRequiredEnvelope(value: unknown): StageEnvelope;
 export declare function isAdvancingEnvelope(envelope: StageEnvelope): boolean;

package/dist/envelope/check.js

@@ -1,4 +1,52 @@
 import { EnvelopeError, } from "../types/envelope.js";
+function parseCloneForkItem(raw, index) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new EnvelopeError(`clone_forks[${index}] must be an object`);
+    }
+    const record = raw;
+    if (typeof record.successor_id !== "string") {
+        throw new EnvelopeError(`clone_forks[${index}].successor_id must be a string`);
+    }
+    const action = record.action;
+    if (action !== "skip" && action !== "once" && action !== "fanout") {
+        throw new EnvelopeError(`clone_forks[${index}].action must be "skip", "once", or "fanout"`);
+    }
+    const item = {
+        successor_id: record.successor_id,
+        action,
+    };
+    if (record.envelope !== undefined) {
+        item.envelope = assertRequiredEnvelope(record.envelope);
+    }
+    if (record.mode !== undefined) {
+        if (record.mode !== "parallel" && record.mode !== "sequential") {
+            throw new EnvelopeError(`clone_forks[${index}].mode must be "parallel" or "sequential"`);
+        }
+        item.mode = record.mode;
+    }
+    if (record.clones !== undefined) {
+        if (!Array.isArray(record.clones)) {
+            throw new EnvelopeError(`clone_forks[${index}].clones must be an array`);
+        }
+        item.clones = record.clones.map((clone, cloneIndex) => {
+            if (clone === null || typeof clone !== "object" || Array.isArray(clone)) {
+                throw new EnvelopeError(`clone_forks[${index}].clones[${cloneIndex}] must be an object`);
+            }
+            const cloneRecord = clone;
+            if (cloneRecord.envelope === undefined) {
+                throw new EnvelopeError(`clone_forks[${index}].clones[${cloneIndex}].envelope is required`);
+            }
+            return { envelope: assertRequiredEnvelope(cloneRecord.envelope) };
+        });
+    }
+    return item;
+}
+export function parseCloneForks(raw) {
+    if (!Array.isArray(raw)) {
+        throw new EnvelopeError("clone_forks must be an array");
+    }
+    return raw.map((item, index) => parseCloneForkItem(item, index));
+}
 export function assertRequiredEnvelope(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new EnvelopeError("envelope must be an object");
@@ -32,6 +80,9 @@ export function assertRequiredEnvelope(value) {
         }
         envelope.fork_choice = record.fork_choice;
     }
+    if (record.clone_forks !== undefined) {
+        envelope.clone_forks = parseCloneForks(record.clone_forks);
+    }
     if (record.payload !== undefined) {
         if (record.payload === null ||
             typeof record.payload !== "object" ||

package/dist/envelope/cloneForks.d.ts

@@ -0,0 +1,2 @@
+import type { CloneEmitContext } from "../types/forkChoice.js";
+export declare function assertCloneForks(params: unknown, cloneEmitContext: CloneEmitContext): void;

package/dist/envelope/cloneForks.js

@@ -0,0 +1,62 @@
+import { parseCloneForks } from "./check.js";
+import { EnvelopeError } from "../types/envelope.js";
+function fieldPresent(item, key) {
+    return item[key] !== undefined;
+}
+export function assertCloneForks(params, cloneEmitContext) {
+    const record = params;
+    if (record.status === "failure")
+        return;
+    if (record.clone_forks === undefined || !Array.isArray(record.clone_forks)) {
+        throw new EnvelopeError("clonable successor requires clone_forks on success");
+    }
+    const items = parseCloneForks(record.clone_forks);
+    if (items.length === 0 && cloneEmitContext.clonableSuccessors.length > 0) {
+        throw new EnvelopeError("clone_forks must not be empty when clonable successors exist");
+    }
+    const expectedIds = cloneEmitContext.clonableSuccessors.map((s) => s.successorId);
+    const expectedSet = new Set(expectedIds);
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item.successor_id)) {
+            throw new EnvelopeError(`clone_forks contains duplicate successor_id: ${item.successor_id}`);
+        }
+        if (!expectedSet.has(item.successor_id)) {
+            throw new EnvelopeError(`clone_forks contains extra successor_id: ${item.successor_id}`);
+        }
+        seen.add(item.successor_id);
+        const capEntry = cloneEmitContext.clonableSuccessors.find((s) => s.successorId === item.successor_id);
+        const cloneCap = capEntry?.cloneCap;
+        if (item.action === "skip") {
+            if (fieldPresent(item, "envelope") ||
+                fieldPresent(item, "mode") ||
+                fieldPresent(item, "clones")) {
+                throw new EnvelopeError(`clone_forks skip for ${item.successor_id} must not include envelope, mode, or clones`);
+            }
+        }
+        else if (item.action === "once") {
+            if (!fieldPresent(item, "envelope")) {
+                throw new EnvelopeError(`clone_forks once for ${item.successor_id} requires envelope`);
+            }
+            if (fieldPresent(item, "mode") || fieldPresent(item, "clones")) {
+                throw new EnvelopeError(`clone_forks once for ${item.successor_id} must not include mode or clones`);
+            }
+        }
+        else if (item.action === "fanout") {
+            if (fieldPresent(item, "envelope")) {
+                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} must not include a top-level envelope`);
+            }
+            if (!fieldPresent(item, "mode") || !fieldPresent(item, "clones") || item.clones === undefined) {
+                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} requires mode and clones`);
+            }
+            if (cloneCap === undefined || item.clones.length < 2 || item.clones.length > cloneCap) {
+                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} must have between 2 and ${cloneCap} clones`);
+            }
+        }
+    }
+    for (const id of expectedIds) {
+        if (!seen.has(id)) {
+            throw new EnvelopeError(`clone_forks missing successor_id: ${id}`);
+        }
+    }
+}

package/dist/envelope/forkChoice.js

@@ -7,7 +7,7 @@ function assertForkChoiceLegality(choices, forkEmitContext) {
     const { immediateSuccessorIds, forkShape } = forkEmitContext;
     for (const id of choices) {
         if (!immediateSuccessorIds.includes(id)) {
-            throw new EnvelopeError(`fork_choice contains non-immediate successor: ${id}`);
+            throw new EnvelopeError(`fork_choice contains non-immediate successor: ${id}; clonable successors belong in clone_forks`);
         }
     }
     if (choices.length === 0) {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/f
 export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
 export { resolveProjectContext, legacyProjectContext, type ProjectContext, } from "./project/resolveProjectContext.js";
 export { resolveStageflowContext, projectContextFromStageflow, type StageflowContext, type CatalogManifestStatus, } from "./project/resolveStageflowContext.js";
-export { PACKAGE_NAME } from "./package-meta.js";
+export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export type { AgentPort } from "./agent/port.js";
@@ -15,3 +15,5 @@ export type { RunStore, RunSummary, RunDetail, RunMeta, RunStatus, StageSnapshot
 export { deriveStatusFromStages } from "./runstore/port.js";
 export { RunManager } from "./runtime/runManager.js";
 export { startUiServer } from "./server/http.js";
+export { startMcpServer } from "./server/mcpHost.js";
+export { DEFAULT_PORT } from "./server/mcpHost.js";

package/dist/index.js

@@ -2,10 +2,12 @@ export { findProjectRoot, clearFindProjectRootCacheForTests, } from "./project/f
 export { globalStageflowHome, ensureGlobalHome, } from "./project/globalHome.js";
 export { resolveProjectContext, legacyProjectContext, } from "./project/resolveProjectContext.js";
 export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
-export { PACKAGE_NAME } from "./package-meta.js";
+export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
 export { createRunStore } from "./runstore/createStore.js";
 export { deriveStatusFromStages } from "./runstore/port.js";
 export { RunManager } from "./runtime/runManager.js";
 export { startUiServer } from "./server/http.js";
+export { startMcpServer } from "./server/mcpHost.js";
+export { DEFAULT_PORT } from "./server/mcpHost.js";

package/dist/mcp/catalogTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare function registerCatalogTools(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/catalogTools.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { browseCatalog } from "../config/browseCatalog.js";
+import { loadPipeline } from "../config/loadPipeline.js";
+import { validateCatalog } from "../config/validateCatalog.js";
+import { projectRunForMcp } from "./projectRun.js";
+import { readRunArtifact } from "./readArtifact.js";
+import { textResult } from "./toolResults.js";
+const taskFileSchema = z.object({
+    id: z.string(),
+    goal: z.string(),
+    context: z.string().optional(),
+    constraints: z.string().optional(),
+    checkout: z.string().optional(),
+});
+const startRunSchema = z
+    .object({
+    pipeline: z.string().describe("Filesystem path to a pipeline YAML file"),
+    task_path: z.string().optional(),
+    task: taskFileSchema.optional(),
+})
+    .refine((data) => Boolean(data.task_path) !== Boolean(data.task), {
+    message: "Exactly one of task_path or task is required",
+});
+const runStatusSchema = z.enum(["created", "running", "succeeded", "failed"]);
+export function registerCatalogTools(server, deps) {
+    const { manager, store, cwd } = deps;
+    server.registerTool("list_pipelines", {
+        description: "List manifest-declared pipeline paths from the project catalog",
+        inputSchema: z.object({}),
+    }, async () => {
+        const catalog = await browseCatalog(cwd);
+        return textResult({ pipelines: catalog.pipelines });
+    });
+    server.registerTool("list_tasks", {
+        description: "List manifest-declared task paths from the project catalog",
+        inputSchema: z.object({}),
+    }, async () => {
+        const catalog = await browseCatalog(cwd);
+        return textResult({ tasks: catalog.tasks });
+    });
+    server.registerTool("list_runs", {
+        description: "List known pipeline runs. Optional filters: status, since (ISO created_at lower bound), pipeline (id or path).",
+        inputSchema: z.object({
+            status: runStatusSchema.optional(),
+            since: z.string().optional(),
+            pipeline: z.string().optional(),
+        }),
+    }, async ({ status, since, pipeline }) => {
+        const filter = {};
+        if (status !== undefined)
+            filter.status = status;
+        if (since !== undefined) {
+            if (!Number.isFinite(Date.parse(since))) {
+                return textResult({ error: "since must be a valid date", status: 400 }, true);
+            }
+            filter.since = since;
+        }
+        if (pipeline !== undefined)
+            filter.pipeline = pipeline;
+        const runs = await store.listRuns(Object.keys(filter).length > 0 ? filter : undefined);
+        return textResult({ runs });
+    });
+    server.registerTool("get_health", {
+        description: "Server health and soft-max run capacity: activeRunIds, activeCount, maxConcurrent, slotsAvailable. Start until slotsAvailable is 0; then wait for a run to finish or raise STAGEFLOW_MAX_CONCURRENT_RUNS.",
+        inputSchema: z.object({}),
+    }, async () => textResult(manager.getHealth()));
+    server.registerTool("start_run", {
+        description: "Start a pipeline run using a filesystem pipeline path and either task_path (catalog task file) or an inline task object. Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
+        inputSchema: startRunSchema,
+    }, async ({ pipeline, task_path, task }) => {
+        if (!pipeline.trim()) {
+            return textResult({ error: "pipeline is required" }, true);
+        }
+        const taskInput = task_path ?? task;
+        if (taskInput === undefined) {
+            return textResult({ error: "Exactly one of task_path or task is required" }, true);
+        }
+        const result = await manager.startRun({ pipeline, task: taskInput });
+        if (!result.ok) {
+            const { ok: _ok, reason, ...rest } = result;
+            return textResult({ error: reason, ...rest }, true);
+        }
+        return textResult({ runId: result.runId });
+    });
+    server.registerTool("get_run", {
+        description: "Poll a run: status, stage statuses, waiting_* / pending_prompt HITL fields, and envelope summary/payload/artifact paths (no events). Use list_stage_events / get_envelope for timelines and full envelopes.",
+        inputSchema: z.object({
+            runId: z.string(),
+        }),
+    }, async ({ runId }) => {
+        try {
+            const detail = await store.readRun(runId);
+            return textResult(projectRunForMcp(detail));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = /not found|no such|unknown run/i.test(message);
+            return textResult({
+                error: message,
+                status: notFound ? 404 : 500,
+            }, true);
+        }
+    });
+    server.registerTool("read_artifact", {
+        description: "Read a text artifact from a run workspace by relative path (contained under the run workspace).",
+        inputSchema: z.object({
+            runId: z.string(),
+            path: z.string(),
+        }),
+    }, async ({ runId, path: artifactPath }) => {
+        try {
+            const content = await readRunArtifact(store, runId, artifactPath);
+            return textResult({ runId, path: artifactPath, content });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = message.startsWith("Run not found") ||
+                message.startsWith("Artifact not found") ||
+                /no such|not found/i.test(message);
+            return textResult({
+                error: message,
+                status: notFound ? 404 : 400,
+            }, true);
+        }
+    });
+    server.registerTool("validate", {
+        description: "Validate the project catalog (full), a pipeline path, or a task path. Returns ValidationResult JSON (ok, summary, findings).",
+        inputSchema: z.object({
+            pipeline: z.string().optional(),
+            task: z.string().optional(),
+            strict: z.boolean().optional(),
+        }),
+    }, async ({ pipeline, task, strict }) => {
+        try {
+            let scope = "full";
+            if (pipeline !== undefined && pipeline.trim())
+                scope = "pipeline";
+            else if (task !== undefined && task.trim())
+                scope = "task";
+            const result = await validateCatalog({
+                cwd,
+                scope,
+                ...(scope === "pipeline" ? { pipeline: pipeline.trim() } : {}),
+                ...(scope === "task" ? { task: task.trim() } : {}),
+                strict: strict ?? false,
+            });
+            return textResult(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return textResult({ error: message, status: 400 }, true);
+        }
+    });
+    server.registerTool("describe_pipeline", {
+        description: "Describe a pipeline DAG: stages with needs, fork, clonable, clone_cap, and gate_kinds. Input is a filesystem pipeline path (same as start_run).",
+        inputSchema: z.object({
+            pipeline: z.string(),
+        }),
+    }, async ({ pipeline }) => {
+        if (!pipeline.trim()) {
+            return textResult({ error: "pipeline is required", status: 400 }, true);
+        }
+        try {
+            const loaded = await loadPipeline(pipeline.trim(), { cwd });
+            const gateById = new Map(loaded.stages.map((s) => [s.id, s.gate_kinds]));
+            const stages = loaded.dag.nodes.map((node) => ({
+                id: node.id,
+                needs: node.needs,
+                ...(node.fork !== undefined ? { fork: node.fork } : {}),
+                ...(node.clonable !== undefined ? { clonable: node.clonable } : {}),
+                ...(node.clone_cap !== undefined ? { clone_cap: node.clone_cap } : {}),
+                ...(gateById.get(node.id) !== undefined
+                    ? { gate_kinds: gateById.get(node.id) }
+                    : {}),
+            }));
+            return textResult({
+                id: loaded.pipeline.id,
+                path: loaded.pipelinePath,
+                stages,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return textResult({ error: message, status: 404 }, true);
+        }
+    });
+}

package/dist/mcp/controlTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare function registerControlTools(server: McpServer, deps: McpToolDeps): void;