stageflow 0.32.0 → 0.35.0

package/dist/cli/runCommand.js

@@ -2,7 +2,8 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { coerceTaskFile } from "../config/loadTask.js";
-import { relativizeLocalPathForNetwork } from "../config/catalogRelativePath.js";
+import { isInsideProjectRoot, relativizeLocalPathForNetwork, } from "../config/catalogRelativePath.js";
+import { resolveCliProjectRootLocal } from "./resolveCliProjectRoot.js";
 import { PipelinePreflightError, PipelineValidationError } from "../runtime/pipelineRunner.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
 import { httpEnsureProject, httpStartRun, httpStoreReader } from "./hostClient.js";
@@ -10,7 +11,7 @@ import { reportCliRun, writeQueuedAdmissionLine, } from "./runOutput.js";
 import { resolveCiIdentity } from "./ciIdentity.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const RUN_USAGE = `Usage:
-  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--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> [--project-root <id-or-path>] [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -32,6 +33,7 @@ function parseRunArgs(args) {
     let ciJobUrl;
     let operatorCwd;
     let operatorAgentDir;
+    let projectRoot;
     let json = false;
     let includeStages = false;
     let skipGates = false;
@@ -111,6 +113,13 @@ function parseRunArgs(args) {
             }
             operatorAgentDir = value;
         }
+        else if (arg === "--project-root") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --project-root");
+            }
+            projectRoot = value;
+        }
         else if (arg === "--json") {
             json = true;
         }
@@ -151,8 +160,16 @@ function parseRunArgs(args) {
         ciJobUrl,
         operatorCwd,
         operatorAgentDir,
+        projectRoot,
     };
 }
+function resolvePathUnderCliRoot(rootPath, inputPath, label) {
+    const abs = path.resolve(rootPath, inputPath);
+    if (!isInsideProjectRoot(rootPath, abs)) {
+        throw new Error(`${label} ${abs} is outside project root ${rootPath}`);
+    }
+    return path.relative(rootPath, abs).replace(/\\/g, "/") || ".";
+}
 async function loadTaskWithBindingOverrides(taskPath, cwd, overrides) {
     const absolute = path.resolve(cwd, taskPath);
     const yamlText = await readFile(absolute, "utf8");
@@ -167,7 +184,7 @@ async function loadTaskWithBindingOverrides(taskPath, cwd, overrides) {
         task.ref = overrides.ref;
     return task;
 }
-function defaultStartRun(cwd, base, ensureService) {
+function defaultStartRun(cwd, base, ensureService, cliProjectRoot) {
     return async (input) => {
         const ensured = await ensureService();
         if (!ensured.ok) {
@@ -180,20 +197,34 @@ function defaultStartRun(cwd, base, ensureService) {
                     : {}),
             };
         }
-        const pipelineRef = relativizeLocalPathForNetwork(cwd, input.pipeline);
+        let pipelineRef;
         let task = input.task;
-        let projectRoot = pipelineRef.project_root;
-        if (typeof input.task === "string") {
-            const absTask = path.resolve(cwd, input.task);
-            const cwdAbs = path.resolve(cwd);
-            const relTask = path.relative(cwdAbs, absTask);
-            if (relTask.startsWith("..") || path.isAbsolute(relTask)) {
-                task = await loadTaskWithBindingOverrides(input.task, cwd, {});
+        let projectRoot;
+        if (cliProjectRoot) {
+            pipelineRef = {
+                path: resolvePathUnderCliRoot(cliProjectRoot.rootPath, input.pipeline, "Pipeline"),
+                project_root: cliProjectRoot.wireId,
+            };
+            projectRoot = cliProjectRoot.wireId;
+            if (typeof input.task === "string") {
+                task = resolvePathUnderCliRoot(cliProjectRoot.rootPath, input.task, "Task");
             }
-            else {
-                const taskRef = relativizeLocalPathForNetwork(cwd, input.task);
-                task = taskRef.path;
-                projectRoot = taskRef.project_root;
+        }
+        else {
+            pipelineRef = relativizeLocalPathForNetwork(cwd, input.pipeline);
+            projectRoot = pipelineRef.project_root;
+            if (typeof input.task === "string") {
+                const absTask = path.resolve(cwd, input.task);
+                const cwdAbs = path.resolve(cwd);
+                const relTask = path.relative(cwdAbs, absTask);
+                if (relTask.startsWith("..") || path.isAbsolute(relTask)) {
+                    task = await loadTaskWithBindingOverrides(input.task, cwd, {});
+                }
+                else {
+                    const taskRef = relativizeLocalPathForNetwork(cwd, input.task);
+                    task = taskRef.path;
+                    projectRoot = taskRef.project_root;
+                }
             }
         }
         const ensuredProject = await httpEnsureProject(base, projectRoot);
@@ -253,8 +284,18 @@ export async function runRunCommand(args, options = {}) {
     if (parsed.operatorCwd !== undefined || parsed.operatorAgentDir !== undefined) {
         out.error("warning: --operator-cwd/--operator-agent-dir have no effect on `sf run` now that pipelines execute in the shared global Stageflow service; set STAGEFLOW_OPERATOR_CWD/STAGEFLOW_OPERATOR_AGENT_DIR before that service first starts instead.");
     }
+    let cliProjectRoot;
+    if (parsed.projectRoot !== undefined) {
+        const local = resolveCliProjectRootLocal(parsed.projectRoot);
+        if (!local) {
+            out.error(`Unknown project_root: ${parsed.projectRoot.trim()}`);
+            out.error(RUN_USAGE);
+            return 1;
+        }
+        cliProjectRoot = local;
+    }
     const startRun = options.startRun ??
-        defaultStartRun(cwd, base, options.ensureService ?? (() => ensureGlobalService()));
+        defaultStartRun(cwd, base, options.ensureService ?? (() => ensureGlobalService()), cliProjectRoot);
     const identity = resolveCiIdentity({
         flags: {
             gitSha: parsed.gitSha,
@@ -266,8 +307,9 @@ export async function runRunCommand(args, options = {}) {
     const store = options.store ?? (parsed.includeStages ? httpStoreReader(base) : undefined);
     try {
         const hasBindingOverride = parsed.repository !== undefined || parsed.ref !== undefined;
+        const taskLoadRoot = cliProjectRoot?.rootPath ?? cwd;
         const taskInput = hasBindingOverride
-            ? await loadTaskWithBindingOverrides(parsed.task, cwd, {
+            ? await loadTaskWithBindingOverrides(parsed.task, taskLoadRoot, {
                 repository: parsed.repository,
                 ref: parsed.ref,
             })

package/dist/cli/skillsCommand.d.ts

@@ -5,6 +5,26 @@ export type SkillsCommandIo = {
     fetch: typeof globalThis.fetch;
     runDoctor: (scriptPath: string, cwd: string) => number;
 };
+export type InstallProjectSkillInput = {
+    projectRoot: string;
+    fromPath?: string;
+    fromZip?: string;
+    zipBytes?: Uint8Array;
+    skillName?: string;
+    checksum?: string;
+    io?: Partial<SkillsCommandIo>;
+};
+export type InstallProjectSkillResult = {
+    ok: true;
+    skillName: string;
+    destPath: string;
+    message: string;
+} | {
+    ok: false;
+    error: string;
+    doctorFailed?: boolean;
+};
+export declare function installProjectSkill(input: InstallProjectSkillInput): Promise<InstallProjectSkillResult>;
 export declare function runSkillsCommand(args: string[], options?: {
     cwd?: string;
     projectRoot?: string;

package/dist/cli/skillsCommand.js

@@ -291,14 +291,18 @@ async function findSkillRootBySkillMd(dir) {
     }
     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);
+async function resolveInstallSource(input, io) {
+    const hasPath = input.fromPath !== undefined;
+    const hasZip = input.fromZip !== undefined;
+    const hasZipBytes = input.zipBytes !== undefined;
+    const sourceCount = Number(hasPath) + Number(hasZip) + Number(hasZipBytes);
+    if (sourceCount !== 1) {
+        throw new Error(hasZipBytes
+            ? "specify exactly one of fromPath, fromZip, or zipBytes"
+            : "specify exactly one of --from-path or --from-zip");
+    }
+    if (input.fromPath !== undefined) {
+        const sourceRoot = path.resolve(input.fromPath);
         try {
             const sourceStat = await stat(sourceRoot);
             if (!sourceStat.isDirectory()) {
@@ -308,13 +312,21 @@ async function resolveInstallSource(parsed, io) {
         catch {
             throw new Error("source path not found");
         }
-        const skillName = parsed.skillName ?? inferSkillNameFromPath(parsed.fromPath);
+        const skillName = input.skillName ?? inferSkillNameFromPath(input.fromPath);
         return { sourceRoot, skillName };
     }
-    const zipRef = parsed.fromZip;
-    const zipBytes = await resolveZipBytes(zipRef, io);
-    if (parsed.checksum !== undefined) {
-        const expected = parseChecksum(parsed.checksum);
+    let zipBytes;
+    let inferredZipName;
+    if (input.zipBytes !== undefined) {
+        zipBytes = Buffer.from(input.zipBytes);
+    }
+    else {
+        const zipRef = input.fromZip;
+        zipBytes = await resolveZipBytes(zipRef, io);
+        inferredZipName = inferSkillNameFromZipRef(zipRef);
+    }
+    if (input.checksum !== undefined) {
+        const expected = parseChecksum(input.checksum);
         const actual = sha256Hex(zipBytes);
         if (actual !== expected) {
             throw new Error("checksum mismatch");
@@ -322,8 +334,9 @@ async function resolveInstallSource(parsed, io) {
     }
     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);
+    const lookupName = input.skillName ?? inferredZipName ?? "skill";
+    const sourceRoot = await findSkillRoot(extractDir, lookupName);
+    const skillName = input.skillName ?? inferredZipName ?? path.basename(sourceRoot);
     return {
         sourceRoot,
         skillName,
@@ -364,24 +377,46 @@ async function listSkills(projectRoot, io) {
         io.log(`${name}\t${version}\tbin/${name}.mjs`);
     }
 }
-async function installSkill(projectRoot, parsed, io) {
-    const resolved = await resolveInstallSource(parsed, io);
+export async function installProjectSkill(input) {
+    const io = { ...defaultIo, ...input.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;
+        const resolved = await resolveInstallSource({
+            fromPath: input.fromPath,
+            fromZip: input.fromZip,
+            zipBytes: input.zipBytes,
+            skillName: input.skillName,
+            checksum: input.checksum,
+        }, io);
+        try {
+            const destRoot = path.join(skillsDirForRoot(input.projectRoot), resolved.skillName);
+            await copySkillTree(resolved.sourceRoot, destRoot);
+            const doctorScript = path.join(destRoot, "bin", `${resolved.skillName}.mjs`);
+            if (await pathExists(doctorScript)) {
+                const doctorCode = io.runDoctor(doctorScript, input.projectRoot);
+                if (doctorCode !== 0) {
+                    io.error("skill doctor failed");
+                    return { ok: false, error: "skill doctor failed", doctorFailed: true };
+                }
+            }
+            const message = `Installed skill ${resolved.skillName} to ${destRoot}`;
+            io.log(message);
+            return {
+                ok: true,
+                skillName: resolved.skillName,
+                destPath: destRoot,
+                message,
+            };
+        }
+        finally {
+            if (resolved.cleanup) {
+                await resolved.cleanup();
+            }
         }
-        io.log(`Installed skill ${resolved.skillName} to ${destRoot}`);
-        return 0;
     }
-    finally {
-        if (resolved.cleanup) {
-            await resolved.cleanup();
-        }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        io.error(error);
+        return { ok: false, error };
     }
 }
 export async function runSkillsCommand(args, options = {}) {
@@ -402,7 +437,15 @@ export async function runSkillsCommand(args, options = {}) {
             await listSkills(projectRoot, io);
             return 0;
         }
-        return await installSkill(projectRoot, parsed, io);
+        const result = await installProjectSkill({
+            projectRoot,
+            fromPath: parsed.fromPath,
+            fromZip: parsed.fromZip,
+            skillName: parsed.skillName,
+            checksum: parsed.checksum,
+            io,
+        });
+        return result.ok ? 0 : 1;
     }
     catch (err) {
         io.error(err instanceof Error ? err.message : String(err));

package/dist/cli/validateCommand.d.ts

@@ -1,5 +1,5 @@
 import { validateCatalog as defaultValidateCatalog, type ValidationResult } from "../config/validateCatalog.js";
-export declare const VALIDATE_USAGE = "Usage:\n  sf validate [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]\n\n  With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).\n  --pipeline validates one pipeline file (includes uses:/include: transitively).\n  --task validates one task file.\n  --trigger validates one trigger file, including its pipeline/task refs.";
+export declare const VALIDATE_USAGE = "Usage:\n  sf validate [--project-root <id-or-path>] [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]\n\n  With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).\n  --pipeline validates one pipeline file (includes uses:/include: transitively).\n  --task validates one task file.\n  --trigger validates one trigger file, including its pipeline/task refs.";
 export type ValidateCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/validateCommand.js

@@ -1,7 +1,8 @@
 import { validateCatalog as defaultValidateCatalog, } from "../config/validateCatalog.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
+import { resolveCliProjectRootLocal } from "./resolveCliProjectRoot.js";
 export const VALIDATE_USAGE = `Usage:
-  sf validate [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]
+  sf validate [--project-root <id-or-path>] [--pipeline <path>] [--task <path>] [--trigger <path>] [--strict] [--json]
 
   With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).
   --pipeline validates one pipeline file (includes uses:/include: transitively).
@@ -18,6 +19,7 @@ function parseValidateArgs(args) {
     if (args[0] === "--help" || args[0] === "-h") {
         return { help: true, strict: false, json: false };
     }
+    let projectRoot;
     let pipeline;
     let task;
     let trigger;
@@ -29,6 +31,13 @@ function parseValidateArgs(args) {
         if (arg === "--help" || arg === "-h") {
             help = true;
         }
+        else if (arg === "--project-root") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --project-root");
+            }
+            projectRoot = value;
+        }
         else if (arg === "--pipeline") {
             const value = args[++i];
             if (value === undefined || value.length === 0) {
@@ -67,11 +76,10 @@ function parseValidateArgs(args) {
     if (scopedFlagCount > 1) {
         throw new Error("Use at most one of --pipeline, --task, or --trigger");
     }
-    return { help, pipeline, task, trigger, strict, json };
+    return { help, projectRoot, pipeline, task, trigger, strict, json };
 }
 export async function runValidateCommand(args, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const projectRoot = options.projectRoot ?? cwd;
+    const shellCwd = options.cwd ?? process.cwd();
     const out = { ...defaultIo, ...options.io };
     const validateCatalogFn = options.validateCatalog ?? defaultValidateCatalog;
     try {
@@ -80,6 +88,16 @@ export async function runValidateCommand(args, options = {}) {
             out.error(VALIDATE_USAGE);
             return 0;
         }
+        let cwd = shellCwd;
+        let projectRoot = options.projectRoot ?? shellCwd;
+        if (parsed.projectRoot !== undefined) {
+            const resolved = resolveCliProjectRootLocal(parsed.projectRoot);
+            if (!resolved) {
+                throw new Error(`Unknown project_root: ${parsed.projectRoot.trim()}`);
+            }
+            cwd = resolved.rootPath;
+            projectRoot = resolved.rootPath;
+        }
         const scope = parsed.pipeline
             ? "pipeline"
             : parsed.task

package/dist/cli.js

@@ -4,7 +4,7 @@ import { A2A_USAGE, runA2aCommand } from "./cli/a2aCommand.js";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { globalAgentBackendFromManifest, resolveAgentPort } from "./agent/resolveAgentPort.js";
+import { globalStageBackendFromManifest, resolveStagePort } from "./agent/resolveStagePort.js";
 import { BROWSER_USAGE, runBrowserCommand } from "./cli/browserCommand.js";
 import { ARTIFACT_USAGE, runArtifactCommand } from "./cli/artifactCommand.js";
 import { ENVELOPE_USAGE, runEnvelopeCommand, } from "./cli/envelopeCommand.js";
@@ -503,7 +503,7 @@ async function main(argv) {
         if (parsed.command === "browser") {
             return runBrowserCommand(argv.slice(3));
         }
-        const globalAgent = globalAgentBackendFromManifest(ctx.manifest);
+        const globalAgent = globalStageBackendFromManifest(ctx.manifest);
         if (parsed.command === "ui") {
             const listenHost = resolveListenHost({ flag: parsed.host });
             const tokens = loadControlTokens();
@@ -512,7 +512,7 @@ async function main(argv) {
                 mcpStateless: parsed.mcpStateless,
             });
             const host = await startUiServer({
-                agent: resolveAgentPort({ global: globalAgent }),
+                agent: resolveStagePort({ global: globalAgent }),
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
                 port: parsed.port,
@@ -547,7 +547,7 @@ async function main(argv) {
                 mcpStateless: parsed.mcpStateless,
             });
             const host = await startMcpServer({
-                agent: resolveAgentPort({ global: globalAgent }),
+                agent: resolveStagePort({ global: globalAgent }),
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
                 port: parsed.port,

package/dist/config/browseCatalog.d.ts

@@ -13,6 +13,8 @@ export type PipelineStageListing = {
     gate_kinds?: StageGateKind[];
     uses_path?: string;
     inline?: boolean;
+    model?: string;
+    skill?: string;
 };
 export type PipelineListing = {
     path: string;

package/dist/config/browseCatalog.js

@@ -22,6 +22,12 @@ function mapStageListing(stage, source, projectRoot) {
     else if (source?.kind === "file") {
         listing.uses_path = repoRelPath(projectRoot, source.path);
     }
+    if (typeof stage.model === "string" && stage.model.trim() !== "") {
+        listing.model = stage.model;
+    }
+    if (typeof stage.skill === "string" && stage.skill.trim() !== "") {
+        listing.skill = stage.skill;
+    }
     return listing;
 }
 function bakedModels() {

package/dist/config/catalogRelativePath.d.ts

@@ -37,6 +37,10 @@ export declare function catalogPathErrorBody(err: CatalogPathError): {
  * otherwise require explicit — no invent.
  */
 export declare function selectCatalogRootForStart(roots: CatalogRoot[], projectRoot?: string): CatalogRoot;
+export declare function resolveDefaultWriteRoot(options: ResolveCatalogRootsOptions, projectRoot?: string): Promise<{
+    roots: CatalogRoot[];
+    wireRoot: CatalogRoot;
+}>;
 /**
  * Shared helper: resolveCatalogRoots → selectCatalogRootForStart.
  * All network-surface start-input call sites use this to avoid the hand-copy sequence.

package/dist/config/catalogRelativePath.js

@@ -82,11 +82,43 @@ export function selectCatalogRootForStart(roots, projectRoot) {
     if (roots.length === 1) {
         return roots[0];
     }
-    const writable = roots.filter((r) => r.kind !== "seeded");
-    if (writable.length === 1) {
-        return writable[0];
+    const registeredOnly = roots.filter((r) => r.kind === "registered");
+    if (registeredOnly.length === 1) {
+        return registeredOnly[0];
     }
-    throw new CatalogPathError("project_root is required when multiple catalog roots are configured", "unknown_project_root", registered);
+    const nonSeeded = roots.filter((r) => r.kind !== "seeded");
+    if (nonSeeded.length === 1) {
+        return nonSeeded[0];
+    }
+    const ids = roots.map((r) => r.project_root).join(", ");
+    throw new CatalogPathError(`project_root is required when multiple catalog roots are configured (${ids})`, "unknown_project_root", registered);
+}
+function workspaceRoot(roots) {
+    return roots.find((r) => r.kind === "workspace");
+}
+export async function resolveDefaultWriteRoot(options, projectRoot) {
+    const roots = await resolveCatalogRoots(options);
+    const registered = roots.map((r) => r.project_root);
+    if (projectRoot !== undefined) {
+        const found = findCatalogRoot(roots, projectRoot);
+        if (found === undefined) {
+            throw new CatalogPathError(`Unknown project_root: ${projectRoot}`, "unknown_project_root", registered);
+        }
+        if (found.read_only) {
+            throw new CatalogPathError(`Catalog root ${found.project_root} is read-only`, "catalog_root_read_only", registered);
+        }
+        if (found.kind === "workspace" && found.available === false) {
+            throw new CatalogPathError(found.unavailable_reason ??
+                `Workspace catalog is not writable (${found.path})`, "unknown_project_root", registered);
+        }
+        return { roots, wireRoot: found };
+    }
+    const ws = workspaceRoot(roots);
+    if (ws === undefined || ws.available === false) {
+        throw new CatalogPathError(ws?.unavailable_reason ??
+            "Workspace catalog is unavailable; set project_root explicitly", "unknown_project_root", registered);
+    }
+    return { roots, wireRoot: ws };
 }
 /**
  * Shared helper: resolveCatalogRoots → selectCatalogRootForStart.
@@ -102,11 +134,7 @@ export async function resolveCatalogStartInput(options, projectRoot) {
  * Used by write surfaces (POST /api/stages, POST /api/pipelines).
  */
 export async function resolveWritableCatalogRoot(options, projectRoot) {
-    const { roots, wireRoot } = await resolveCatalogStartInput(options, projectRoot);
-    if (wireRoot.read_only) {
-        throw new CatalogPathError(`Catalog root ${wireRoot.project_root} is read-only`, "catalog_root_read_only", roots.map((r) => r.project_root));
-    }
-    return { roots, wireRoot };
+    return resolveDefaultWriteRoot(options, projectRoot);
 }
 /**
  * Local CLI control: turn a cwd-resolved filesystem path into a catalog-relative

package/dist/config/createStage.d.ts

@@ -7,6 +7,7 @@ export type CreateStageInput = {
     system_prompt: string;
     model?: string;
     gate_kinds?: StageGateKind[];
+    skill?: string;
 };
 export type CreatedStageListing = {
     path: string;

package/dist/config/createStage.js

@@ -41,8 +41,12 @@ export function parseCreateStageBody(body) {
     if ("payload_schema" in body) {
         return { ok: false, status: 400, error: "payload_schema is not supported" };
     }
-    if ("skill" in body) {
-        return { ok: false, status: 400, error: "skill is not supported" };
+    let skill;
+    if (body.skill !== undefined) {
+        if (typeof body.skill !== "string" || body.skill.trim() === "") {
+            return { ok: false, status: 400, error: "skill must be a non-empty string" };
+        }
+        skill = body.skill.trim();
     }
     if (typeof body.pipeline_directory !== "string" || !body.pipeline_directory.trim()) {
         return { ok: false, status: 400, error: "pipeline_directory is required" };
@@ -84,6 +88,7 @@ export function parseCreateStageBody(body) {
         system_prompt: body.system_prompt,
         ...(model !== undefined ? { model } : {}),
         ...(gateKinds !== undefined ? { gate_kinds: gateKinds } : {}),
+        ...(skill !== undefined ? { skill } : {}),
     };
 }
 function formatInlineYamlScalar(value) {
@@ -122,6 +127,9 @@ export function stageConfigToYaml(stage) {
     if (stage.model !== undefined && stage.model.length > 0) {
         lines.push(`model: ${formatInlineYamlScalar(stage.model)}`);
     }
+    if (stage.skill !== undefined && stage.skill.length > 0) {
+        lines.push(`skill: ${formatInlineYamlScalar(stage.skill)}`);
+    }
     lines.push("io:");
     lines.push("  input:");
     lines.push("    schema:");
@@ -204,6 +212,7 @@ export async function createStage(projectRoot, input) {
             system_prompt: input.system_prompt,
             ...(input.model !== undefined && input.model.length > 0 ? { model: input.model } : {}),
             ...(input.gate_kinds !== undefined ? { gate_kinds: input.gate_kinds } : {}),
+            ...(input.skill !== undefined && input.skill.length > 0 ? { skill: input.skill } : {}),
         }), "utf8");
     }
     catch (err) {

package/dist/config/createTask.d.ts

@@ -0,0 +1,30 @@
+import type { TaskDetail } from "./findTaskInCatalog.js";
+export type CreateTaskInput = {
+    directory: string;
+    id: string;
+    goal: string;
+    context?: string;
+    constraints?: string;
+    checkout?: string;
+    repository?: string;
+    ref?: string;
+};
+export type CreateTaskParseError = {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export type CreateTaskResult = {
+    ok: true;
+    task: TaskDetail;
+} | {
+    ok: false;
+    status: 400 | 404 | 409 | 500 | 502;
+    error: string;
+};
+export declare function validateTaskId(id: string): string | null;
+export declare function parseCreateTaskBody(body: unknown): CreateTaskInput | CreateTaskParseError;
+export declare function resolveTaskDirectory(projectRoot: string, directory: string): string | null;
+export declare function taskFieldsToYaml(fields: CreateTaskInput): string;
+export declare function findTaskIdCollision(projectRoot: string, id: string, targetPath: string): Promise<string | null>;
+export declare function createTask(rawProjectRoot: string, input: CreateTaskInput): Promise<CreateTaskResult>;