stageflow 0.13.0 → 0.16.0

package/dist/runtime/completionCheckRunner.d.ts

@@ -131,7 +131,8 @@ export type CompletionVerificationResult = {
 /** Default Node implementation; callers may substitute a sandboxed executor. */
 export declare const nodeCommandExecutor: CommandExecutor;
 /**
- * Run every completion check in declaration order. A failed check never throws
- * or prevents later checks from producing their own repair evidence.
+ * Run every after-phase IR check in declaration order. YAML: `verify` when after.
+ * A failed check never throws or prevents later checks from producing their own
+ * repair evidence.
  */
 export declare function runCompletionContract(input: CompletionCheckRunnerInput): Promise<CompletionVerificationResult>;

package/dist/runtime/completionCheckRunner.js

@@ -343,8 +343,9 @@ async function runCheck(check, input) {
     }
 }
 /**
- * Run every completion check in declaration order. A failed check never throws
- * or prevents later checks from producing their own repair evidence.
+ * Run every after-phase IR check in declaration order. YAML: `verify` when after.
+ * A failed check never throws or prevents later checks from producing their own
+ * repair evidence.
  */
 export async function runCompletionContract(input) {
     const checks = [];

package/dist/runtime/envelopeRouting.d.ts

@@ -1,9 +1,9 @@
 import type { RunStore, StageSnapshot } from "../runstore/port.js";
 import type { StageEnvelope, TerminalEnvelope } from "../types/envelope.js";
 import type { LoadedPipeline, ResolvedPipelineDag } from "../types/pipeline.js";
-import type { StageConfig } from "../types/stage.js";
+import type { LoadedStageConfig } from "../types/stage.js";
 export declare function buildCompletedEnvelopesFromRun(store: RunStore, runId: string, stages?: StageSnapshot[], dag?: ResolvedPipelineDag): Promise<Map<string, StageEnvelope>>;
-export declare function buildStageConfigById(loaded: LoadedPipeline): Map<string, StageConfig>;
+export declare function buildStageConfigById(loaded: LoadedPipeline): Map<string, LoadedStageConfig>;
 export type ResolvePriorEnvelopeResult = {
     ok: true;
     prior: StageEnvelope | null;

package/dist/runtime/pipelineRunner.d.ts

@@ -1,4 +1,5 @@
 import type { AgentPort } from "../agent/port.js";
+import { type ValidationFinding } from "../config/validateCatalog.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { StageHitlController } from "./stageHitl.js";
@@ -15,6 +16,7 @@ export type PipelineRunResult = {
     runDir: string;
     runId: string;
     reason?: string;
+    findings?: ValidationFinding[];
 };
 export type StartedPipeline = {
     runId: string;
@@ -38,6 +40,7 @@ export type PreparedPipeline = {
     stageProcessLauncher?: StageProcessLauncher;
     operatorCatalog?: OperatorCatalog;
     skipGates?: boolean;
+    findings?: ValidationFinding[];
 };
 export type ExecuteStagesOptions = {
     maxActiveStagesPerRun?: number;

package/dist/runtime/pipelineRunner.js

@@ -1,8 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { loadPipelineValidated } from "../config/validateCatalog.js";
+import { buildValidationResult, loadPipelineValidated, } from "../config/validateCatalog.js";
 import { loadTaskFromYaml } from "../config/loadTask.js";
-import { buildValidationResult } from "../config/validateCatalog.js";
 import { resolveAndValidateCheckout } from "./stageRoots.js";
 import { buildPipelineDagSnapshotFromLoaded } from "../runstore/pipelineDagSnapshot.js";
 import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
@@ -10,6 +9,7 @@ import { runPipelineDag } from "./pipelineScheduler.js";
 import { readMaxActiveStagesPerRun, readStageExecutionMode, } from "./stageConcurrency.js";
 import { StageProcessLauncher } from "./stageProcessLauncher.js";
 import { PipelineValidationError } from "./pipelineValidationError.js";
+import { checkTaskEntryInput } from "./taskInput.js";
 export { PipelineValidationError } from "./pipelineValidationError.js";
 let defaultStageProcessLauncher;
 function resolveStageProcessLauncher(executionMode, override) {
@@ -27,6 +27,7 @@ function resolveStageProcessLauncher(executionMode, override) {
 async function preparePipeline(options) {
     const loadResult = await loadPipelineValidated(options.pipeline, {
         cwd: options.cwd,
+        projectRoot: options.projectRoot ?? options.cwd,
         validateStages: true,
     });
     if (!loadResult.ok) {
@@ -41,6 +42,20 @@ async function preparePipeline(options) {
             })());
     const label = options.taskPath ?? "task.yaml";
     const task = loadTaskFromYaml(taskYaml, `task file ${label}`);
+    const pairing = checkTaskEntryInput(task, loaded, {
+        cwd: options.cwd,
+        taskPath: options.taskPath,
+    });
+    if (pairing.some((finding) => finding.severity === "error")) {
+        throw new PipelineValidationError(buildValidationResult("pipeline", pairing, false));
+    }
+    const warningFindings = [
+        ...loadResult.findings.filter((finding) => finding.severity === "warning"),
+        ...pairing.filter((finding) => finding.severity === "warning"),
+    ];
+    for (const finding of warningFindings) {
+        console.error(`${finding.code}: ${finding.message}`);
+    }
     const checkoutRoot = await resolveAndValidateCheckout(task, options.checkoutOverride, options.cwd);
     const pipelinePath = normalizeCatalogPath(loaded.pipelinePath);
     const taskPath = options.taskPath
@@ -76,6 +91,7 @@ async function preparePipeline(options) {
         stageProcessLauncher,
         operatorCatalog: options.operatorCatalog,
         skipGates: options.skipGates,
+        ...(warningFindings.length > 0 ? { findings: warningFindings } : {}),
     };
 }
 export async function executeStages(prepared, options) {
@@ -84,7 +100,7 @@ export async function executeStages(prepared, options) {
         prepared.executionMode ??
         readStageExecutionMode(process.env);
     const stageProcessLauncher = resolveStageProcessLauncher(executionMode, options?.stageProcessLauncher ?? prepared.stageProcessLauncher);
-    return runPipelineDag({
+    const result = await runPipelineDag({
         prepared,
         maxActiveStagesPerRun,
         resumeFromStageId: options?.resumeFromStageId,
@@ -93,6 +109,10 @@ export async function executeStages(prepared, options) {
         executionMode,
         stageProcessLauncher,
     });
+    if (prepared.findings !== undefined && prepared.findings.length > 0) {
+        return { ...result, findings: prepared.findings };
+    }
+    return result;
 }
 export async function runPipeline(options) {
     const cwd = options.cwd ?? process.cwd();

package/dist/runtime/runManager.js

@@ -383,7 +383,7 @@ export class RunManager {
             gitSha: input.gitSha,
             ciPrUrl: input.ciPrUrl,
             ciJobUrl: input.ciJobUrl,
-        });
+        }, undefined, resolved.kind === "path" ? resolved.taskPath : undefined);
     }
     async rerun(runId) {
         const cwd = this.options.cwd ?? process.cwd();
@@ -1061,7 +1061,7 @@ export class RunManager {
             this.attachedWaiting.delete(`${runId}\0${stageId}`);
         }
     }
-    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot) {
+    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath) {
         let checkoutKey;
         try {
             const task = loadTaskFromYaml(taskYaml, taskLabel);
@@ -1086,6 +1086,7 @@ export class RunManager {
                 agent: this.options.agent,
                 store: this.options.store,
                 taskYaml,
+                taskPath,
                 pipeline,
                 cwd,
                 projectRoot: projectRoot ?? this.projectRoot,

package/dist/runtime/stageAttemptBootstrap.d.ts

@@ -2,7 +2,7 @@ import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunInput, StageS
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
-import type { StageConfig } from "../types/stage.js";
+import type { LoadedStageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
 import { type StageAttemptContext } from "./stageAttemptContext.js";
 import { type StageRoots } from "./stageRoots.js";
@@ -14,7 +14,7 @@ export type StageAttemptOpenInput = {
     agent: Pick<AgentPort, "openStage">;
     store: RunStore;
     runId: string;
-    stage: StageConfig;
+    stage: LoadedStageConfig;
     task: TaskFile;
     dag: ResolvedPipelineDag;
     checkoutRoot?: string;

package/dist/runtime/stageRunner.d.ts

@@ -1,6 +1,6 @@
 import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunResult, StageSessionMode } from "../agent/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { StageConfig } from "../types/stage.js";
+import type { LoadedStageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
 import type { RunStore } from "../runstore/port.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
@@ -21,7 +21,7 @@ export type RunStageOptions = {
     agent: AgentPort;
     store: RunStore;
     runId: string;
-    stage: StageConfig;
+    stage: LoadedStageConfig;
     task: TaskFile;
     dag?: ResolvedPipelineDag;
     priorEnvelope?: StageEnvelope | null;

package/dist/runtime/stageRunner.js

@@ -54,7 +54,7 @@ async function finalizeStageResult(options) {
             store,
             runId,
             stageId,
-            event: { event: "failed", reason: result.reason },
+            event: { event: "failed", reason: result.reason, usage: result.usage },
             attemptCtx,
         });
         console.error(`Stage ${stageId} failed: ${result.reason}`);
@@ -64,7 +64,7 @@ async function finalizeStageResult(options) {
         store,
         runId,
         stageId,
-        event: { event: "succeeded" },
+        event: { event: "succeeded", usage: result.usage },
         attemptCtx,
     });
     console.error(`Stage ${stageId} succeeded.`);

package/dist/runtime/taskInput.d.ts

@@ -1,3 +1,5 @@
+import { type ValidationFinding } from "../config/validateCatalog.js";
+import type { LoadedPipeline } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
 export type StartTaskInput = {
     task?: string | TaskFile;
@@ -12,4 +14,9 @@ export type ResolvedTaskInput = {
 };
 export declare function isTaskFile(value: unknown): value is TaskFile;
 export declare function taskFileToYaml(task: TaskFile): string;
+/** Validate optional `task.input` against entry-stage IR `clone_input_schema` (YAML: `io.input.schema`). */
+export declare function checkTaskEntryInput(task: TaskFile, loaded: LoadedPipeline, options: {
+    cwd: string;
+    taskPath?: string;
+}): ValidationFinding[];
 export declare function resolveStartTaskInput(input: StartTaskInput, cwd: string): ResolvedTaskInput;

package/dist/runtime/taskInput.js

@@ -1,5 +1,8 @@
+import path from "node:path";
 import { stringify as stringifyYaml } from "yaml";
 import { parseTaskFile } from "../config/loadTask.js";
+import { relPath } from "../config/validateCatalog.js";
+import { payloadInstanceMismatch } from "../envelope/payloadSchema.js";
 import { resolveTaskPath } from "./pipelineRunner.js";
 export function isTaskFile(value) {
     return parseTaskFile(value, "task").ok;
@@ -15,8 +18,65 @@ export function taskFileToYaml(task) {
         doc.constraints = task.constraints;
     if (task.checkout !== undefined)
         doc.checkout = task.checkout;
+    if (task.input !== undefined)
+        doc.input = task.input;
     return stringifyYaml(doc);
 }
+/** Validate optional `task.input` against entry-stage IR `clone_input_schema` (YAML: `io.input.schema`). */
+export function checkTaskEntryInput(task, loaded, options) {
+    const absPath = options.taskPath
+        ? path.resolve(options.cwd, options.taskPath)
+        : path.resolve(options.cwd, "task.yaml");
+    const findingPath = relPath(options.cwd, absPath);
+    const stageById = new Map(loaded.stages.map((stage) => [stage.id, stage]));
+    const findings = [];
+    for (const rootId of loaded.dag.roots) {
+        const stage = stageById.get(rootId);
+        if (stage?.clone_input_schema === undefined)
+            continue;
+        if (task.input === undefined) {
+            findings.push({
+                severity: "warning",
+                code: "task.entry_input_unmet",
+                path: findingPath,
+                message: `Task has no input; entry stage "${rootId}" requires io.input`,
+                category: "task",
+                pipelineId: loaded.pipeline.id,
+                stageId: rootId,
+            });
+            continue;
+        }
+        let details;
+        try {
+            details = payloadInstanceMismatch(task.input, stage.clone_input_schema);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            findings.push({
+                severity: "error",
+                code: "task.invalid_shape",
+                path: findingPath,
+                message: `Task input does not match entry stage "${rootId}" io.input: ${message}`,
+                category: "task",
+                pipelineId: loaded.pipeline.id,
+                stageId: rootId,
+            });
+            continue;
+        }
+        if (details !== undefined) {
+            findings.push({
+                severity: "error",
+                code: "task.invalid_shape",
+                path: findingPath,
+                message: `Task input does not match entry stage "${rootId}" io.input: ${details}`,
+                category: "task",
+                pipelineId: loaded.pipeline.id,
+                stageId: rootId,
+            });
+        }
+    }
+    return findings;
+}
 export function resolveStartTaskInput(input, cwd) {
     if (typeof input.taskYaml === "string") {
         if (input.taskYaml.trim().length === 0) {

package/dist/runtime/verifiedStageExecution.js

@@ -1,3 +1,6 @@
+/**
+ * After-phase VSE. Runs IR `CompletionContract` (YAML: `verify` when after).
+ */
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { listQaExchanges } from "../hitl/qaTrail.js";

package/dist/types/completion.d.ts

@@ -1,5 +1,10 @@
 import type { StageGateKind } from "./stage.js";
 export declare const COMPLETION_VERIFICATION_FAILURE_PREFIX = "Completion verification failed:";
+/**
+ * After-phase check IR (`DAG node.completion`). YAML: `verify` items whose
+ * `when` includes `after`. `type: payload_schema` here is a check kind (re-check
+ * the success payload after emit), not the old YAML authoring key.
+ */
 export type CompletionCheck = {
     id: string;
     type: "command";
@@ -31,6 +36,7 @@ export type CompletionContract = {
     mode: "all";
     checks: CompletionCheck[];
 };
+/** IR recovery on the DAG node. YAML: `on_verify_fail`. */
 export type RecoveryPolicy = {
     mode: "repair";
     max_attempts: number;

package/dist/types/pipeline.d.ts

@@ -1,11 +1,15 @@
 import type { CloneAction } from "./forkChoice.js";
-import type { StageConfig, StageGateKind } from "./stage.js";
+import type { LoadedStageConfig, StageGateKind, StageIoYaml } from "./stage.js";
 import type { CompletionContract, RecoveryPolicy } from "./completion.js";
 export type PipelineConfig = {
     id: string;
     stages: string[];
     /** Selects the AgentPort backend for every stage in this pipeline; overrides the global default. */
     agent?: string;
+    /** Default LLM model id for every stage in this pipeline; overrides the global default. */
+    model?: string;
+    /** Pipeline-file `$ref` root (`#/schemas/<name>`). */
+    schemas?: Record<string, unknown>;
 };
 export type PipelineForkConfig = {
     select: "one" | "subset";
@@ -37,12 +41,20 @@ export type PipelineStageRef = {
     };
     clonable?: boolean;
     clone_cap?: number;
+    /** IR: after-phase checks. YAML: `verify` items whose `when` includes `after`. */
     completion?: CompletionContract;
+    /** IR: after-phase failure policy. YAML: `on_verify_fail`. */
     recovery?: RecoveryPolicy;
     feedback_loop?: FeedbackLoopConfig;
     /** Omitted means this stage is safe to include in a feedback replay. */
     replay_safe?: boolean;
 };
+/**
+ * Pipeline YAML stage entry (both dialects). Target authoring is `io` / `verify`
+ * / `on_verify_fail`. The payload_schema / pre_emit_checks / completion /
+ * recovery keys are the legacy YAML dialect (and also the IR names after compile).
+ * New catalog fields: add target YAML keys here and compile them in yamlDialect.ts.
+ */
 export type PipelineStageYamlEntry = PipelineStageRef & {
     uses?: string;
     system_prompt?: string;
@@ -53,6 +65,10 @@ export type PipelineStageYamlEntry = PipelineStageRef & {
     clone_actions?: CloneAction[];
     skill?: string;
     mcp?: string[];
+    io?: StageIoYaml;
+    verify?: unknown;
+    on_verify_fail?: RecoveryPolicy;
+    pre_emit_checks?: unknown;
 };
 export type PipelineIncludeEntry = {
     local: string;
@@ -70,6 +86,7 @@ export type NormalizedPipelineStageEntry = {
     };
     clonable?: boolean;
     clone_cap?: number;
+    /** IR after compile. YAML `verify` after-phase / `on_verify_fail`. */
     completion?: CompletionContract;
     recovery?: RecoveryPolicy;
     feedback_loop?: FeedbackLoopConfig;
@@ -102,7 +119,9 @@ export type ResolvedPipelineStageNode = {
     clonable?: boolean;
     clone_cap?: number;
     definition_id?: string;
+    /** Persisted on pipeline_dag. YAML `verify` after-phase. */
     completion?: CompletionContract;
+    /** Persisted on pipeline_dag. YAML `on_verify_fail`. */
     recovery?: RecoveryPolicy;
     feedback_loop?: FeedbackLoopConfig;
     replay_safe?: boolean;
@@ -114,7 +133,7 @@ export type ResolvedPipelineDag = {
 };
 export type LoadedPipeline = {
     pipeline: PipelineConfig;
-    stages: StageConfig[];
+    stages: LoadedStageConfig[];
     dag: ResolvedPipelineDag;
     pipelinePath: string;
     stageSources?: Record<string, PipelineStageSource>;

package/dist/types/preEmitCheck.d.ts

@@ -1,11 +1,9 @@
 import type { StageGateKind } from "./stage.js";
 /**
- * In-session checks `emit_stage_envelope` must satisfy this attempt before a
- * success emit is accepted. Distinct from `CompletionCheck`/`CompletionContract`
- * (`src/types/completion.ts`): those run post-hoc, after a candidate envelope
- * has already been captured, driven by the pipeline-wiring `completion` field.
- * `PreEmitCheck` runs synchronously inside the agent's own `emit_stage_envelope`
- * tool call, driven by the stage-body `pre_emit_checks` field.
+ * Emit-phase check IR (`StageConfig.pre_emit_checks`). YAML: `verify` items
+ * whose `when` includes `emit`. Distinct from after-phase `CompletionCheck`
+ * (`src/types/completion.ts`), which runs after a candidate envelope is captured.
+ * This runs inside `emit_stage_envelope` before success is accepted.
  */
 export type PreEmitCheck = {
     id: string;

package/dist/types/stage.d.ts

@@ -2,16 +2,32 @@ import type { PreEmitCheck } from "./preEmitCheck.js";
 import type { CloneAction } from "./forkChoice.js";
 export declare const STAGE_GATE_KINDS: readonly ["free_text", "confirm", "multi_question", "artifact_backed"];
 export type StageGateKind = (typeof STAGE_GATE_KINDS)[number];
+/** Target YAML `io:` block. Compiles onto StageConfig.payload_schema / clone_input_schema. */
+export type StageIoYaml = {
+    input?: {
+        schema?: unknown;
+    };
+    output?: {
+        schema?: unknown;
+    };
+};
+/**
+ * Loaded stage IR. Field names are the runtime contract (emit, VSE, snapshots),
+ * not the catalog YAML spelling. Target YAML `io` / `verify` compile onto these
+ * in `src/config/yamlDialect.ts`. Do not add new catalog keys here — add them on
+ * the YAML dialect and map them in compileTargetContract.
+ */
 export type StageConfig = {
     id: string;
     system_prompt: string;
-    model: string;
-    /** Optional JSON Schema (subset) for envelope.payload on success. */
+    model?: string;
+    /** IR: success envelope.payload schema. YAML: `io.output.schema`. */
     payload_schema?: unknown;
     /** Declared ask_operator kinds this stage is expected to stop on. */
     gate_kinds?: StageGateKind[];
-    /** In-session checks emit must satisfy this attempt before success is accepted. */
+    /** IR: emit-phase checks. YAML: `verify` items whose `when` includes `emit`. */
     pre_emit_checks?: PreEmitCheck[];
+    /** IR: clone/fan-out assignment schema. YAML: `io.input.schema`. */
     clone_input_schema?: unknown;
     clone_actions?: CloneAction[];
     /** Optional stage wall-clock timeout in milliseconds (default 60 minutes). */
@@ -24,3 +40,6 @@ export type StageConfig = {
      */
     agent?: string;
 };
+export type LoadedStageConfig = StageConfig & {
+    model: string;
+};

package/dist/types/stageflowManifest.d.ts

@@ -13,6 +13,8 @@ export type StageflowManifest = {
     catalog: StageflowManifestCatalog;
     /** Default AgentPort backend for every pipeline/stage that doesn't override it. */
     agent?: string;
+    /** Default LLM model id for every stage that doesn't override it at pipeline or stage level. */
+    model?: string;
 };
 export type LoadedManifest = {
     path: string;

package/dist/types/task.d.ts

@@ -4,4 +4,5 @@ export type TaskFile = {
     context?: string;
     constraints?: string;
     checkout?: string;
+    input?: Record<string, unknown>;
 };

package/dist/types/usage.d.ts

@@ -0,0 +1,16 @@
+/** Per-model token/cost breakdown, as computed by the backend SDK itself. */
+export type ModelUsageBreakdown = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    costUsd: number;
+};
+/** Accumulated LLM usage/cost for one stage attempt, across every turn/call it made. */
+export type StageUsage = {
+    costUsd: number;
+    models: Record<string, ModelUsageBreakdown>;
+};
+/** Merge one model's usage from a single call into an accumulator, in place. */
+export declare function addModelUsage(usage: StageUsage, model: string, delta: Partial<ModelUsageBreakdown>): void;
+export declare function emptyStageUsage(): StageUsage;

package/dist/types/usage.js

@@ -0,0 +1,24 @@
+function emptyBreakdown() {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUsd: 0,
+    };
+}
+/** Merge one model's usage from a single call into an accumulator, in place. */
+export function addModelUsage(usage, model, delta) {
+    const current = usage.models[model] ?? emptyBreakdown();
+    usage.models[model] = {
+        inputTokens: current.inputTokens + (delta.inputTokens ?? 0),
+        outputTokens: current.outputTokens + (delta.outputTokens ?? 0),
+        cacheReadInputTokens: current.cacheReadInputTokens + (delta.cacheReadInputTokens ?? 0),
+        cacheCreationInputTokens: current.cacheCreationInputTokens + (delta.cacheCreationInputTokens ?? 0),
+        costUsd: current.costUsd + (delta.costUsd ?? 0),
+    };
+    usage.costUsd += delta.costUsd ?? 0;
+}
+export function emptyStageUsage() {
+    return { costUsd: 0, models: {} };
+}