stageflow 0.19.0 → 0.25.0

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { A2A_USAGE, runA2aCommand } from "./cli/a2aCommand.js";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,6 +11,7 @@ import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.j
 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 { RUN_STAGE_USAGE, runRunStageCommand } from "./cli/runStageCommand.js";
 import { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
 import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
@@ -27,6 +29,7 @@ import { PACKAGE_VERSION } from "./package-meta.js";
 const USAGE = `Usage:
   sf init
   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 run-stage (--stage <path> | --stage-inline '<json>') (--task <path> | --task-inline '<json>' | --envelope-ref <runId>:<stageId>[:<attempt>]) [--checkout <path>] [--model <id>] [--blocking] [--timeout-ms <n>] [--json]
   sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]
   sf graph --pipeline <path> [--json]
   sf migrate-yaml [path] [--root <path>] [--write] [--json] [--force]
@@ -58,6 +61,8 @@ const USAGE = `Usage:
   sf --version
   sf -V
   sf --help
+  sf a2a validate|list [--config <path>]
+  sf a2a add-caller <id> [--config <path>] [--token-env <NAME>]
 
 Stageflow (sf) runs YAML-defined automatic stage pipelines.
 
@@ -67,10 +72,14 @@ ${INIT_USAGE}
 
 ${RUN_USAGE}
 
+${RUN_STAGE_USAGE}
+
 ${VALIDATE_USAGE}
 
 ${GRAPH_USAGE}
 
+${A2A_USAGE}
+
 ${MIGRATE_YAML_USAGE}
 
 ${ARTIFACT_USAGE}
@@ -103,8 +112,10 @@ function parseArgs(argv) {
     if (command === "providers" ||
         command === "validate" ||
         command === "graph" ||
+        command === "a2a" ||
         command === "migrate-yaml" ||
         command === "run" ||
+        command === "run-stage" ||
         command === "init" ||
         command === "artifact" ||
         command === "envelope" ||
@@ -282,6 +293,9 @@ async function main(argv) {
             return 0;
         }
         const ctx = await resolveStageflowContext(process.cwd());
+        if (parsed.command === "a2a") {
+            return runA2aCommand(argv.slice(3), { cwd: ctx.invocationCwd, projectRoot: ctx.projectRoot });
+        }
         if (parsed.command === "init") {
             return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
         }
@@ -306,8 +320,11 @@ async function main(argv) {
         if (parsed.command === "run") {
             return runRunCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,
-                projectRoot: ctx.projectRoot,
-                isGitProject: ctx.isGitProject,
+            });
+        }
+        if (parsed.command === "run-stage") {
+            return runRunStageCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
             });
         }
         if (parsed.command === "artifact") {
@@ -331,8 +348,6 @@ async function main(argv) {
         if (parsed.command === "runs") {
             return runRunsCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,
-                projectRoot: ctx.projectRoot,
-                isGitProject: ctx.isGitProject,
             });
         }
         if (parsed.command === "providers") {
@@ -344,7 +359,7 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
-        const store = createRunStore({ rootDir: ctx.projectRoot });
+        const store = createRunStore({ rootDir: ctx.globalHome });
         const globalAgent = globalAgentBackendFromManifest(ctx.manifest);
         if (parsed.command === "ui") {
             const mcpStateless = resolveMcpStateless({

package/dist/config/describePipeline.d.ts

@@ -0,0 +1,26 @@
+import type { CloneMode, FeedbackLoopConfig, LoadedPipeline, PipelineForkConfig, PipelineNeedEdge, ResolvedPipelineStageNode, RouteIfPredicate } from "../types/pipeline.js";
+import type { StageGateKind } from "../types/stage.js";
+export type PipelineDescribeNeedEdge = {
+    id: string;
+    on: PipelineNeedEdge["on"];
+    if?: RouteIfPredicate;
+};
+export type PipelineDescribeNeeds = string | null | PipelineDescribeNeedEdge[];
+export type PipelineDescribeStage = {
+    id: string;
+    needs: PipelineDescribeNeeds;
+    fork?: PipelineForkConfig;
+    gate_kinds?: StageGateKind[];
+    clone_cap?: number;
+    clone_mode?: CloneMode;
+    feedback_loop?: FeedbackLoopConfig;
+    entry?: boolean;
+    replay_safe?: boolean;
+};
+export type PipelineDescribe = {
+    id: string;
+    path: string;
+    stages: PipelineDescribeStage[];
+};
+export declare function describePipelineNeeds(node: ResolvedPipelineStageNode): PipelineDescribeNeeds;
+export declare function describePipeline(loaded: LoadedPipeline): PipelineDescribe;

package/dist/config/describePipeline.js

@@ -0,0 +1,37 @@
+import { toPipelineNeeds } from "./pipelineNeeds.js";
+export function describePipelineNeeds(node) {
+    if (node.needsEdges.length === 0)
+        return node.needs;
+    const collapsed = toPipelineNeeds(node.needsEdges);
+    if (typeof collapsed === "string")
+        return collapsed;
+    return collapsed.map((edge) => ({
+        id: edge.id,
+        on: [...edge.on],
+        ...(edge.if !== undefined ? { if: edge.if } : {}),
+    }));
+}
+export function describePipeline(loaded) {
+    const gateById = new Map(loaded.stages.map((stage) => [stage.id, stage.gate_kinds]));
+    const stages = loaded.dag.nodes.map((node) => {
+        const gateKinds = gateById.get(node.id);
+        return {
+            id: node.id,
+            needs: describePipelineNeeds(node),
+            ...(node.fork !== undefined ? { fork: { ...node.fork } } : {}),
+            ...(node.clone_cap !== undefined ? { clone_cap: node.clone_cap } : {}),
+            ...(node.clone_mode !== undefined ? { clone_mode: node.clone_mode } : {}),
+            ...(node.feedback_loop !== undefined
+                ? { feedback_loop: { ...node.feedback_loop } }
+                : {}),
+            ...(node.entry !== undefined ? { entry: node.entry } : {}),
+            ...(node.replay_safe !== undefined ? { replay_safe: node.replay_safe } : {}),
+            ...(gateKinds !== undefined ? { gate_kinds: [...gateKinds] } : {}),
+        };
+    });
+    return {
+        id: loaded.pipeline.id,
+        path: loaded.pipelinePath,
+        stages,
+    };
+}

package/dist/config/loadPipeline.d.ts

@@ -1,8 +1,20 @@
-import type { LoadedPipeline } from "../types/pipeline.js";
+import type { InlinePipelineDefinition, LoadedPipeline } from "../types/pipeline.js";
 import { type LoadOutcome } from "./loadOutcome.js";
 export type { LoadedPipeline } from "../types/pipeline.js";
 export type { LoadIssue, LoadOutcome } from "./loadOutcome.js";
 export declare function resolvePipelinePath(pipelinePath: string, cwd: string): Promise<string>;
+/** Synthetic `pipelinePath` for a `LoadedPipeline` built from an inline object with no backing file. */
+export declare const INLINE_PIPELINE_PATH = "<inline>";
+export declare function loadPipelineFromObjectOutcome(raw: InlinePipelineDefinition, options?: {
+    cwd?: string;
+    projectRoot?: string;
+    requireIo?: boolean;
+}): Promise<LoadOutcome<LoadedPipeline>>;
+export declare function loadPipelineFromObject(raw: InlinePipelineDefinition, options?: {
+    cwd?: string;
+    projectRoot?: string;
+    requireIo?: boolean;
+}): Promise<LoadedPipeline>;
 export declare function loadPipelineOutcome(nameOrPath: string, options?: {
     cwd?: string;
     projectRoot?: string;

package/dist/config/loadPipeline.js

@@ -2,7 +2,7 @@ import { access } from "node:fs/promises";
 import path from "node:path";
 import { compilePayloadSchema, expandPayloadSchemaRefs, isPayloadSchemaSubset, UnresolvedSchemaRefError, } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
-import { mergePipelineStages } from "./mergePipelineIncludes.js";
+import { mergeInlinePipelineStages, mergePipelineStages, } from "./mergePipelineIncludes.js";
 import { normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
 import { loadStageFromObjectOutcome, loadStageOutcome, afterCompletionForStage } from "./loadStage.js";
 import { materializeStageModels } from "./materializeStageModels.js";
@@ -92,14 +92,44 @@ export async function resolvePipelinePath(pipelinePath, cwd) {
         throw new Error(`Pipeline file not found: ${resolved}. Pass a filesystem path to --pipeline (e.g. pipelines/hello.pipeline.yaml), not a bare pipeline id.`);
     }
 }
+/** Synthetic `pipelinePath` for a `LoadedPipeline` built from an inline object with no backing file. */
+export const INLINE_PIPELINE_PATH = "<inline>";
 async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd, requireIo = true) {
     const normalizedPipelinePath = path.normalize(path.resolve(pipelinePath));
     const mergeOutcome = await mergePipelineStages(normalizedPipelinePath);
     if (!mergeOutcome.ok) {
         return loadFailure(mergeOutcome.issues);
     }
-    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, warnings: mergeWarnings, } = mergeOutcome.value;
-    const ctx = { pipelineId, path: normalizedPipelinePath };
+    return buildLoadedPipelineFromMerge(mergeOutcome.value, {
+        projectRoot,
+        requireIo,
+        pipelinePath: normalizedPipelinePath,
+    });
+}
+export async function loadPipelineFromObjectOutcome(raw, options = {}) {
+    const projectRoot = options.projectRoot ?? options.cwd ?? process.cwd();
+    const requireIo = options.requireIo !== false;
+    const mergeOutcome = await mergeInlinePipelineStages(raw);
+    if (!mergeOutcome.ok) {
+        return loadFailure(mergeOutcome.issues);
+    }
+    return buildLoadedPipelineFromMerge(mergeOutcome.value, {
+        projectRoot,
+        requireIo,
+        pipelinePath: INLINE_PIPELINE_PATH,
+    });
+}
+export async function loadPipelineFromObject(raw, options = {}) {
+    const outcome = await loadPipelineFromObjectOutcome(raw, options);
+    if (!outcome.ok) {
+        throw new Error(outcome.issues[0].message);
+    }
+    return outcome.value;
+}
+async function buildLoadedPipelineFromMerge(merge, options) {
+    const { projectRoot, requireIo, pipelinePath } = options;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, warnings: mergeWarnings, } = merge;
+    const ctx = { pipelineId, path: pipelinePath };
     const warnings = [...mergeWarnings];
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
     if (!normalizeOutcome.ok) {
@@ -274,7 +304,7 @@ async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd, requir
         pipeline,
         stages: loadedStages,
         dag,
-        pipelinePath: normalizedPipelinePath,
+        pipelinePath,
         stageSources,
     }, warnings);
 }

package/dist/config/mergePipelineIncludes.d.ts

@@ -1,4 +1,5 @@
 import type { PayloadSchemaMap } from "../envelope/payloadSchema.js";
+import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
 export type RawMergedEntry = {
     raw: unknown;
@@ -12,3 +13,13 @@ export declare function mergePipelineStages(rootPath: string): Promise<LoadOutco
     schemas?: PayloadSchemaMap;
     warnings: LoadIssue[];
 }>>;
+/** Synthetic `declaringPath` for stage entries with no backing file. */
+export declare const INLINE_DECLARING_PATH = "<inline pipeline>";
+export declare function mergeInlinePipelineStages(raw: InlinePipelineDefinition): Promise<LoadOutcome<{
+    entries: RawMergedEntry[];
+    pipelineId: string;
+    agent?: string;
+    model?: string;
+    schemas?: PayloadSchemaMap;
+    warnings: LoadIssue[];
+}>>;

package/dist/config/mergePipelineIncludes.js

@@ -201,6 +201,81 @@ export async function mergePipelineStages(rootPath) {
         warnings,
     });
 }
+/** Synthetic `declaringPath` for stage entries with no backing file. */
+export const INLINE_DECLARING_PATH = "<inline pipeline>";
+export async function mergeInlinePipelineStages(raw) {
+    if (typeof raw.id !== "string" || !raw.id) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_shape",
+                message: `Invalid inline pipeline: id is required`,
+                category: "pipeline",
+            },
+        ]);
+    }
+    if (!Array.isArray(raw.stages) || raw.stages.length === 0) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_shape",
+                message: `Invalid inline pipeline ${raw.id}: stages must be non-empty`,
+                category: "pipeline",
+                pipelineId: raw.id,
+            },
+        ]);
+    }
+    const pipelineId = raw.id;
+    const agentField = parseAgentField(raw.agent);
+    if (!agentField.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_agent",
+                message: `Invalid inline pipeline ${pipelineId}: ${agentField.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const agent = agentField.value;
+    const modelField = parseModelField(raw.model);
+    if (!modelField.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_model",
+                message: `Invalid inline pipeline ${pipelineId}: ${modelField.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const model = modelField.value;
+    const schemasOutcome = parsePipelineSchemas(raw.schemas, "<inline pipeline>", pipelineId);
+    if (!schemasOutcome.ok)
+        return schemasOutcome;
+    const schemas = schemasOutcome.value;
+    const entries = [];
+    for (let index = 0; index < raw.stages.length; index++) {
+        const entry = raw.stages[index];
+        if (isPlainObject(entry) && typeof entry.uses === "string") {
+            return loadFailure([
+                {
+                    code: "pipeline.invalid_shape",
+                    message: `Invalid inline pipeline ${pipelineId}: stage entry at index ${index} has "uses" — inline pipelines cannot reference external stage files, all stage bodies must be inline`,
+                    category: "pipeline",
+                    pipelineId,
+                },
+            ]);
+        }
+        entries.push({ raw: entry, declaringPath: INLINE_DECLARING_PATH });
+    }
+    return loadSuccess({
+        entries,
+        pipelineId,
+        ...(agent !== undefined ? { agent } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(schemas !== undefined ? { schemas } : {}),
+        warnings: [],
+    });
+}
 function parsePipelineSchemas(raw, absPath, pipelineId) {
     if (raw === undefined)
         return loadSuccess(undefined);

package/dist/config/validateCatalog.d.ts

@@ -1,4 +1,4 @@
-import type { LoadedPipeline } from "../types/pipeline.js";
+import type { InlinePipelineDefinition, LoadedPipeline } from "../types/pipeline.js";
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task";
@@ -50,7 +50,7 @@ export type LoadPipelineValidatedResult = {
     ok: false;
     findings: ValidationFinding[];
 };
-export declare function loadPipelineValidated(nameOrPath: string, options?: {
+export declare function loadPipelineValidated(nameOrPath: string | InlinePipelineDefinition, options?: {
     cwd?: string;
     projectRoot?: string;
     validateStages?: boolean;

package/dist/config/validateCatalog.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { loadPipelineOutcome, resolvePipelinePath } from "./loadPipeline.js";
+import { INLINE_PIPELINE_PATH, loadPipelineFromObjectOutcome, loadPipelineOutcome, resolvePipelinePath, } from "./loadPipeline.js";
 import { loadStageOutcome } from "./loadStage.js";
 import { loadTaskOutcome } from "./loadTask.js";
 import { readYamlObject } from "./readYamlObject.js";
@@ -241,23 +241,30 @@ async function runPipelineValidation(nameOrPath, options) {
     const { cwd, validateStages } = options;
     const projectRoot = options.projectRoot ?? cwd;
     let pipelinePath;
-    try {
-        pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
+    let outcome;
+    if (typeof nameOrPath === "string") {
+        try {
+            pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                findings: findingsFromLoadIssues(cwd, path.resolve(cwd, nameOrPath), [
+                    {
+                        code: "pipeline.load_error",
+                        message,
+                        category: "pipeline",
+                    },
+                ]),
+            };
+        }
+        outcome = await loadPipelineOutcome(pipelinePath, { cwd, projectRoot });
+    }
+    else {
+        pipelinePath = path.resolve(cwd, INLINE_PIPELINE_PATH);
+        outcome = await loadPipelineFromObjectOutcome(nameOrPath, { cwd, projectRoot });
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-            ok: false,
-            findings: findingsFromLoadIssues(cwd, path.resolve(cwd, nameOrPath), [
-                {
-                    code: "pipeline.load_error",
-                    message,
-                    category: "pipeline",
-                },
-            ]),
-        };
-    }
-    const outcome = await loadPipelineOutcome(pipelinePath, { cwd, projectRoot });
     const findings = [];
     if (!outcome.ok) {
         findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));