stageflow 0.13.0 → 0.16.0

package/dist/cli/runOutput.js

@@ -2,6 +2,21 @@ import { projectRun } from "../projection/projectRun.js";
 function stringify(payload) {
     return JSON.stringify(payload, null, 2);
 }
+function formatUsd(amount) {
+    return `$${amount.toFixed(4)}`;
+}
+/** Best-effort total cost for a run; undefined (not thrown) on any read failure or when no stage reported usage. */
+async function tryReadTotalCostUsd(store, runId) {
+    if (!store)
+        return undefined;
+    try {
+        const detail = await store.readRun(runId);
+        return detail.total_cost_usd;
+    }
+    catch {
+        return undefined;
+    }
+}
 function isBusyCode(code) {
     return code === "busy_capacity" || code === "busy_checkout";
 }
@@ -46,40 +61,53 @@ function formatStartFailureJson(started) {
     return formatRunStartFailedJson(started);
 }
 function baseRunCompletionPayload(result) {
-    if (result.outcome === "succeeded") {
-        return {
+    const payload = result.outcome === "succeeded"
+        ? {
             ok: true,
             outcome: "succeeded",
             runId: result.runId,
             runDir: result.runDir,
-        };
+        }
+        : result.outcome === "waiting"
+            ? {
+                ok: false,
+                outcome: "waiting",
+                runId: result.runId,
+                runDir: result.runDir,
+            }
+            : {
+                ok: false,
+                outcome: "failed",
+                runId: result.runId,
+                runDir: result.runDir,
+            };
+    if (result.outcome === "failed" && result.reason !== undefined) {
+        payload.reason = result.reason;
     }
-    if (result.outcome === "waiting") {
-        return {
-            ok: false,
-            outcome: "waiting",
-            runId: result.runId,
-            runDir: result.runDir,
-        };
+    if (Array.isArray(result.findings) && result.findings.length > 0) {
+        payload.findings = result.findings.map((finding) => ({
+            severity: finding.severity,
+            code: finding.code,
+            file: finding.path,
+            message: finding.message,
+            category: finding.category,
+        }));
     }
-    const payload = {
-        ok: false,
-        outcome: "failed",
-        runId: result.runId,
-        runDir: result.runDir,
-    };
-    if (result.reason !== undefined)
-        payload.reason = result.reason;
     return payload;
 }
-function formatRunCompletionJson(result) {
-    return stringify(baseRunCompletionPayload(result));
+async function formatRunCompletionJsonWithCost(result, store) {
+    const totalCostUsd = await tryReadTotalCostUsd(store, result.runId);
+    return stringify({
+        ...baseRunCompletionPayload(result),
+        ...(totalCostUsd !== undefined ? { total_cost_usd: totalCostUsd } : {}),
+    });
 }
 async function formatRunCompletionJsonWithStages(result, store) {
     const detail = await store.readRun(result.runId);
     const projection = projectRun(detail);
     return stringify({
         ...baseRunCompletionPayload(result),
+        ...(detail.total_cost_usd !== undefined ? { total_cost_usd: detail.total_cost_usd } : {}),
         stages: projection.stages,
     });
 }
@@ -93,18 +121,21 @@ function writeStartFailureHuman(started, io) {
         io.error(`conflictingCheckout: ${started.conflictingCheckout}`);
     }
 }
-function writeCompletionHuman(result, io) {
+function writeCompletionHuman(result, io, totalCostUsd) {
     switch (result.outcome) {
         case "waiting":
             io.error(`Pipeline waiting. Run folder: ${result.runDir} (${result.runId})`);
-            return;
+            break;
         case "failed":
             io.error(`Pipeline failed: ${result.reason}`);
             io.error(`Run folder: ${result.runDir}`);
-            return;
+            break;
         case "succeeded":
             io.log(`Pipeline succeeded. Run folder: ${result.runDir}`);
-            return;
+            break;
+    }
+    if (totalCostUsd !== undefined) {
+        io.error(`Cost: ${formatUsd(totalCostUsd)}`);
     }
 }
 function exitCodeForRunOutcome(outcome) {
@@ -143,11 +174,12 @@ export async function reportCliRun(event, options) {
             }
         }
         else {
-            options.io.log(formatRunCompletionJson(event.result));
+            options.io.log(await formatRunCompletionJsonWithCost(event.result, options.store));
         }
     }
     else {
-        writeCompletionHuman(event.result, options.io);
+        const totalCostUsd = await tryReadTotalCostUsd(options.store, event.result.runId);
+        writeCompletionHuman(event.result, options.io, totalCostUsd);
     }
     return exitCodeForRunOutcome(event.result.outcome);
 }

package/dist/cli/validateCommand.d.ts

@@ -6,6 +6,7 @@ export type ValidateCommandIo = {
 };
 export declare function runValidateCommand(args: string[], options?: {
     cwd?: string;
+    projectRoot?: string;
     io?: Partial<ValidateCommandIo>;
     validateCatalog?: (options: Parameters<typeof defaultValidateCatalog>[0]) => Promise<ValidationResult>;
 }): Promise<number>;

package/dist/cli/validateCommand.js

@@ -61,6 +61,7 @@ function parseValidateArgs(args) {
 }
 export async function runValidateCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
     const out = { ...defaultIo, ...options.io };
     const validateCatalogFn = options.validateCatalog ?? defaultValidateCatalog;
     try {
@@ -73,6 +74,7 @@ export async function runValidateCommand(args, options = {}) {
         const result = await validateCatalogFn({
             scope,
             cwd,
+            projectRoot,
             pipeline: parsed.pipeline,
             task: parsed.task,
             strict: parsed.strict,

package/dist/cli.js

@@ -14,6 +14,7 @@ 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 { MIGRATE_YAML_USAGE, runMigrateYamlCommand } from "./cli/migrateYamlCommand.js";
 import { createRunStore } from "./runstore/createStore.js";
 import { resolveStageflowContext } from "./project/resolveStageflowContext.js";
 import { exitForOutcome, runStageWorker } from "./runtime/stageWorker.js";
@@ -26,6 +27,7 @@ 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 validate [--pipeline <path>] [--task <path>] [--strict] [--json]
+  sf migrate-yaml [path] [--root <path>] [--write] [--json] [--force]
   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>]
@@ -64,6 +66,8 @@ ${RUN_USAGE}
 
 ${VALIDATE_USAGE}
 
+${MIGRATE_YAML_USAGE}
+
 ${ARTIFACT_USAGE}
 
 ${ENVELOPE_USAGE}
@@ -93,6 +97,7 @@ function parseArgs(argv) {
     const command = args[0];
     if (command === "providers" ||
         command === "validate" ||
+        command === "migrate-yaml" ||
         command === "run" ||
         command === "init" ||
         command === "artifact" ||
@@ -275,7 +280,16 @@ async function main(argv) {
             return runInitCommand(argv.slice(3), { cwd: ctx.invocationCwd });
         }
         if (parsed.command === "validate") {
-            return runValidateCommand(argv.slice(3), { cwd: ctx.invocationCwd });
+            return runValidateCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
+        if (parsed.command === "migrate-yaml") {
+            return runMigrateYamlCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
         }
         if (parsed.command === "run") {
             return runRunCommand(argv.slice(3), {

package/dist/config/browseCatalog.js

@@ -106,7 +106,7 @@ async function listModelsFromManifest(projectRoot, manifest) {
         try {
             const loaded = await loadPipeline(filePath, { cwd: projectRoot });
             for (const stage of loaded.stages) {
-                if (stage.model.trim()) {
+                if (stage.model?.trim()) {
                     models.add(stage.model);
                 }
             }

package/dist/config/createPipeline.d.ts

@@ -3,7 +3,7 @@ import type { StageGateKind } from "../types/stage.js";
 import type { PipelineListing } from "./listConfig.js";
 export type CreatePipelineStageInline = {
     system_prompt: string;
-    model: string;
+    model?: string;
     gate_kinds?: StageGateKind[];
 };
 export type CreatePipelineStageRef = {

package/dist/config/createPipeline.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parsePipelineNeeds } from "./pipelineNeeds.js";
 import { STAGE_ID_PATTERN } from "./createStage.js";
 import { inferIdFromUsesPath, normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
+import { parseModelField } from "./modelField.js";
 import { readYamlObject } from "./readYamlObject.js";
 import { resolvePipelineDagFromRefs } from "./resolvePipelineDag.js";
 import { validatePipeline } from "./validateCatalog.js";
@@ -36,7 +37,9 @@ function stageRefToRaw(ref) {
         raw.uses = ref.uses;
     if (ref.inline) {
         raw.system_prompt = ref.inline.system_prompt;
-        raw.model = ref.inline.model;
+        if (ref.inline.model !== undefined && ref.inline.model.length > 0) {
+            raw.model = ref.inline.model;
+        }
         if (ref.inline.gate_kinds !== undefined) {
             raw.gate_kinds = ref.inline.gate_kinds;
         }
@@ -61,7 +64,9 @@ function normalizedToCreateRefs(entries) {
             const raw = entry.body.raw;
             ref.inline = {
                 system_prompt: String(raw.system_prompt ?? ""),
-                model: String(raw.model ?? ""),
+                ...(typeof raw.model === "string" && raw.model.length > 0
+                    ? { model: raw.model }
+                    : {}),
                 ...(Array.isArray(raw.gate_kinds)
                     ? { gate_kinds: raw.gate_kinds }
                     : {}),
@@ -97,17 +102,22 @@ function parseInlineBody(entry, index) {
             error: `stages[${index}].system_prompt is required for inline stage`,
         };
     }
-    if (typeof entry.model !== "string" || entry.model.length === 0) {
-        return {
-            ok: false,
-            status: 400,
-            error: `stages[${index}].model is required for inline stage`,
-        };
-    }
     const inline = {
         system_prompt: entry.system_prompt,
-        model: entry.model,
     };
+    if (entry.model !== undefined) {
+        const modelField = parseModelField(entry.model);
+        if (!modelField.ok) {
+            return {
+                ok: false,
+                status: 400,
+                error: `stages[${index}].${modelField.message}`,
+            };
+        }
+        if (modelField.value !== undefined) {
+            inline.model = modelField.value;
+        }
+    }
     if (entry.gate_kinds !== undefined) {
         if (!Array.isArray(entry.gate_kinds)) {
             return {
@@ -288,7 +298,9 @@ export function pipelineConfigToYaml(pipeline, options) {
             else {
                 lines.push(`    system_prompt: ${formatInlineYamlScalar(stage.inline.system_prompt)}`);
             }
-            lines.push(`    model: ${formatInlineYamlScalar(stage.inline.model)}`);
+            if (stage.inline.model !== undefined && stage.inline.model.length > 0) {
+                lines.push(`    model: ${formatInlineYamlScalar(stage.inline.model)}`);
+            }
         }
         else if (stage.uses) {
             lines.push(`    uses: ${stage.uses}`);

package/dist/config/createStage.d.ts

@@ -5,7 +5,7 @@ export type CreateStageInput = {
     filename: string;
     id: string;
     system_prompt: string;
-    model: string;
+    model?: string;
     gate_kinds?: StageGateKind[];
 };
 export type CreatedStageListing = {

package/dist/config/createStage.js

@@ -2,6 +2,7 @@ import { access, mkdir, readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
 import { loadStage } from "./loadStage.js";
+import { parseModelField } from "./modelField.js";
 import { readYamlObject } from "./readYamlObject.js";
 export const STAGE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 function isGateKind(value) {
@@ -63,9 +64,11 @@ export function parseCreateStageBody(body) {
     if (typeof body.system_prompt !== "string" || body.system_prompt.length === 0) {
         return { ok: false, status: 400, error: "system_prompt is required" };
     }
-    if (typeof body.model !== "string" || body.model.length === 0) {
-        return { ok: false, status: 400, error: "model is required" };
+    const modelField = parseModelField(body.model);
+    if (!modelField.ok) {
+        return { ok: false, status: 400, error: modelField.message };
     }
+    const model = modelField.value;
     const gateKinds = parseGateKinds(body.gate_kinds);
     if (gateKinds === "invalid") {
         return {
@@ -79,7 +82,7 @@ export function parseCreateStageBody(body) {
         filename,
         id: body.id,
         system_prompt: body.system_prompt,
-        model: body.model,
+        ...(model !== undefined ? { model } : {}),
         ...(gateKinds !== undefined ? { gate_kinds: gateKinds } : {}),
     };
 }
@@ -116,7 +119,9 @@ export function stageConfigToYaml(stage) {
     else {
         lines.push(`system_prompt: ${formatInlineYamlScalar(stage.system_prompt)}`);
     }
-    lines.push(`model: ${formatInlineYamlScalar(stage.model)}`);
+    if (stage.model !== undefined && stage.model.length > 0) {
+        lines.push(`model: ${formatInlineYamlScalar(stage.model)}`);
+    }
     lines.push("");
     return lines.join("\n");
 }
@@ -190,7 +195,7 @@ export async function createStage(projectRoot, input) {
         await writeFile(filePath, stageConfigToYaml({
             id: input.id,
             system_prompt: input.system_prompt,
-            model: input.model,
+            ...(input.model !== undefined && input.model.length > 0 ? { model: input.model } : {}),
             ...(input.gate_kinds !== undefined ? { gate_kinds: input.gate_kinds } : {}),
         }), "utf8");
     }

package/dist/config/legacyYaml.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Dual-read adapter: accept old YAML authoring keys and warn (`catalog.legacy_yaml`).
+ *
+ * This is not the runtime IR. Stage workers, snapshots, emit, and VSE already
+ * use those same strings as TypeScript fields (`StageConfig.payload_schema`,
+ * DAG `completion` / `recovery`). Target YAML compiles onto that IR in
+ * `yamlDialect.ts`. New catalog fields go on `io` / `verify` / `on_verify_fail`,
+ * not here.
+ *
+ * Off: STAGEFLOW_LEGACY_YAML=0. migrate-yaml still reads legacy via
+ * withLegacyYamlAllowedAsync.
+ *
+ * Delete this file plus migrateYaml.ts, printTargetYaml.ts,
+ * migrateYamlCommand.ts, and tests/fixtures/dual-read to stop accepting
+ * payload_schema / pre_emit_checks / completion / recovery as authoring keys.
+ */
+import type { LoadIssue } from "./loadOutcome.js";
+import type { YamlDialect } from "./yamlDialect.js";
+export declare const LEGACY_CONTRACT_KEYS: Set<string>;
+export declare const LEGACY_KEY_REPLACEMENTS: Record<string, string>;
+export declare function formatLegacyReplacements(keys: string[]): string;
+export declare function presentLegacyKeys(keys: Iterable<string>): string[];
+export declare function legacyYamlIssue(fileLabel: string, keys: string[]): LoadIssue;
+export declare function dialectWarningForDocument(raw: Record<string, unknown>, fileLabel: string): LoadIssue | undefined;
+export declare function allowLegacyYamlAuthoring(): boolean;
+export declare function withLegacyYamlAllowed<T>(fn: () => T): T;
+export declare function withLegacyYamlAllowedAsync<T>(fn: () => Promise<T>): Promise<T>;
+export declare function legacyAuthoringRejected(dialect: YamlDialect, fileLabel: string, keys: string[]): LoadIssue | undefined;

package/dist/config/legacyYaml.js

@@ -0,0 +1,98 @@
+/**
+ * Dual-read adapter: accept old YAML authoring keys and warn (`catalog.legacy_yaml`).
+ *
+ * This is not the runtime IR. Stage workers, snapshots, emit, and VSE already
+ * use those same strings as TypeScript fields (`StageConfig.payload_schema`,
+ * DAG `completion` / `recovery`). Target YAML compiles onto that IR in
+ * `yamlDialect.ts`. New catalog fields go on `io` / `verify` / `on_verify_fail`,
+ * not here.
+ *
+ * Off: STAGEFLOW_LEGACY_YAML=0. migrate-yaml still reads legacy via
+ * withLegacyYamlAllowedAsync.
+ *
+ * Delete this file plus migrateYaml.ts, printTargetYaml.ts,
+ * migrateYamlCommand.ts, and tests/fixtures/dual-read to stop accepting
+ * payload_schema / pre_emit_checks / completion / recovery as authoring keys.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export const LEGACY_CONTRACT_KEYS = new Set([
+    "payload_schema",
+    "clone_input_schema",
+    "pre_emit_checks",
+    "completion",
+    "recovery",
+]);
+export const LEGACY_KEY_REPLACEMENTS = {
+    payload_schema: "io.output.schema",
+    clone_input_schema: "io.input.schema",
+    pre_emit_checks: "verify items with when including emit",
+    completion: "verify items with when including after",
+    recovery: "on_verify_fail",
+};
+const TARGET_AUTHORING_KEYS = new Set(["io", "verify", "on_verify_fail"]);
+const legacyYamlOverride = new AsyncLocalStorage();
+function collectDocumentKeys(raw) {
+    const keys = new Set(Object.keys(raw));
+    if (Array.isArray(raw.stages)) {
+        for (const entry of raw.stages) {
+            if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+                for (const key of Object.keys(entry))
+                    keys.add(key);
+            }
+        }
+    }
+    return keys;
+}
+export function formatLegacyReplacements(keys) {
+    return keys
+        .map((key) => {
+        const replacement = LEGACY_KEY_REPLACEMENTS[key];
+        return replacement ? `${key} → ${replacement}` : key;
+    })
+        .join(", ");
+}
+export function presentLegacyKeys(keys) {
+    const set = keys instanceof Set ? keys : new Set(keys);
+    return [...LEGACY_CONTRACT_KEYS].filter((key) => set.has(key));
+}
+export function legacyYamlIssue(fileLabel, keys) {
+    return {
+        code: "catalog.legacy_yaml",
+        message: `${fileLabel} uses legacy YAML keys (${formatLegacyReplacements(keys)})`,
+        category: "catalog",
+    };
+}
+export function dialectWarningForDocument(raw, fileLabel) {
+    const keys = collectDocumentKeys(raw);
+    const legacyKeys = presentLegacyKeys(keys);
+    if (legacyKeys.length === 0)
+        return undefined;
+    for (const key of keys) {
+        if (TARGET_AUTHORING_KEYS.has(key))
+            return undefined;
+    }
+    return legacyYamlIssue(fileLabel, legacyKeys);
+}
+export function allowLegacyYamlAuthoring() {
+    if (legacyYamlOverride.getStore() === true)
+        return true;
+    const raw = process.env.STAGEFLOW_LEGACY_YAML;
+    if (raw === "0" || raw === "false")
+        return false;
+    return true;
+}
+export function withLegacyYamlAllowed(fn) {
+    return legacyYamlOverride.run(true, fn);
+}
+export function withLegacyYamlAllowedAsync(fn) {
+    return legacyYamlOverride.run(true, fn);
+}
+export function legacyAuthoringRejected(dialect, fileLabel, keys) {
+    if (dialect !== "legacy" || allowLegacyYamlAuthoring())
+        return undefined;
+    return {
+        code: "catalog.legacy_yaml",
+        message: `${fileLabel}: dual-read is disabled (STAGEFLOW_LEGACY_YAML=0). Run sf migrate-yaml or author io / verify / on_verify_fail (${formatLegacyReplacements(keys)}).`,
+        category: "catalog",
+    };
+}

package/dist/config/loadOutcome.d.ts

@@ -23,9 +23,10 @@ export type LoadIssue = {
 export type LoadOutcome<T> = {
     ok: true;
     value: T;
+    issues?: LoadIssue[];
 } | {
     ok: false;
     issues: LoadIssue[];
 };
 export declare function loadFailure<T>(issues: LoadIssue[]): LoadOutcome<T>;
-export declare function loadSuccess<T>(value: T): LoadOutcome<T>;
+export declare function loadSuccess<T>(value: T, issues?: LoadIssue[]): LoadOutcome<T>;

package/dist/config/loadOutcome.js

@@ -1,6 +1,9 @@
 export function loadFailure(issues) {
     return { ok: false, issues };
 }
-export function loadSuccess(value) {
+export function loadSuccess(value, issues) {
+    if (issues && issues.length > 0) {
+        return { ok: true, value, issues };
+    }
     return { ok: true, value };
 }

package/dist/config/loadPipeline.d.ts

@@ -5,7 +5,9 @@ export type { LoadIssue, LoadOutcome } from "./loadOutcome.js";
 export declare function resolvePipelinePath(pipelinePath: string, cwd: string): Promise<string>;
 export declare function loadPipelineOutcome(nameOrPath: string, options?: {
     cwd?: string;
+    projectRoot?: string;
 }): Promise<LoadOutcome<LoadedPipeline>>;
 export declare function loadPipeline(nameOrPath: string, options?: {
     cwd?: string;
+    projectRoot?: string;
 }): Promise<LoadedPipeline>;