stageflow 0.3.0 → 0.9.0

package/dist/cli/skillsCommand.js

@@ -0,0 +1,459 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { access, cp, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { inflateRawSync } from "node:zlib";
+import path from "node:path";
+import { findProjectRoot } from "../project/findProjectRoot.js";
+export const SKILLS_USAGE = `Usage:
+  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>]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+    fetch: globalThis.fetch.bind(globalThis),
+    runDoctor: (scriptPath, cwd) => {
+        const result = spawnSync(process.execPath, [scriptPath, "doctor"], {
+            cwd,
+            stdio: "pipe",
+        });
+        return result.status ?? 1;
+    },
+};
+function parseSkillsArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    const subcommand = args[0];
+    if (subcommand !== "list" && subcommand !== "install") {
+        throw new Error(`Unknown skills subcommand: ${subcommand}`);
+    }
+    let fromPath;
+    let fromZip;
+    let skillName;
+    let checksum;
+    let help = false;
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--from-path") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --from-path");
+            }
+            fromPath = value;
+        }
+        else if (arg === "--from-zip") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --from-zip");
+            }
+            fromZip = value;
+        }
+        else if (arg === "--skill-name") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --skill-name");
+            }
+            skillName = value;
+        }
+        else if (arg === "--checksum") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --checksum");
+            }
+            checksum = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return {
+        help,
+        subcommand,
+        fromPath,
+        fromZip,
+        skillName,
+        checksum,
+    };
+}
+function skillsDirForRoot(projectRoot) {
+    return path.join(projectRoot, ".pi", "skills");
+}
+function shouldCopyRelative(rel) {
+    const normalized = rel.split(path.sep).join("/");
+    if (normalized === "" || normalized === ".") {
+        return true;
+    }
+    const segments = normalized.split("/");
+    if (segments.some((segment) => segment === "test" || segment === "node_modules")) {
+        return false;
+    }
+    if (segments[0] === "scripts") {
+        const base = segments[segments.length - 1] ?? "";
+        if (base.startsWith("generate-")) {
+            return false;
+        }
+    }
+    return true;
+}
+async function copySkillTree(sourceRoot, destRoot) {
+    await rm(destRoot, { recursive: true, force: true });
+    await mkdir(destRoot, { recursive: true });
+    await cp(sourceRoot, destRoot, {
+        recursive: true,
+        filter: (src) => {
+            const rel = path.relative(sourceRoot, src);
+            return shouldCopyRelative(rel);
+        },
+    });
+}
+function inferSkillNameFromPath(sourcePath) {
+    return path.basename(path.resolve(sourcePath));
+}
+function inferSkillNameFromZipRef(zipRef) {
+    const base = path.basename(zipRef.split("?")[0] ?? zipRef);
+    return base.replace(/\.zip$/i, "");
+}
+function parseChecksum(value) {
+    const match = /^sha256:([a-f0-9]{64})$/i.exec(value);
+    if (!match) {
+        throw new Error("--checksum must be sha256:<64 hex chars>");
+    }
+    return match[1].toLowerCase();
+}
+function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function isZipSlipEntry(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (path.posix.isAbsolute(normalized)) {
+        return true;
+    }
+    return normalized.split("/").some((segment) => segment === "..");
+}
+function findEndOfCentralDirectory(data) {
+    for (let i = data.length - 22; i >= 0; i--) {
+        if (data.readUInt32LE(i) === 0x06054b50) {
+            return i;
+        }
+    }
+    throw new Error("invalid zip archive: end of central directory not found");
+}
+function readZipEntries(data) {
+    const eocdOffset = findEndOfCentralDirectory(data);
+    const centralDirOffset = data.readUInt32LE(eocdOffset + 16);
+    const totalEntries = data.readUInt16LE(eocdOffset + 10);
+    const entries = [];
+    let offset = centralDirOffset;
+    for (let i = 0; i < totalEntries; i++) {
+        if (data.readUInt32LE(offset) !== 0x02014b50) {
+            throw new Error("invalid zip archive: central directory entry missing");
+        }
+        const compressionMethod = data.readUInt16LE(offset + 10);
+        const compressedSize = data.readUInt32LE(offset + 20);
+        const uncompressedSize = data.readUInt32LE(offset + 24);
+        const nameLength = data.readUInt16LE(offset + 28);
+        const extraLength = data.readUInt16LE(offset + 30);
+        const commentLength = data.readUInt16LE(offset + 32);
+        const localHeaderOffset = data.readUInt32LE(offset + 42);
+        const name = data.toString("utf8", offset + 46, offset + 46 + nameLength);
+        entries.push({
+            name,
+            compressionMethod,
+            compressedSize,
+            uncompressedSize,
+            localHeaderOffset,
+        });
+        offset += 46 + nameLength + extraLength + commentLength;
+    }
+    return entries;
+}
+async function extractZipBuffer(data, destDir) {
+    await mkdir(destDir, { recursive: true });
+    const entries = readZipEntries(data);
+    for (const entry of entries) {
+        if (entry.name.endsWith("/")) {
+            continue;
+        }
+        if (isZipSlipEntry(entry.name)) {
+            throw new Error("zip entry path rejected (zip-slip)");
+        }
+        const localOffset = entry.localHeaderOffset;
+        if (data.readUInt32LE(localOffset) !== 0x04034b50) {
+            throw new Error("invalid zip archive: local file header missing");
+        }
+        const nameLength = data.readUInt16LE(localOffset + 26);
+        const extraLength = data.readUInt16LE(localOffset + 28);
+        const dataOffset = localOffset + 30 + nameLength + extraLength;
+        const compressed = data.subarray(dataOffset, dataOffset + entry.compressedSize);
+        let content;
+        if (entry.compressionMethod === 0) {
+            content = compressed;
+        }
+        else if (entry.compressionMethod === 8) {
+            content = inflateRawSync(compressed);
+        }
+        else {
+            throw new Error(`unsupported zip compression method: ${entry.compressionMethod}`);
+        }
+        if (content.length !== entry.uncompressedSize) {
+            throw new Error("invalid zip archive: uncompressed size mismatch");
+        }
+        const outPath = path.join(destDir, entry.name);
+        await mkdir(path.dirname(outPath), { recursive: true });
+        await writeFile(outPath, content);
+    }
+}
+async function resolveZipBytes(zipRef, io) {
+    if (zipRef.startsWith("https://")) {
+        const response = await io.fetch(zipRef);
+        if (!response.ok) {
+            throw new Error(`failed to fetch zip: HTTP ${response.status}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    if (/^https?:\/\//i.test(zipRef)) {
+        throw new Error("only HTTPS URLs are supported for --from-zip");
+    }
+    return readFile(path.resolve(zipRef));
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findSkillRoot(extractRoot, skillName) {
+    const directBin = path.join(extractRoot, "bin", `${skillName}.mjs`);
+    if (await pathExists(directBin)) {
+        return extractRoot;
+    }
+    const nestedRoot = path.join(extractRoot, skillName);
+    const nestedBin = path.join(nestedRoot, "bin", `${skillName}.mjs`);
+    if (await pathExists(nestedBin)) {
+        return nestedRoot;
+    }
+    const found = await findSkillRootByBin(extractRoot, skillName);
+    if (found !== undefined) {
+        return found;
+    }
+    const bySkillMd = await findSkillRootBySkillMd(extractRoot);
+    if (bySkillMd !== undefined) {
+        return bySkillMd;
+    }
+    throw new Error(`could not locate skill root in extracted archive`);
+}
+async function findSkillRootByBin(dir, skillName) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const fullPath = path.join(dir, entry.name);
+        const binScript = path.join(fullPath, "bin", `${skillName}.mjs`);
+        if (await pathExists(binScript)) {
+            return fullPath;
+        }
+        const nested = await findSkillRootByBin(fullPath, skillName);
+        if (nested !== undefined) {
+            return nested;
+        }
+    }
+    return undefined;
+}
+async function findSkillRootBySkillMd(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isFile() && entry.name === "SKILL.md") {
+            return dir;
+        }
+        if (entry.isDirectory()) {
+            const nested = await findSkillRootBySkillMd(fullPath);
+            if (nested !== undefined) {
+                return nested;
+            }
+        }
+    }
+    return undefined;
+}
+async function resolveInstallSource(parsed, io) {
+    const hasPath = parsed.fromPath !== undefined;
+    const hasZip = parsed.fromZip !== undefined;
+    if (hasPath === hasZip) {
+        throw new Error("specify exactly one of --from-path or --from-zip");
+    }
+    if (parsed.fromPath !== undefined) {
+        const sourceRoot = path.resolve(parsed.fromPath);
+        try {
+            const sourceStat = await stat(sourceRoot);
+            if (!sourceStat.isDirectory()) {
+                throw new Error("source path not found");
+            }
+        }
+        catch {
+            throw new Error("source path not found");
+        }
+        const skillName = parsed.skillName ?? inferSkillNameFromPath(parsed.fromPath);
+        return { sourceRoot, skillName };
+    }
+    const zipRef = parsed.fromZip;
+    const zipBytes = await resolveZipBytes(zipRef, io);
+    if (parsed.checksum !== undefined) {
+        const expected = parseChecksum(parsed.checksum);
+        const actual = sha256Hex(zipBytes);
+        if (actual !== expected) {
+            throw new Error("checksum mismatch");
+        }
+    }
+    const extractDir = await mkdtemp(path.join(tmpdir(), "sf-skill-zip-"));
+    await extractZipBuffer(zipBytes, extractDir);
+    const skillName = parsed.skillName ?? inferSkillNameFromZipRef(zipRef);
+    const sourceRoot = await findSkillRoot(extractDir, skillName);
+    return {
+        sourceRoot,
+        skillName,
+        cleanup: async () => {
+            await rm(extractDir, { recursive: true, force: true });
+        },
+    };
+}
+async function listSkills(projectRoot, io) {
+    const skillsDir = skillsDirForRoot(projectRoot);
+    let names;
+    try {
+        names = await readdir(skillsDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return;
+        }
+        throw err;
+    }
+    for (const name of names.sort()) {
+        const skillDir = path.join(skillsDir, name);
+        const skillStat = await stat(skillDir);
+        if (!skillStat.isDirectory()) {
+            continue;
+        }
+        let version = "—";
+        try {
+            const pkgRaw = await readFile(path.join(skillDir, "package.json"), "utf8");
+            const pkg = JSON.parse(pkgRaw);
+            if (typeof pkg.version === "string" && pkg.version.length > 0) {
+                version = pkg.version;
+            }
+        }
+        catch {
+            // no package.json
+        }
+        io.log(`${name}\t${version}\tbin/${name}.mjs`);
+    }
+}
+async function installSkill(projectRoot, parsed, io) {
+    const resolved = await resolveInstallSource(parsed, io);
+    try {
+        const destRoot = path.join(skillsDirForRoot(projectRoot), resolved.skillName);
+        await copySkillTree(resolved.sourceRoot, destRoot);
+        const doctorScript = path.join(destRoot, "bin", `${resolved.skillName}.mjs`);
+        const doctorCode = io.runDoctor(doctorScript, projectRoot);
+        if (doctorCode !== 0) {
+            io.error("skill doctor failed");
+            return 1;
+        }
+        io.log(`Installed skill ${resolved.skillName} to ${destRoot}`);
+        return 0;
+    }
+    finally {
+        if (resolved.cleanup) {
+            await resolved.cleanup();
+        }
+    }
+}
+export async function runSkillsCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? findProjectRoot(cwd) ?? path.resolve(cwd);
+    const io = { ...defaultIo, ...options.io };
+    try {
+        const parsed = parseSkillsArgs(args);
+        if (parsed.help) {
+            io.error(SKILLS_USAGE);
+            return 0;
+        }
+        if (parsed.subcommand === undefined) {
+            io.error(SKILLS_USAGE);
+            return 1;
+        }
+        if (parsed.subcommand === "list") {
+            await listSkills(projectRoot, io);
+            return 0;
+        }
+        return await installSkill(projectRoot, parsed, io);
+    }
+    catch (err) {
+        io.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}
+export function createStoredZip(files) {
+    const localParts = [];
+    const centralParts = [];
+    let offset = 0;
+    for (const file of files) {
+        const nameBuf = Buffer.from(file.name, "utf8");
+        const content = Buffer.isBuffer(file.content)
+            ? file.content
+            : Buffer.from(file.content, "utf8");
+        const localHeader = Buffer.alloc(30);
+        localHeader.writeUInt32LE(0x04034b50, 0);
+        localHeader.writeUInt16LE(20, 4);
+        localHeader.writeUInt16LE(0, 6);
+        localHeader.writeUInt16LE(0, 8);
+        localHeader.writeUInt32LE(0, 14);
+        localHeader.writeUInt32LE(content.length, 18);
+        localHeader.writeUInt32LE(content.length, 22);
+        localHeader.writeUInt16LE(nameBuf.length, 26);
+        localHeader.writeUInt16LE(0, 28);
+        localParts.push(localHeader, nameBuf, content);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0, 8);
+        central.writeUInt16LE(0, 10);
+        central.writeUInt32LE(0, 16);
+        central.writeUInt32LE(content.length, 20);
+        central.writeUInt32LE(content.length, 24);
+        central.writeUInt16LE(nameBuf.length, 28);
+        central.writeUInt16LE(0, 30);
+        central.writeUInt16LE(0, 32);
+        central.writeUInt32LE(offset, 42);
+        centralParts.push(central, nameBuf);
+        offset += 30 + nameBuf.length + content.length;
+    }
+    const centralDir = Buffer.concat(centralParts);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(0, 4);
+    eocd.writeUInt16LE(0, 6);
+    eocd.writeUInt16LE(files.length, 8);
+    eocd.writeUInt16LE(files.length, 10);
+    eocd.writeUInt32LE(centralDir.length, 12);
+    eocd.writeUInt32LE(offset, 16);
+    eocd.writeUInt16LE(0, 20);
+    return Buffer.concat([...localParts, centralDir, eocd]);
+}

package/dist/cli/validateOutput.d.ts

@@ -1,6 +1,6 @@
 import type { ValidationResult } from "../config/validateCatalog.js";
-export declare const VALIDATION_SCOPE_LINE = "Scope: pipeline and stage YAML only (task, checkout, providers not checked).";
-export declare const VALIDATION_CHECKS = "pipeline and stage YAML only";
+export declare const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, and tasks as selected by flags). Provider auth and checkout paths are not checked.";
+export declare const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks as selected by flags)";
 export declare function formatValidationHuman(result: ValidationResult, options?: {
     strict?: boolean;
 }): string;

package/dist/cli/validateOutput.js

@@ -1,6 +1,6 @@
 import { effectiveSeverity } from "../config/validateCatalog.js";
-export const VALIDATION_SCOPE_LINE = "Scope: pipeline and stage YAML only (task, checkout, providers not checked).";
-export const VALIDATION_CHECKS = "pipeline and stage YAML only";
+export const VALIDATION_SCOPE_LINE = "Scope: catalog YAML (pipelines, stages, and tasks as selected by flags). Provider auth and checkout paths are not checked.";
+export const VALIDATION_CHECKS = "catalog YAML (pipelines, stages, tasks as selected by flags)";
 function effectiveSeverityRank(finding, strict) {
     return effectiveSeverity(finding, strict) === "error" ? 0 : 1;
 }

package/dist/cli.js

@@ -4,27 +4,52 @@ 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 { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.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";
+import { PACKAGE_VERSION } from "./package-meta.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 runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
+  sf runs show --run <runId> [--from <sf-run.json>] [--json]
+  sf runs waiting [--run <runId>] [--json]
+  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]
+  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
+  sf runs retry --run <runId> --stage <stageId> [--json]
+  sf runs abandon --run <runId> --stage <stageId> [--json]
+  sf runs rerun --run <runId> [--json]
+  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 --version
+  sf -V
   sf --help
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
@@ -37,7 +62,17 @@ ${RUN_USAGE}
 
 ${VALIDATE_USAGE}
 
-${PROVIDERS_USAGE}`;
+${ARTIFACT_USAGE}
+
+${ENVELOPE_USAGE}
+
+${EXPORT_RUN_USAGE}
+
+${RUNS_USAGE}
+
+${PROVIDERS_USAGE}
+
+${SKILLS_USAGE}`;
 function parseArgs(argv) {
     const args = argv.slice(2);
     if (args.length === 0) {
@@ -47,11 +82,22 @@ function parseArgs(argv) {
         args.length === 1) {
         return { help: true };
     }
+    if (args[0] === "--version" || args[0] === "-V") {
+        if (args.length > 1) {
+            throw new Error(`Unexpected argument: ${args[1]}`);
+        }
+        return { help: false, version: true };
+    }
     const command = args[0];
     if (command === "providers" ||
         command === "validate" ||
         command === "run" ||
-        command === "init") {
+        command === "init" ||
+        command === "artifact" ||
+        command === "envelope" ||
+        command === "export-run" ||
+        command === "runs" ||
+        command === "skills") {
         return { help: false, command };
     }
     if (args.includes("--help") || args.includes("-h")) {
@@ -61,6 +107,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 +129,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;
@@ -211,6 +261,10 @@ async function main(argv) {
             console.log(USAGE);
             return argv.slice(2).length === 0 ? 1 : 0;
         }
+        if (parsed.version) {
+            console.log(PACKAGE_VERSION);
+            return 0;
+        }
         const ctx = await resolveStageflowContext(process.cwd());
         if (parsed.command === "init") {
             return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
@@ -225,17 +279,52 @@ 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 === "runs") {
+            return runRunsCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+                isGitProject: ctx.isGitProject,
+            });
+        }
         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 +332,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 = {