stageflow 0.13.0 → 0.15.0

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>;
 };