stageflow 0.12.0 → 0.15.0

package/dist/config/loadStage.js

@@ -1,10 +1,19 @@
 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 { compilePayloadSchema, UnresolvedSchemaRefError } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parseModelField } from "./modelField.js";
+import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { applyCompiledBody, classifyYamlDocument, compileTargetContract, dialectFromKeys, mixedDialectIssue, STAGE_FILE_WIRING_KEYS, } from "./yamlDialect.js";
+const afterCompletionByStage = new WeakMap();
+/** After-phase IR from target `verify` (`when` includes after). Stamped onto DAG `completion`. */
+export function afterCompletionForStage(stage) {
+    return afterCompletionByStage.get(stage);
+}
 function isGateKind(value) {
     return STAGE_GATE_KINDS.includes(value);
 }
@@ -91,13 +100,76 @@ function parseGateKinds(raw, label) {
     }
     return loadSuccess(kinds);
 }
-function parseStageFields(raw, label, entryId) {
-    if (typeof raw.system_prompt !== "string" ||
-        typeof raw.model !== "string") {
+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, deferSchemaRefs) {
+    // Reads IR field names. Target YAML must already be compiled via
+    // applyCompiledBody; legacy YAML uses these keys as authoring.
+    if (typeof raw.system_prompt !== "string") {
         return loadFailure([
             {
                 code: "stage.invalid_shape",
-                message: `Invalid stage ${label}: system_prompt and model are required strings`,
+                message: `Invalid stage ${label}: system_prompt is a required string`,
                 category: "stage",
                 stageId: entryId,
             },
@@ -106,8 +178,21 @@ function parseStageFields(raw, label, entryId) {
     const stage = {
         id: entryId,
         system_prompt: raw.system_prompt,
-        model: raw.model,
     };
+    const modelField = parseModelField(raw.model);
+    if (!modelField.ok) {
+        return loadFailure([
+            {
+                code: "stage.invalid_model",
+                message: `Invalid stage ${label}: ${modelField.message}`,
+                category: "stage",
+                stageId: entryId,
+            },
+        ]);
+    }
+    if (modelField.value !== undefined) {
+        stage.model = modelField.value;
+    }
     if (raw.payload_schema !== undefined) {
         if (raw.payload_schema === null ||
             typeof raw.payload_schema !== "object" ||
@@ -125,15 +210,29 @@ function parseStageFields(raw, label, entryId) {
             compilePayloadSchema(raw.payload_schema);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return loadFailure([
-                {
-                    code: "stage.invalid_payload_schema",
-                    message: `Invalid stage ${label}: invalid payload_schema: ${message}`,
-                    category: "stage",
-                    stageId: entryId,
-                },
-            ]);
+            if (err instanceof UnresolvedSchemaRefError) {
+                if (!deferSchemaRefs) {
+                    return loadFailure([
+                        {
+                            code: "stage.unresolved_schema_ref",
+                            message: `Invalid stage ${label}: ${err.message}`,
+                            category: "stage",
+                            stageId: entryId,
+                        },
+                    ]);
+                }
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                return loadFailure([
+                    {
+                        code: "stage.invalid_payload_schema",
+                        message: `Invalid stage ${label}: invalid payload_schema: ${message}`,
+                        category: "stage",
+                        stageId: entryId,
+                    },
+                ]);
+            }
         }
         stage.payload_schema = raw.payload_schema;
     }
@@ -154,15 +253,29 @@ function parseStageFields(raw, label, entryId) {
             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,
-                },
-            ]);
+            if (err instanceof UnresolvedSchemaRefError) {
+                if (!deferSchemaRefs) {
+                    return loadFailure([
+                        {
+                            code: "stage.unresolved_schema_ref",
+                            message: `Invalid stage ${label}: ${err.message}`,
+                            category: "stage",
+                            stageId: entryId,
+                        },
+                    ]);
+                }
+            }
+            else {
+                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;
     }
@@ -223,6 +336,12 @@ 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([
@@ -241,9 +360,28 @@ function parseStageFields(raw, label, entryId) {
 }
 export function loadStageFromObjectOutcome(raw, ctx) {
     const label = `${ctx.entryId} (${ctx.declaringPath})`;
-    return parseStageFields(raw, label, ctx.entryId);
+    const deferSchemaRefs = ctx.deferSchemaRefs === true;
+    const dialect = dialectFromKeys(Object.keys(raw));
+    if (dialect === "invalid") {
+        return loadFailure([mixedDialectIssue()]);
+    }
+    const rejected = legacyAuthoringRejected(dialect, label, presentLegacyKeys(Object.keys(raw)));
+    if (rejected)
+        return loadFailure([rejected]);
+    if (dialect === "target") {
+        const compiled = compileTargetContract(raw, {
+            stageId: ctx.entryId,
+            label,
+            category: "stage",
+            deferSchemaRefs,
+        });
+        if (!compiled.ok)
+            return compiled;
+        return parseStageFields(applyCompiledBody(raw, compiled.value), label, ctx.entryId, deferSchemaRefs);
+    }
+    return parseStageFields(raw, label, ctx.entryId, deferSchemaRefs);
 }
-export async function loadStageOutcome(filePath) {
+export async function loadStageOutcome(filePath, options = {}) {
     let raw;
     try {
         raw = await readYamlObject(filePath);
@@ -262,12 +400,47 @@ export async function loadStageOutcome(filePath) {
         return loadFailure([
             {
                 code: "stage.invalid_shape",
-                message: `Invalid stage file ${filePath}: id, system_prompt, and model are required strings`,
+                message: `Invalid stage file ${filePath}: id and system_prompt are required strings`,
                 category: "stage",
             },
         ]);
     }
-    const outcome = parseStageFields(raw, `file ${filePath}`, raw.id);
+    const dialect = classifyYamlDocument(raw);
+    if (dialect === "invalid") {
+        return loadFailure([mixedDialectIssue()]);
+    }
+    const rejected = legacyAuthoringRejected(dialect, filePath, presentLegacyKeys(Object.keys(raw)));
+    if (rejected)
+        return loadFailure([rejected]);
+    if (dialect === "target") {
+        const wiring = STAGE_FILE_WIRING_KEYS.find((key) => raw[key] !== undefined);
+        if (wiring) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_shape",
+                    message: `Invalid stage file ${filePath}: new-dialect stage files must not declare wiring key "${wiring}"`,
+                    category: "stage",
+                    stageId: raw.id,
+                },
+            ]);
+        }
+    }
+    let parseRaw = raw;
+    let afterCompletion;
+    const deferSchemaRefs = options.deferSchemaRefs === true;
+    if (dialect === "target") {
+        const compiled = compileTargetContract(raw, {
+            stageId: raw.id,
+            label: `file ${filePath}`,
+            category: "stage",
+            deferSchemaRefs,
+        });
+        if (!compiled.ok)
+            return compiled;
+        parseRaw = applyCompiledBody(raw, compiled.value);
+        afterCompletion = compiled.value.completion;
+    }
+    const outcome = parseStageFields(parseRaw, `file ${filePath}`, raw.id, deferSchemaRefs);
     if (!outcome.ok)
         return outcome;
     if (outcome.value.id !== raw.id) {
@@ -280,7 +453,12 @@ export async function loadStageOutcome(filePath) {
             },
         ]);
     }
-    return outcome;
+    if (afterCompletion)
+        afterCompletionByStage.set(outcome.value, afterCompletion);
+    const warning = allowLegacyYamlAuthoring()
+        ? dialectWarningForDocument(raw, filePath)
+        : undefined;
+    return loadSuccess(outcome.value, warning ? [warning] : undefined);
 }
 export async function loadStage(filePath) {
     const outcome = await loadStageOutcome(filePath);

package/dist/config/loadStageflowManifest.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parseModelField } from "./modelField.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
 export function manifestPathForProject(projectRoot) {
@@ -117,6 +118,14 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
     else {
         agent = agentField.value;
     }
+    let model;
+    const modelField = parseModelField(record.model);
+    if (!modelField.ok) {
+        issues.push(catalogIssue("catalog.manifest_invalid", modelField.message));
+    }
+    else {
+        model = modelField.value;
+    }
     if (issues.length > 0) {
         return loadFailure(issues);
     }
@@ -140,6 +149,7 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
         version: 1,
         catalog,
         ...(agent !== undefined ? { agent } : {}),
+        ...(model !== undefined ? { model } : {}),
     };
     return loadSuccess({
         path: manifestPath,

package/dist/config/loadTask.js

@@ -1,6 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 export function parseTaskFile(raw, source = "task") {
     const record = raw;
     if (typeof record?.id !== "string" || typeof record?.goal !== "string") {
@@ -13,12 +16,23 @@ export function parseTaskFile(raw, source = "task") {
             },
         ]);
     }
+    if (record.input !== undefined && !isPlainObject(record.input)) {
+        return loadFailure([
+            {
+                code: "task.invalid_shape",
+                message: `Invalid ${source}: input must be an object`,
+                category: "task",
+                taskId: record.id,
+            },
+        ]);
+    }
     return loadSuccess({
         id: record.id,
         goal: record.goal,
         context: typeof record.context === "string" ? record.context : undefined,
         constraints: typeof record.constraints === "string" ? record.constraints : undefined,
         checkout: typeof record.checkout === "string" ? record.checkout : undefined,
+        ...(record.input !== undefined ? { input: record.input } : {}),
     });
 }
 export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {

package/dist/config/materializeStageModels.d.ts

@@ -0,0 +1,7 @@
+import type { LoadedStageConfig, StageConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export declare function materializeStageModels(stages: StageConfig[], options: {
+    pipelineModel?: string;
+    pipelineId: string;
+    projectRoot: string;
+}): Promise<LoadOutcome<LoadedStageConfig[]>>;

package/dist/config/materializeStageModels.js

@@ -0,0 +1,35 @@
+import { access } from "node:fs/promises";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { loadStageflowManifestOutcome, manifestPathForProject, } from "./loadStageflowManifest.js";
+import { globalModelFromManifest, resolveModelOutcome } from "./resolveModel.js";
+export async function materializeStageModels(stages, options) {
+    let globalModel;
+    const manifestPath = manifestPathForProject(options.projectRoot);
+    let manifestExists = true;
+    try {
+        await access(manifestPath);
+    }
+    catch {
+        manifestExists = false;
+    }
+    if (manifestExists) {
+        const manifestOutcome = await loadStageflowManifestOutcome(options.projectRoot);
+        if (!manifestOutcome.ok) {
+            return loadFailure(manifestOutcome.issues);
+        }
+        globalModel = globalModelFromManifest(manifestOutcome.value);
+    }
+    const materialized = [];
+    for (const stage of stages) {
+        const modelOutcome = resolveModelOutcome({
+            stage: stage.model,
+            pipeline: options.pipelineModel,
+            global: globalModel,
+        }, { stageId: stage.id, pipelineId: options.pipelineId });
+        if (!modelOutcome.ok) {
+            return loadFailure(modelOutcome.issues);
+        }
+        materialized.push({ ...stage, model: modelOutcome.value });
+    }
+    return loadSuccess(materialized);
+}

package/dist/config/mergePipelineIncludes.d.ts

@@ -1,4 +1,5 @@
-import { type LoadOutcome } from "./loadOutcome.js";
+import type { PayloadSchemaMap } from "../envelope/payloadSchema.js";
+import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
 export type RawMergedEntry = {
     raw: unknown;
     declaringPath: string;
@@ -7,4 +8,7 @@ export declare function mergePipelineStages(rootPath: string): Promise<LoadOutco
     entries: RawMergedEntry[];
     pipelineId: string;
     agent?: string;
+    model?: string;
+    schemas?: PayloadSchemaMap;
+    warnings: LoadIssue[];
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -1,7 +1,10 @@
 import path from "node:path";
 import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
+import { parseModelField } from "./modelField.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { classifyYamlDocument, collectDocumentKeys, mixedDialectIssue, } from "./yamlDialect.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -12,7 +15,7 @@ function formatIncludeCycle(stack, nextPath) {
     const chain = [...stack, nextPath].map((p) => path.basename(p));
     return chain.join(" → ");
 }
-async function visitPipelineFile(filePath, stack, idLocations, entries) {
+async function visitPipelineFile(filePath, stack, idLocations, entries, warnings) {
     const absPath = normalizePath(filePath);
     if (stack.some((p) => normalizePath(p) === absPath)) {
         const cycleChain = formatIncludeCycle(stack, absPath);
@@ -38,6 +41,28 @@ async function visitPipelineFile(filePath, stack, idLocations, entries) {
             },
         ]);
     }
+    const dialect = classifyYamlDocument(raw);
+    if (dialect === "invalid") {
+        return loadFailure([mixedDialectIssue()]);
+    }
+    const rejected = legacyAuthoringRejected(dialect, absPath, presentLegacyKeys(collectDocumentKeys(raw)));
+    if (rejected)
+        return loadFailure([rejected]);
+    if (allowLegacyYamlAuthoring()) {
+        const warning = dialectWarningForDocument(raw, absPath);
+        if (warning)
+            warnings.push(warning);
+    }
+    const isFragment = stack.length > 0;
+    if (isFragment && raw.schemas !== undefined) {
+        return loadFailure([
+            {
+                code: "pipeline.include_invalid",
+                message: `Invalid include in ${absPath}: schemas is only allowed on the pipeline file, not on include fragments`,
+                category: "pipeline",
+            },
+        ]);
+    }
     const nextStack = [...stack, absPath];
     if (raw.include !== undefined) {
         if (!Array.isArray(raw.include)) {
@@ -61,7 +86,7 @@ async function visitPipelineFile(filePath, stack, idLocations, entries) {
                 ]);
             }
             const includePath = normalizePath(path.resolve(path.dirname(absPath), item.local));
-            const includeResult = await visitPipelineFile(includePath, nextStack, idLocations, entries);
+            const includeResult = await visitPipelineFile(includePath, nextStack, idLocations, entries, warnings);
             if (!includeResult.ok)
                 return includeResult;
         }
@@ -136,9 +161,26 @@ export async function mergePipelineStages(rootPath) {
         ]);
     }
     const agent = agentField.value;
+    const modelField = parseModelField(raw.model);
+    if (!modelField.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_model",
+                message: `Invalid pipeline ${absRoot}: ${modelField.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const model = modelField.value;
+    const schemasOutcome = parsePipelineSchemas(raw.schemas, absRoot, pipelineId);
+    if (!schemasOutcome.ok)
+        return schemasOutcome;
+    const schemas = schemasOutcome.value;
     const idLocations = new Map();
     const entries = [];
-    const mergeResult = await visitPipelineFile(absRoot, [], idLocations, entries);
+    const warnings = [];
+    const mergeResult = await visitPipelineFile(absRoot, [], idLocations, entries, warnings);
     if (!mergeResult.ok)
         return mergeResult;
     if (entries.length === 0) {
@@ -150,5 +192,41 @@ export async function mergePipelineStages(rootPath) {
             },
         ]);
     }
-    return loadSuccess({ entries, pipelineId, ...(agent !== undefined ? { agent } : {}) });
+    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);
+    if (!isPlainObject(raw)) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_shape",
+                message: `Invalid pipeline ${absPath}: schemas must be an object`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const schemas = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            return loadFailure([
+                {
+                    code: "pipeline.invalid_shape",
+                    message: `Invalid pipeline ${absPath}: schemas.${name} must be an object`,
+                    category: "pipeline",
+                    pipelineId,
+                },
+            ]);
+        }
+        schemas[name] = value;
+    }
+    return loadSuccess(schemas);
 }

package/dist/config/migrateYaml.d.ts

@@ -0,0 +1,19 @@
+export type MigrateYamlWrite = {
+    file: string;
+    absPath: string;
+    content: string;
+};
+export type MigrateYamlPlan = {
+    writes: MigrateYamlWrite[];
+    skipped: string[];
+    errors: string[];
+};
+export declare function catalogKind(raw: Record<string, unknown>, filePath: string): "pipeline" | "stage" | "task" | "unknown";
+export declare function fileDirtyVsHead(absPath: string): boolean;
+export declare function planMigrateYaml(targetPath: string, options?: {
+    cwd: string;
+    projectRoot?: string;
+}): Promise<MigrateYamlPlan>;
+export declare function applyMigrateYamlPlan(plan: MigrateYamlPlan, testOnly?: {
+    beforeRename?: () => Promise<void>;
+}): Promise<void>;