stageflow 0.12.0 → 0.15.0

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,4 +1,7 @@
 import { resolveSkillByName } from "../config/listSkills.js";
+import { mkdir } from "node:fs/promises";
+import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
+import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
 import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
@@ -20,16 +23,49 @@ async function resolveStageSkillForRun(stage, catalog) {
     }
     return { ok: true, skillFilePath: resolved.filePath };
 }
-async function openStageWithOperatorCatalog(agent, input, catalog) {
+async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir) {
+    const names = allowlist ?? [];
+    if (names.length === 0)
+        return undefined;
+    if (factoryCwd === undefined) {
+        throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
+    }
+    await mkdir(artifactsDir, { recursive: true });
+    const resolved = await resolveStageMcpServers({
+        projectRoot: factoryCwd,
+        allowlist: names,
+        env: {
+            ...process.env,
+            [STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV]: artifactsDir,
+        },
+    });
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, artifactsDir) {
     const skill = await resolveStageSkillForRun(input.stage, catalog);
     if (!skill.ok)
         return skill;
+    let resolvedMcpServers;
+    try {
+        resolvedMcpServers = await resolveAttemptMcpServers(input.stage.mcp, factoryCwd, artifactsDir);
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            return { ok: false, reason: err.message };
+        }
+        throw err;
+    }
     try {
         const handle = agent.openStage({
             ...input,
+            stage: {
+                ...input.stage,
+                system_prompt: stampStagePromptArtifactsDir(input.stage.system_prompt, artifactsDir),
+            },
             ...(skill.skillFilePath !== undefined
                 ? { skillFilePath: skill.skillFilePath }
                 : {}),
+            ...(resolvedMcpServers !== undefined ? { resolvedMcpServers } : {}),
         });
         return { ok: true, handle };
     }
@@ -159,7 +195,7 @@ export async function openStageAttempt(input) {
         ...(input.stage.timeout_ms !== undefined
             ? { timeoutMs: input.stage.timeout_ms }
             : {}),
-    }, input.operatorCatalog);
+    }, input.operatorCatalog, input.factoryCwd, attemptArtifactsDir(input.workspaceDir, stageId, attempt));
     if (!opened.ok)
         return opened;
     return {

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/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.d.ts

@@ -3,6 +3,8 @@ import type { RunStore } from "../runstore/port.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
 import type { StageConfig } from "../types/stage.js";
 import type { StageRoots } from "./stageRoots.js";
+/** Sidecar written before completion command checks so they can inspect fork_choice. */
+export declare const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
 export type VerifiedStageExecution = {
     /** Establish durable observation before agent work begins. */
     prepare(): Promise<void>;

package/dist/runtime/verifiedStageExecution.js

@@ -1,9 +1,16 @@
+/**
+ * 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";
-import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
+import { attemptArtifactsDir, attemptWorkspaceDir, } from "../runstore/workspaceLayout.js";
 import { COMPLETION_VERIFICATION_FAILURE_PREFIX, } from "../types/completion.js";
 import { runCompletionContract, } from "./completionCheckRunner.js";
 import { readCompletionCheckoutBaseline, writeCompletionCheckoutBaseline, } from "./completionCheckoutBaseline.js";
 import { createGitCheckoutCapability } from "./gitCheckoutCapability.js";
+/** Sidecar written before completion command checks so they can inspect fork_choice. */
+export const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
 export function completionVerificationFailureReason(failedCheckIds) {
     return `${COMPLETION_VERIFICATION_FAILURE_PREFIX} ${failedCheckIds.join(", ")}`;
 }
@@ -65,11 +72,15 @@ export function createVerifiedStageExecution(options) {
             if (contract === undefined)
                 return candidate;
             try {
+                const artifactsDir = attemptArtifactsDir(roots.runWorkspaceDir, stageId, attempt);
+                const attemptDir = attemptWorkspaceDir(roots.runWorkspaceDir, stageId, attempt);
+                await mkdir(attemptDir, { recursive: true });
+                await writeFile(path.join(attemptDir, COMPLETION_CANDIDATE_ENVELOPE_FILENAME), `${JSON.stringify(candidate.envelope, null, 2)}\n`, "utf8");
                 const verification = await runCompletionContract({
                     contract,
                     envelope: candidate.envelope,
                     payloadSchema: stage.payload_schema,
-                    artifactsDir: attemptArtifactsDir(roots.runWorkspaceDir, stageId, attempt),
+                    artifactsDir,
                     commandWorkingDirectory: roots.cwd,
                     gates: gateDecisionsForAttempt({ store, runId, stageId, attempt }),
                     checkout,

package/dist/server/http.js

@@ -3,12 +3,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getCredentialSourceSettings, setCredentialSource, } from "../agent/providerAuth.js";
 import { handleProviderRoutes, providerAuthErrorBody, } from "./providerRoutes.js";
+import { handleProjectMcpRoutes } from "./projectMcpRoutes.js";
 import { createPipeline, parseCreatePipelineBody } from "../config/createPipeline.js";
 import { createStage, parseCreateStageBody } from "../config/createStage.js";
 import { browseCatalog } from "../config/browseCatalog.js";
 import { listExtensions } from "../config/listExtensions.js";
 import { listSkills } from "../config/listSkills.js";
-import { readRunArtifact } from "../mcp/readArtifact.js";
+import { artifactMediaType, readRunArtifact, readRunArtifactBytes, } from "../mcp/readArtifact.js";
 import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, } from "../runtime/settingsFile.js";
@@ -96,7 +97,8 @@ function isMutatingApi(method, pathname) {
         /^\/api\/providers\/[^/]+\/login$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login\/[^/]+\/answer$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login\/[^/]+\/cancel$/.test(pathname) ||
-        /^\/api\/providers\/[^/]+\/logout$/.test(pathname));
+        /^\/api\/providers\/[^/]+\/logout$/.test(pathname) ||
+        /^\/api\/project-mcp\/[^/]+\/probe$/.test(pathname));
 }
 function isCredentialMutatingApi(method, pathname) {
     if (method !== "POST")
@@ -210,8 +212,19 @@ export async function startUiServer(options) {
                         return true;
                     }
                     try {
-                        const content = await readRunArtifact(store, runId, artifactPath);
-                        textPlain(res, 200, content);
+                        const mediaType = artifactMediaType(artifactPath);
+                        if (mediaType !== undefined) {
+                            const bytes = await readRunArtifactBytes(store, runId, artifactPath);
+                            res.writeHead(200, {
+                                "Content-Type": mediaType,
+                                "Content-Length": bytes.length,
+                            });
+                            res.end(bytes);
+                        }
+                        else {
+                            const content = await readRunArtifact(store, runId, artifactPath);
+                            textPlain(res, 200, content);
+                        }
                     }
                     catch (err) {
                         const message = err instanceof Error ? err.message : String(err);
@@ -527,6 +540,12 @@ export async function startUiServer(options) {
                 })) {
                     return true;
                 }
+                if (await handleProjectMcpRoutes(req, res, {
+                    projectRoot: boot.rootDir,
+                    json,
+                })) {
+                    return true;
+                }
                 if (method === "GET" && pathname === "/api/skills") {
                     json(res, 200, await listSkills({ cwd, agentDir }));
                     return true;

package/dist/server/projectMcpRoutes.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export type ProjectMcpRoutesCtx = {
+    projectRoot: string;
+    json: (res: ServerResponse, status: number, body: unknown) => void;
+};
+export declare function handleProjectMcpRoutes(req: IncomingMessage, res: ServerResponse, ctx: ProjectMcpRoutesCtx): Promise<boolean>;

package/dist/server/projectMcpRoutes.js

@@ -0,0 +1,38 @@
+import { probeProjectMcpServer } from "../agent/piIsolatedMcpProbe.js";
+import { listProjectMcpCatalog } from "../config/resolveStageMcpServers.js";
+function requestAbortSignal(req) {
+    const controller = new AbortController();
+    const abort = () => {
+        if (!controller.signal.aborted)
+            controller.abort();
+    };
+    if (req.aborted || req.destroyed) {
+        abort();
+        return controller.signal;
+    }
+    req.once("aborted", abort);
+    req.once("close", abort);
+    return controller.signal;
+}
+export async function handleProjectMcpRoutes(req, res, ctx) {
+    const { projectRoot, json } = ctx;
+    const method = req.method ?? "GET";
+    const rawUrl = req.url ?? "/";
+    const pathname = new URL(rawUrl, "http://localhost").pathname;
+    if (method === "GET" && pathname === "/api/project-mcp") {
+        json(res, 200, await listProjectMcpCatalog(projectRoot));
+        return true;
+    }
+    const probeMatch = pathname.match(/^\/api\/project-mcp\/([^/]+)\/probe$/);
+    if (method === "POST" && probeMatch) {
+        const name = decodeURIComponent(probeMatch[1] ?? "");
+        const result = await probeProjectMcpServer({
+            projectRoot,
+            name,
+            signal: requestAbortSignal(req),
+        });
+        json(res, 200, result);
+        return true;
+    }
+    return false;
+}

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;
@@ -52,6 +64,11 @@ export type PipelineStageYamlEntry = PipelineStageRef & {
     clone_input_schema?: unknown;
     clone_actions?: CloneAction[];
     skill?: string;
+    mcp?: string[];
+    io?: StageIoYaml;
+    verify?: unknown;
+    on_verify_fail?: RecoveryPolicy;
+    pre_emit_checks?: unknown;
 };
 export type PipelineIncludeEntry = {
     local: string;
@@ -69,11 +86,13 @@ 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;
     replay_safe?: boolean;
     skill?: string;
+    mcp?: string[];
     body: {
         kind: "inline";
         raw: Record<string, unknown>;
@@ -100,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;
@@ -112,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,24 +2,44 @@ 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 15 minutes). */
+    /** Optional stage wall-clock timeout in milliseconds (default 60 minutes). */
     timeout_ms?: number;
     skill?: string;
+    mcp?: string[];
     /**
      * Selects the AgentPort backend for this stage, overriding pipeline/global.
      * Parsed but not yet consulted — see STAGE_LEVEL_AGENT_OVERRIDE_ENABLED.
      */
     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>;
 };