stageflow 0.9.0 → 0.13.0

package/dist/config/loadStage.js

@@ -1,10 +1,70 @@
+import { parseAgentField } from "../agent/agentBackend.js";
+import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
+import { CLONE_ACTIONS } from "../types/forkChoice.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
 import { compilePayloadSchema } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
 function isGateKind(value) {
     return STAGE_GATE_KINDS.includes(value);
 }
+function isCloneAction(value) {
+    return CLONE_ACTIONS.includes(value);
+}
+function parseCloneActions(raw, label) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw) || !raw.every((item) => typeof item === "string")) {
+        return loadFailure([
+            {
+                code: "stage.invalid_clone_actions",
+                message: `Invalid stage ${label}: clone_actions must be a non-empty array of strings`,
+                category: "stage",
+            },
+        ]);
+    }
+    if (raw.length === 0) {
+        return loadFailure([
+            {
+                code: "stage.invalid_clone_actions",
+                message: `Invalid stage ${label}: clone_actions must not be empty`,
+                category: "stage",
+            },
+        ]);
+    }
+    const actions = [];
+    for (const item of raw) {
+        if (!isCloneAction(item)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_clone_actions",
+                    message: `Invalid stage ${label}: unsupported clone_actions value "${item}" (allowed: ${CLONE_ACTIONS.join(", ")})`,
+                    category: "stage",
+                },
+            ]);
+        }
+        actions.push(item);
+    }
+    return loadSuccess(actions);
+}
+function parseTimeoutMs(raw, label) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (typeof raw !== "number" ||
+        !Number.isFinite(raw) ||
+        !Number.isInteger(raw) ||
+        raw <= 0) {
+        return loadFailure([
+            {
+                code: "stage.invalid_timeout_ms",
+                message: `Invalid stage ${label}: timeout_ms must be a positive integer (milliseconds)`,
+                category: "stage",
+            },
+        ]);
+    }
+    return loadSuccess(raw);
+}
 function parseGateKinds(raw, label) {
     if (raw === undefined)
         return loadSuccess(undefined);
@@ -30,7 +90,69 @@ function parseGateKinds(raw, label) {
         }
         kinds.push(item);
     }
-    return loadSuccess(kinds.length > 0 ? kinds : undefined);
+    return loadSuccess(kinds);
+}
+export function parseStageMcp(raw, label, stageId) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw)) {
+        return loadFailure([
+            {
+                code: "stage.invalid_mcp",
+                message: `Invalid stage ${label}: mcp must be an array of server names`,
+                category: "stage",
+                stageId,
+            },
+        ]);
+    }
+    const names = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (typeof item !== "string") {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp entries must be strings`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        const name = item.trim();
+        if (name === "") {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp entries must be non-empty strings`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        if (name === STAGEFLOW_MCP_SERVER_NAME) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp must not include reserved name "${STAGEFLOW_MCP_SERVER_NAME}"`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        if (seen.has(name)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp contains duplicate name "${name}"`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        seen.add(name);
+        names.push(name);
+    }
+    return loadSuccess(names);
 }
 function parseStageFields(raw, label, entryId) {
     if (typeof raw.system_prompt !== "string" ||
@@ -78,6 +200,46 @@ function parseStageFields(raw, label, entryId) {
         }
         stage.payload_schema = raw.payload_schema;
     }
+    if (raw.clone_input_schema !== undefined) {
+        if (raw.clone_input_schema === null ||
+            typeof raw.clone_input_schema !== "object" ||
+            Array.isArray(raw.clone_input_schema)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_clone_input_schema",
+                    message: `Invalid stage ${label}: clone_input_schema must be an object`,
+                    category: "stage",
+                    stageId: entryId,
+                },
+            ]);
+        }
+        try {
+            compilePayloadSchema(raw.clone_input_schema);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return loadFailure([
+                {
+                    code: "stage.invalid_clone_input_schema",
+                    message: `Invalid stage ${label}: invalid clone_input_schema: ${message}`,
+                    category: "stage",
+                    stageId: entryId,
+                },
+            ]);
+        }
+        stage.clone_input_schema = raw.clone_input_schema;
+    }
+    const cloneActionsOutcome = parseCloneActions(raw.clone_actions, label);
+    if (!cloneActionsOutcome.ok) {
+        const issues = cloneActionsOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: entryId,
+        }));
+        return loadFailure(issues);
+    }
+    if (cloneActionsOutcome.value !== undefined) {
+        stage.clone_actions = cloneActionsOutcome.value;
+    }
     const gateKindsOutcome = parseGateKinds(raw.gate_kinds, label);
     if (!gateKindsOutcome.ok) {
         const issues = gateKindsOutcome.issues.map((issue) => ({
@@ -86,8 +248,31 @@ function parseStageFields(raw, label, entryId) {
         }));
         return loadFailure(issues);
     }
-    if (gateKindsOutcome.value)
+    if (gateKindsOutcome.value !== undefined) {
         stage.gate_kinds = gateKindsOutcome.value;
+    }
+    const timeoutMsOutcome = parseTimeoutMs(raw.timeout_ms, label);
+    if (!timeoutMsOutcome.ok) {
+        const issues = timeoutMsOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: entryId,
+        }));
+        return loadFailure(issues);
+    }
+    if (timeoutMsOutcome.value !== undefined) {
+        stage.timeout_ms = timeoutMsOutcome.value;
+    }
+    const preEmitChecksOutcome = parsePreEmitChecks(raw.pre_emit_checks, label);
+    if (!preEmitChecksOutcome.ok) {
+        const issues = preEmitChecksOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: entryId,
+        }));
+        return loadFailure(issues);
+    }
+    if (preEmitChecksOutcome.value !== undefined) {
+        stage.pre_emit_checks = preEmitChecksOutcome.value;
+    }
     if (raw.skill !== undefined) {
         if (typeof raw.skill !== "string" || raw.skill.trim() === "") {
             return loadFailure([
@@ -101,6 +286,26 @@ function parseStageFields(raw, label, entryId) {
         }
         stage.skill = raw.skill.trim();
     }
+    const mcpOutcome = parseStageMcp(raw.mcp, label, entryId);
+    if (!mcpOutcome.ok)
+        return mcpOutcome;
+    if (mcpOutcome.value !== undefined) {
+        stage.mcp = mcpOutcome.value;
+    }
+    const agentField = parseAgentField(raw.agent);
+    if (!agentField.ok) {
+        return loadFailure([
+            {
+                code: "stage.invalid_agent",
+                message: `Invalid stage ${label}: ${agentField.message}`,
+                category: "stage",
+                stageId: entryId,
+            },
+        ]);
+    }
+    if (agentField.value !== undefined) {
+        stage.agent = agentField.value;
+    }
     return loadSuccess(stage);
 }
 export function loadStageFromObjectOutcome(raw, ctx) {

package/dist/config/loadStageflowManifest.js

@@ -1,6 +1,7 @@
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
@@ -108,6 +109,14 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
         }
     }
     const patterns = parsePatterns(catalogRecord.patterns, issues);
+    let agent;
+    const agentField = parseAgentField(record.agent);
+    if (!agentField.ok) {
+        issues.push(catalogIssue("catalog.manifest_invalid", agentField.message));
+    }
+    else {
+        agent = agentField.value;
+    }
     if (issues.length > 0) {
         return loadFailure(issues);
     }
@@ -127,7 +136,11 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
             catalog.patterns.task = patterns.task;
         }
     }
-    const manifest = { version: 1, catalog };
+    const manifest = {
+        version: 1,
+        catalog,
+        ...(agent !== undefined ? { agent } : {}),
+    };
     return loadSuccess({
         path: manifestPath,
         projectRoot,

package/dist/config/mergePipelineIncludes.d.ts

@@ -6,4 +6,5 @@ export type RawMergedEntry = {
 export declare function mergePipelineStages(rootPath: string): Promise<LoadOutcome<{
     entries: RawMergedEntry[];
     pipelineId: string;
+    agent?: string;
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { readYamlObject } from "./readYamlObject.js";
 function isPlainObject(value) {
@@ -123,6 +124,18 @@ export async function mergePipelineStages(rootPath) {
         ]);
     }
     const pipelineId = raw.id;
+    const agentField = parseAgentField(raw.agent);
+    if (!agentField.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_agent",
+                message: `Invalid pipeline ${absRoot}: ${agentField.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const agent = agentField.value;
     const idLocations = new Map();
     const entries = [];
     const mergeResult = await visitPipelineFile(absRoot, [], idLocations, entries);
@@ -137,5 +150,5 @@ export async function mergePipelineStages(rootPath) {
             },
         ]);
     }
-    return loadSuccess({ entries, pipelineId });
+    return loadSuccess({ entries, pipelineId, ...(agent !== undefined ? { agent } : {}) });
 }

package/dist/config/normalizePipelineStageEntry.d.ts

@@ -1,4 +1,5 @@
-import type { NormalizedPipelineStageEntry } from "../types/pipeline.js";
+import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
+import type { NormalizedPipelineStageEntry, PipelineNeeds } from "../types/pipeline.js";
 import { type LoadOutcome } from "./loadOutcome.js";
 import type { RawMergedEntry } from "./mergePipelineIncludes.js";
 export declare function inferIdFromUsesPath(usesPath: string): string | null;
@@ -8,11 +9,15 @@ export declare function normalizePipelineStageEntries(rawEntries: RawMergedEntry
 }): LoadOutcome<NormalizedPipelineStageEntry[]>;
 export declare function toWiringRefs(entries: NormalizedPipelineStageEntry[]): Array<{
     id: string;
-    needs?: string;
+    needs?: PipelineNeeds;
     fork?: {
         select: "one" | "subset";
         allow_none?: boolean;
     };
     clonable?: boolean;
     clone_cap?: number;
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+    feedback_loop?: NormalizedPipelineStageEntry["feedback_loop"];
+    replay_safe?: boolean;
 }>;

package/dist/config/normalizePipelineStageEntry.js

@@ -1,6 +1,10 @@
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parseStageMcp } from "./loadStage.js";
 import { BODY_KEYS, isAllowedPipelineStageEntryKey, } from "./pipelineStageKeys.js";
+import { parseExecutionPolicy } from "./parseCompletionContract.js";
+import { parsePipelineNeeds } from "./pipelineNeeds.js";
+import { parseFeedbackLoopConfig } from "./resolvePipelineDag.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -28,7 +32,7 @@ function extractBodyRaw(raw) {
     return body;
 }
 function hasBodyKey(raw) {
-    return Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill");
+    return Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill" && key !== "mcp");
 }
 function readSkill(raw) {
     if (raw.skill === undefined)
@@ -93,6 +97,10 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             return skillOutcome;
         }
         const skill = skillOutcome?.ok ? skillOutcome.value : undefined;
+        const mcpOutcome = parseStageMcp(raw.mcp, `entry at index ${index} in ${declaringPath}`);
+        if (!mcpOutcome.ok)
+            return mcpOutcome;
+        const mcp = mcpOutcome.value;
         if (uses && hasBody) {
             return loadFailure([
                 {
@@ -130,27 +138,49 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 },
             ]);
         }
-        if (raw.needs !== undefined) {
-            if (Array.isArray(raw.needs)) {
+        const policyOutcome = parseExecutionPolicy(raw, id);
+        if (!policyOutcome.ok)
+            return policyOutcome;
+        let needs;
+        let feedbackLoop;
+        if (raw.feedback_loop !== undefined) {
+            try {
+                feedbackLoop = parseFeedbackLoopConfig(raw.feedback_loop, id, ctx);
+            }
+            catch (err) {
                 return loadFailure([
                     {
                         code: "pipeline.dag_error",
-                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": needs must be a string, not an array`,
+                        message: err instanceof Error ? err.message : String(err),
                         category: "pipeline",
                         pipelineId: ctx.pipelineId,
                     },
                 ]);
             }
-            if (typeof raw.needs !== "string" || !raw.needs) {
+        }
+        if (raw.replay_safe !== undefined && typeof raw.replay_safe !== "boolean") {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": replay_safe must be a boolean`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.needs !== undefined) {
+            const parsedNeeds = parsePipelineNeeds(raw.needs, id);
+            if (!parsedNeeds.ok) {
                 return loadFailure([
                     {
                         code: "pipeline.dag_error",
-                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": needs must be a non-empty string`,
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): ${parsedNeeds.message}`,
                         category: "pipeline",
                         pipelineId: ctx.pipelineId,
                     },
                 ]);
             }
+            needs = parsedNeeds.value;
         }
         let forkValue;
         if (raw.fork !== undefined) {
@@ -178,11 +208,24 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             id,
             declaringPath,
             body,
-            ...(typeof raw.needs === "string" ? { needs: raw.needs } : {}),
+            ...(needs !== undefined ? { needs } : {}),
             ...(forkValue !== undefined ? { fork: forkValue } : {}),
             ...(raw.clonable !== undefined ? { clonable: raw.clonable } : {}),
             ...(raw.clone_cap !== undefined ? { clone_cap: raw.clone_cap } : {}),
+            ...(policyOutcome.value.completion !== undefined
+                ? { completion: policyOutcome.value.completion }
+                : {}),
+            ...(policyOutcome.value.recovery !== undefined
+                ? { recovery: policyOutcome.value.recovery }
+                : {}),
+            ...(feedbackLoop !== undefined
+                ? { feedback_loop: feedbackLoop }
+                : {}),
+            ...(raw.replay_safe !== undefined
+                ? { replay_safe: raw.replay_safe }
+                : {}),
             ...(skill !== undefined ? { skill } : {}),
+            ...(mcp !== undefined ? { mcp } : {}),
         };
         const priorPath = normalized.find((e) => e.id === id)?.declaringPath;
         if (priorPath) {
@@ -206,5 +249,11 @@ export function toWiringRefs(entries) {
         ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
         ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
         ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
+        ...(entry.completion !== undefined ? { completion: entry.completion } : {}),
+        ...(entry.recovery !== undefined ? { recovery: entry.recovery } : {}),
+        ...(entry.feedback_loop !== undefined
+            ? { feedback_loop: entry.feedback_loop }
+            : {}),
+        ...(entry.replay_safe !== undefined ? { replay_safe: entry.replay_safe } : {}),
     }));
 }

package/dist/config/parseCompletionContract.d.ts

@@ -0,0 +1,8 @@
+import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+type ExecutionPolicy = {
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+};
+export declare function parseExecutionPolicy(raw: Record<string, unknown>, stageId: string): LoadOutcome<ExecutionPolicy>;
+export {};