stageflow 0.3.0 → 0.8.0

package/dist/cli.js

@@ -4,27 +4,40 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { PiAgentAdapter } from "./agent/piAdapter.js";
+import { ARTIFACT_USAGE, runArtifactCommand } from "./cli/artifactCommand.js";
+import { ENVELOPE_USAGE, runEnvelopeCommand, } from "./cli/envelopeCommand.js";
+import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.js";
 import { INIT_USAGE, runInitCommand } from "./cli/initCommand.js";
 import { PROVIDERS_USAGE, runProvidersCommand } from "./cli/providersCommand.js";
 import { RUN_USAGE, runRunCommand } from "./cli/runCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
+import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
 import { VALIDATE_USAGE, runValidateCommand } from "./cli/validateCommand.js";
 import { createRunStore } from "./runstore/createStore.js";
 import { resolveStageflowContext } from "./project/resolveStageflowContext.js";
 import { exitForOutcome, runStageWorker } from "./runtime/stageWorker.js";
 import { SF_STAGE_WORKER } from "./runtime/stageWorkerProtocol.js";
 import { DEFAULT_PORT, startUiServer } from "./server/http.js";
+import { startMcpServer } from "./server/mcpHost.js";
+import { resolveMcpStateless } from "./mcp/server.js";
 const USAGE = `Usage:
   sf init
-  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]
+  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]
   sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]
-  sf ui [--port ${DEFAULT_PORT}]
+  sf artifact read --run <runId> --path <relPath> [--out <file>]
+  sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]
+  sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]
+  sf ui [--port ${DEFAULT_PORT}] [--mcp-stateless]
+  sf mcp [--port ${DEFAULT_PORT}] [--mcp-stateless]
   sf providers list
   sf providers status [--provider <id>]
   sf providers detect
   sf providers source [get | set <pi_home|sf_owned>]
   sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]
   sf providers logout <providerId>
+  sf skills list
+  sf skills install --from-path <dir> [--skill-name <name>]
+  sf skills install --from-zip <url-or-path> [--skill-name <name>] [--checksum sha256:<hex>]
   sf --help
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
@@ -37,7 +50,15 @@ ${RUN_USAGE}
 
 ${VALIDATE_USAGE}
 
-${PROVIDERS_USAGE}`;
+${ARTIFACT_USAGE}
+
+${ENVELOPE_USAGE}
+
+${EXPORT_RUN_USAGE}
+
+${PROVIDERS_USAGE}
+
+${SKILLS_USAGE}`;
 function parseArgs(argv) {
     const args = argv.slice(2);
     if (args.length === 0) {
@@ -51,7 +72,11 @@ function parseArgs(argv) {
     if (command === "providers" ||
         command === "validate" ||
         command === "run" ||
-        command === "init") {
+        command === "init" ||
+        command === "artifact" ||
+        command === "envelope" ||
+        command === "export-run" ||
+        command === "skills") {
         return { help: false, command };
     }
     if (args.includes("--help") || args.includes("-h")) {
@@ -61,6 +86,7 @@ function parseArgs(argv) {
     let pipeline;
     let port;
     let checkout;
+    let mcpStateless = false;
     for (let i = 1; i < args.length; i++) {
         if (args[i] === "--task") {
             task = args[++i];
@@ -82,8 +108,11 @@ function parseArgs(argv) {
                 throw new Error(`Invalid --port: ${raw}`);
             }
         }
+        else if (args[i] === "--mcp-stateless") {
+            mcpStateless = true;
+        }
     }
-    return { help: false, command, task, pipeline, port, checkout };
+    return { help: false, command, task, pipeline, port, checkout, mcpStateless };
 }
 export function parseRunStageArgs(argv) {
     let runId;
@@ -225,17 +254,45 @@ async function main(argv) {
                 isGitProject: ctx.isGitProject,
             });
         }
+        if (parsed.command === "artifact") {
+            return runArtifactCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
+        if (parsed.command === "envelope") {
+            return runEnvelopeCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
+        if (parsed.command === "export-run") {
+            return runExportRunCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
         if (parsed.command === "providers") {
             return runProvidersCommand(argv.slice(3), ctx.invocationCwd);
         }
+        if (parsed.command === "skills") {
+            return runSkillsCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
         const store = createRunStore({ rootDir: ctx.projectRoot });
         if (parsed.command === "ui") {
+            const mcpStateless = resolveMcpStateless({
+                mcpStateless: parsed.mcpStateless,
+            });
             const { url, mcpUrl } = await startUiServer({
                 agent: new PiAgentAdapter(),
                 store,
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
                 port: parsed.port,
+                mcpStateless,
             });
             console.log(`Operator console: ${url}`);
             console.log(`MCP endpoint: ${mcpUrl}`);
@@ -243,6 +300,22 @@ async function main(argv) {
             await new Promise(() => undefined);
             return 0;
         }
+        if (parsed.command === "mcp") {
+            const mcpStateless = resolveMcpStateless({
+                mcpStateless: parsed.mcpStateless,
+            });
+            const { mcpUrl } = await startMcpServer({
+                agent: new PiAgentAdapter(),
+                store,
+                cwd: ctx.invocationCwd,
+                rootDir: ctx.projectRoot,
+                port: parsed.port,
+                mcpStateless,
+            });
+            console.log(`MCP endpoint: ${mcpUrl}`);
+            await new Promise(() => undefined);
+            return 0;
+        }
         if (parsed.command === "internal") {
             const subArgs = argv.slice(3);
             const subcommand = subArgs[0];

package/dist/config/loadPipeline.js

@@ -96,7 +96,11 @@ async function loadPipelineFromPath(pipelinePath) {
                 },
             ]);
         }
-        stages.push(stageOutcome.value);
+        const stage = {
+            ...stageOutcome.value,
+            ...(entry.skill !== undefined ? { skill: entry.skill } : {}),
+        };
+        stages.push(stage);
         stageSources[stageId] = { kind: "file", path: entry.body.absolutePath };
     }
     const pipeline = {

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

@@ -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

@@ -9,3 +9,5 @@ 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;