stageflow 0.3.0 → 0.9.0

package/dist/mcp/tools.js

@@ -1,113 +1,62 @@
 import { z } from "zod";
-import { browseCatalog } from "../config/browseCatalog.js";
-import { projectRunForMcp } from "./projectRun.js";
-import { readRunArtifact } from "./readArtifact.js";
-const taskFileSchema = z.object({
-    id: z.string(),
-    goal: z.string(),
-    context: z.string().optional(),
-    constraints: z.string().optional(),
-    checkout: z.string().optional(),
-});
-const startRunSchema = z
-    .object({
-    pipeline: z.string().describe("Filesystem path to a pipeline YAML file"),
-    task_path: z.string().optional(),
-    task: taskFileSchema.optional(),
-})
-    .refine((data) => Boolean(data.task_path) !== Boolean(data.task), {
-    message: "Exactly one of task_path or task is required",
-});
-function textResult(data, isError = false) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-        ...(isError ? { isError: true } : {}),
-    };
-}
+import { registerCatalogTools } from "./catalogTools.js";
+import { registerControlTools } from "./controlTools.js";
+import { textResult } from "./toolResults.js";
+import { DEFAULT_TIMEOUT_MS, waitRun } from "./waitRun.js";
 export function registerMcpTools(server, deps) {
-    const { manager, store, cwd } = deps;
-    server.registerTool("list_pipelines", {
-        description: "List manifest-declared pipeline paths from the project catalog",
-        inputSchema: z.object({}),
-    }, async () => {
-        const catalog = await browseCatalog(cwd);
-        return textResult({ pipelines: catalog.pipelines });
-    });
-    server.registerTool("list_tasks", {
-        description: "List manifest-declared task paths from the project catalog",
-        inputSchema: z.object({}),
-    }, async () => {
-        const catalog = await browseCatalog(cwd);
-        return textResult({ tasks: catalog.tasks });
-    });
-    server.registerTool("list_runs", {
-        description: "List known pipeline runs",
-        inputSchema: z.object({}),
-    }, async () => {
-        const runs = await store.listRuns();
-        return textResult({ runs });
-    });
-    server.registerTool("get_health", {
-        description: "Server health and soft-max run capacity: activeRunIds, activeCount, maxConcurrent, slotsAvailable. Start until slotsAvailable is 0; then wait for a run to finish or raise STAGEFLOW_MAX_CONCURRENT_RUNS.",
-        inputSchema: z.object({}),
-    }, async () => textResult(manager.getHealth()));
-    server.registerTool("start_run", {
-        description: "Start a pipeline run using a filesystem pipeline path and either task_path (catalog task file) or an inline task object. Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
-        inputSchema: startRunSchema,
-    }, async ({ pipeline, task_path, task }) => {
-        if (!pipeline.trim()) {
-            return textResult({ error: "pipeline is required" }, true);
-        }
-        const taskInput = task_path ?? task;
-        if (taskInput === undefined) {
-            return textResult({ error: "Exactly one of task_path or task is required" }, true);
-        }
-        const result = await manager.startRun({ pipeline, task: taskInput });
-        if (!result.ok) {
-            const { ok: _ok, reason, ...rest } = result;
-            return textResult({ error: reason, ...rest }, true);
-        }
-        return textResult({ runId: result.runId });
-    });
-    server.registerTool("get_run", {
-        description: "Poll a run: status, stage statuses, and envelope summary/payload/artifact paths (no events).",
+    const { store } = deps;
+    registerCatalogTools(server, deps);
+    registerControlTools(server, deps);
+    server.registerTool("wait_run", {
+        description: "Long-poll until a run is waiting for HITL input and/or terminal (succeeded/failed), or until timeout_ms. Default until=any wakes on waiting OR terminal. Abort cancels only this wait (not the run). Optional notifications/progress when the client supplies _meta.progressToken. Compose: wait_run → answer_gate → wait_run.",
         inputSchema: z.object({
             runId: z.string(),
+            timeout_ms: z
+                .number()
+                .optional()
+                .describe(`Wait budget in ms (default ${DEFAULT_TIMEOUT_MS}, max 240000)`),
+            until: z
+                .enum(["any", "waiting", "terminal"])
+                .optional()
+                .describe('Wake predicate: "any" (default), "waiting", or "terminal"'),
         }),
-    }, async ({ runId }) => {
-        try {
-            const detail = await store.readRun(runId);
-            return textResult(projectRunForMcp(detail));
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const notFound = /not found|no such|unknown run/i.test(message);
-            return textResult({
-                error: message,
-                status: notFound ? 404 : 500,
-            }, true);
-        }
-    });
-    server.registerTool("read_artifact", {
-        description: "Read a text artifact from a run workspace by relative path (contained under the run workspace).",
-        inputSchema: z.object({
-            runId: z.string(),
-            path: z.string(),
-        }),
-    }, async ({ runId, path: artifactPath }) => {
-        try {
-            const content = await readRunArtifact(store, runId, artifactPath);
-            return textResult({ runId, path: artifactPath, content });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const notFound = message.startsWith("Run not found") ||
-                message.startsWith("Artifact not found") ||
-                /no such|not found/i.test(message);
+    }, async ({ runId, timeout_ms, until }, ctx) => {
+        const progressToken = ctx.mcpReq._meta?.progressToken;
+        const result = await waitRun({
+            store,
+            runId,
+            timeoutMs: timeout_ms,
+            until,
+            signal: ctx.mcpReq.signal,
+            onProgress: progressToken !== undefined
+                ? async (info) => {
+                    try {
+                        await ctx.mcpReq.notify({
+                            method: "notifications/progress",
+                            params: {
+                                progressToken,
+                                progress: info.progress,
+                                message: info.message,
+                            },
+                        });
+                    }
+                    catch {
+                    }
+                }
+                : undefined,
+        });
+        if (!result.ok) {
             return textResult({
-                error: message,
-                status: notFound ? 404 : 400,
+                error: result.error,
+                ...(result.status !== undefined ? { status: result.status } : {}),
+                ...(result.code !== undefined ? { code: result.code } : {}),
             }, true);
         }
+        return textResult({
+            reason: result.reason,
+            elapsed_ms: result.elapsed_ms,
+            until: result.until,
+            run: result.run,
+        });
     });
 }

package/dist/mcp/waitRun.d.ts

@@ -0,0 +1,46 @@
+import type { RunProjection } from "../projection/projectRun.js";
+import type { RunStore } from "../runstore/port.js";
+export type WaitUntil = "any" | "waiting" | "terminal";
+export type WaitReason = "waiting" | "terminal" | "timeout" | "already";
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export declare const MAX_TIMEOUT_MS = 240000;
+export declare const POLL_INTERVAL_MS = 250;
+export declare const PROGRESS_EVERY_MS = 2000;
+export type WaitRunProgressInfo = {
+    progress: number;
+    message: string;
+};
+export type WaitRunSuccess = {
+    ok: true;
+    reason: WaitReason;
+    elapsed_ms: number;
+    until: WaitUntil;
+    run: RunProjection;
+};
+export type WaitRunFailure = {
+    ok: false;
+    error: string;
+    status?: number;
+    code?: string;
+};
+export type WaitRunResult = WaitRunSuccess | WaitRunFailure;
+export type WaitRunOpts = {
+    store: Pick<RunStore, "readRun">;
+    runId: string;
+    timeoutMs?: number;
+    until?: WaitUntil;
+    signal?: AbortSignal;
+    onProgress?: (info: WaitRunProgressInfo) => void | Promise<void>;
+};
+export declare function clampTimeoutMs(timeoutMs: number | undefined): {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function isWaitingProjection(projection: Pick<RunProjection, "waiting_stage_ids" | "waiting_stage_id" | "stages">): boolean;
+export declare function isTerminalProjection(projection: Pick<RunProjection, "status">): boolean;
+export declare function classifyWaitWake(projection: Pick<RunProjection, "status" | "waiting_stage_ids" | "waiting_stage_id" | "stages">, until: WaitUntil, hadWaited: boolean): Exclude<WaitReason, "timeout"> | null;
+export declare function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function waitRun(opts: WaitRunOpts): Promise<WaitRunResult>;

package/dist/mcp/waitRun.js

@@ -0,0 +1,146 @@
+import { projectRunForMcp } from "./projectRun.js";
+export const DEFAULT_TIMEOUT_MS = 60_000;
+export const MAX_TIMEOUT_MS = 240_000;
+export const POLL_INTERVAL_MS = 250;
+export const PROGRESS_EVERY_MS = 2_000;
+export function clampTimeoutMs(timeoutMs) {
+    const value = timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : timeoutMs;
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value <= 0 ||
+        value > MAX_TIMEOUT_MS) {
+        return {
+            ok: false,
+            error: `timeout_ms must be in (0, ${MAX_TIMEOUT_MS}]`,
+        };
+    }
+    return { ok: true, value };
+}
+export function isWaitingProjection(projection) {
+    if (projection.waiting_stage_ids !== undefined &&
+        projection.waiting_stage_ids.length > 0) {
+        return true;
+    }
+    if (projection.waiting_stage_id !== undefined) {
+        return true;
+    }
+    return projection.stages.some((s) => s.status === "waiting_for_input");
+}
+export function isTerminalProjection(projection) {
+    return projection.status === "succeeded" || projection.status === "failed";
+}
+export function classifyWaitWake(projection, until, hadWaited) {
+    const waiting = isWaitingProjection(projection);
+    const terminal = isTerminalProjection(projection);
+    let matched = null;
+    if (until === "waiting") {
+        if (waiting)
+            matched = "waiting";
+        else if (terminal)
+            matched = "terminal";
+    }
+    else if (until === "terminal") {
+        if (terminal)
+            matched = "terminal";
+    }
+    else if (waiting) {
+        matched = "waiting";
+    }
+    else if (terminal) {
+        matched = "terminal";
+    }
+    if (matched === null)
+        return null;
+    return hadWaited ? matched : "already";
+}
+export function sleepAbortable(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(Object.assign(new Error("aborted"), { code: "aborted" }));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(Object.assign(new Error("aborted"), { code: "aborted" }));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export async function waitRun(opts) {
+    const untilVal = opts.until ?? "any";
+    const clamped = clampTimeoutMs(opts.timeoutMs);
+    if (!clamped.ok) {
+        return { ok: false, error: clamped.error, status: 400 };
+    }
+    const signal = opts.signal;
+    const started = Date.now();
+    let hadWaited = false;
+    let pollCount = 0;
+    let lastProgressAt = 0;
+    while (true) {
+        if (signal?.aborted) {
+            return { ok: false, error: "wait aborted", code: "aborted" };
+        }
+        let detail;
+        try {
+            detail = await opts.store.readRun(opts.runId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = /not found|no such|unknown run/i.test(message);
+            return {
+                ok: false,
+                error: message,
+                status: notFound ? 404 : 500,
+            };
+        }
+        const run = projectRunForMcp(detail);
+        const wake = classifyWaitWake(run, untilVal, hadWaited);
+        const elapsed_ms = Date.now() - started;
+        if (wake !== null) {
+            return {
+                ok: true,
+                reason: wake,
+                elapsed_ms,
+                until: untilVal,
+                run,
+            };
+        }
+        if (elapsed_ms >= clamped.value) {
+            return {
+                ok: true,
+                reason: "timeout",
+                elapsed_ms,
+                until: untilVal,
+                run,
+            };
+        }
+        if (opts.onProgress &&
+            elapsed_ms - lastProgressAt >= PROGRESS_EVERY_MS) {
+            try {
+                const maybe = opts.onProgress({
+                    progress: pollCount,
+                    message: `waiting until=${untilVal} elapsed_ms=${elapsed_ms}`,
+                });
+                void Promise.resolve(maybe).catch(() => { });
+            }
+            catch {
+            }
+            lastProgressAt = elapsed_ms;
+        }
+        const remaining = clamped.value - elapsed_ms;
+        const sleepMs = Math.min(POLL_INTERVAL_MS, remaining);
+        try {
+            await sleepAbortable(sleepMs, signal);
+        }
+        catch {
+            return { ok: false, error: "wait aborted", code: "aborted" };
+        }
+        hadWaited = true;
+        pollCount += 1;
+    }
+}

package/dist/mcp/waitingGates.d.ts

@@ -0,0 +1,12 @@
+import type { RunStore, RunSummary, StageSnapshot } from "../runstore/port.js";
+type WaitingSummarySource = Pick<RunSummary, "run_id" | "waiting_stage_id" | "waiting_stage_ids" | "waiting_kind" | "waiting_summary" | "waiting_prompt_id" | "waiting_artifacts" | "waiting_questions">;
+export declare function projectWaitingGate(opts: {
+    runId: string;
+    stageId: string;
+    stage: StageSnapshot;
+    summary: WaitingSummarySource;
+}): Record<string, unknown>;
+export declare function projectWaitingGates(store: RunStore, opts?: {
+    runId?: string;
+}): Promise<Array<Record<string, unknown>>>;
+export {};

package/dist/mcp/waitingGates.js

@@ -0,0 +1,83 @@
+export function projectWaitingGate(opts) {
+    const { runId, stageId, stage, summary } = opts;
+    const prompt = stage.pending_prompt;
+    const item = {
+        runId,
+        stageId,
+    };
+    if (prompt !== undefined) {
+        item.waiting_kind = prompt.kind;
+        item.waiting_prompt_id = prompt.id;
+        item.pending_prompt = prompt;
+        if (prompt.kind === "multi_question") {
+            item.waiting_questions = prompt.questions.map((q) => q.message);
+        }
+        else {
+            item.waiting_summary = prompt.message;
+        }
+        if (prompt.kind === "artifact_backed") {
+            item.waiting_artifacts = prompt.artifacts;
+        }
+    }
+    else if (stageId === summary.waiting_stage_id) {
+        if (summary.waiting_kind !== undefined) {
+            item.waiting_kind = summary.waiting_kind;
+        }
+        if (summary.waiting_summary !== undefined) {
+            item.waiting_summary = summary.waiting_summary;
+        }
+        if (summary.waiting_prompt_id !== undefined) {
+            item.waiting_prompt_id = summary.waiting_prompt_id;
+        }
+        if (summary.waiting_artifacts !== undefined) {
+            item.waiting_artifacts = summary.waiting_artifacts;
+        }
+        if (summary.waiting_questions !== undefined) {
+            item.waiting_questions = summary.waiting_questions;
+        }
+    }
+    return item;
+}
+function projectGatesForRun(detail, summary) {
+    const stageIds = summary.waiting_stage_ids ??
+        (summary.waiting_stage_id !== undefined ? [summary.waiting_stage_id] : []);
+    const items = [];
+    for (const stageId of stageIds) {
+        const stage = detail.stages.find((s) => s.stage_id === stageId);
+        if (!stage || stage.status !== "waiting_for_input")
+            continue;
+        items.push(projectWaitingGate({
+            runId: summary.run_id,
+            stageId,
+            stage,
+            summary,
+        }));
+    }
+    return items;
+}
+export async function projectWaitingGates(store, opts) {
+    if (opts?.runId !== undefined) {
+        let detail;
+        try {
+            detail = await store.readRun(opts.runId);
+        }
+        catch {
+            return [];
+        }
+        return projectGatesForRun(detail, detail);
+    }
+    const summaries = await store.listRuns();
+    const waiting = summaries.filter((r) => (r.waiting_stage_ids !== undefined && r.waiting_stage_ids.length > 0) ||
+        r.waiting_stage_id !== undefined);
+    const perRun = await Promise.all(waiting.map(async (summary) => {
+        let detail;
+        try {
+            detail = await store.readRun(summary.run_id);
+        }
+        catch {
+            return [];
+        }
+        return projectGatesForRun(detail, summary);
+    }));
+    return perRun.flat();
+}

package/dist/package-meta.d.ts

@@ -1 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
+export declare const PACKAGE_VERSION = "0.9.0";

package/dist/package-meta.js

@@ -1 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
+export const PACKAGE_VERSION = "0.9.0";

package/dist/projection/projectRun.d.ts

@@ -0,0 +1,44 @@
+import type { RunDetail, StageSnapshot } from "../runstore/port.js";
+import type { PipelineTrackProjection, RunSummary } from "../runstore/port.js";
+import type { AskOperatorPrompt } from "../tools/askOperator.js";
+import type { StageEnvelope } from "../types/envelope.js";
+import type { CloneForkItem } from "../types/forkChoice.js";
+export type StageProjection = {
+    stage_id: string;
+    status: StageSnapshot["status"];
+    envelope: {
+        status: StageEnvelope["status"];
+        summary: string;
+        artifacts: string[];
+        payload?: Record<string, unknown>;
+        fork_choice?: string[];
+        clone_forks?: CloneForkItem[];
+    } | null;
+    artifacts: string[];
+    last_at?: string;
+    pending_prompt?: AskOperatorPrompt;
+};
+export type RunProjection = {
+    run_id: string;
+    pipeline_id: string;
+    task_id?: string;
+    pipeline_path?: string;
+    task_path?: string;
+    project_root?: string;
+    status: RunDetail["status"];
+    created_at: string;
+    updated_at?: string;
+    stages: StageProjection[];
+    pipeline_track: PipelineTrackProjection;
+    waiting_stage_id?: RunSummary["waiting_stage_id"];
+    waiting_stage_ids?: RunSummary["waiting_stage_ids"];
+    waiting_summary?: RunSummary["waiting_summary"];
+    waiting_kind?: RunSummary["waiting_kind"];
+    waiting_prompt_id?: RunSummary["waiting_prompt_id"];
+    waiting_artifacts?: RunSummary["waiting_artifacts"];
+    waiting_questions?: RunSummary["waiting_questions"];
+    failed_stage_id?: RunSummary["failed_stage_id"];
+    failed_reason?: RunSummary["failed_reason"];
+};
+export declare function projectRun(detail: RunDetail): RunProjection;
+export { projectRun as projectRunForMcp };

package/dist/projection/projectRun.js

@@ -0,0 +1,71 @@
+export function projectRun(detail) {
+    return {
+        run_id: detail.run_id,
+        pipeline_id: detail.pipeline_id,
+        task_id: detail.task_id,
+        ...(detail.pipeline_path !== undefined
+            ? { pipeline_path: detail.pipeline_path }
+            : {}),
+        ...(detail.task_path !== undefined ? { task_path: detail.task_path } : {}),
+        ...(detail.project_root !== undefined
+            ? { project_root: detail.project_root }
+            : {}),
+        status: detail.status,
+        created_at: detail.created_at,
+        updated_at: detail.updated_at,
+        pipeline_track: detail.pipeline_track,
+        ...(detail.waiting_stage_id !== undefined
+            ? { waiting_stage_id: detail.waiting_stage_id }
+            : {}),
+        ...(detail.waiting_stage_ids !== undefined
+            ? { waiting_stage_ids: detail.waiting_stage_ids }
+            : {}),
+        ...(detail.waiting_summary !== undefined
+            ? { waiting_summary: detail.waiting_summary }
+            : {}),
+        ...(detail.waiting_kind !== undefined
+            ? { waiting_kind: detail.waiting_kind }
+            : {}),
+        ...(detail.waiting_prompt_id !== undefined
+            ? { waiting_prompt_id: detail.waiting_prompt_id }
+            : {}),
+        ...(detail.waiting_artifacts !== undefined
+            ? { waiting_artifacts: detail.waiting_artifacts }
+            : {}),
+        ...(detail.waiting_questions !== undefined
+            ? { waiting_questions: detail.waiting_questions }
+            : {}),
+        ...(detail.failed_stage_id !== undefined
+            ? { failed_stage_id: detail.failed_stage_id }
+            : {}),
+        ...(detail.failed_reason !== undefined
+            ? { failed_reason: detail.failed_reason }
+            : {}),
+        stages: detail.stages.map((stage) => ({
+            stage_id: stage.stage_id,
+            status: stage.status,
+            envelope: stage.envelope
+                ? {
+                    status: stage.envelope.status,
+                    summary: stage.envelope.summary,
+                    artifacts: stage.envelope.artifacts,
+                    ...(stage.envelope.payload !== undefined
+                        ? { payload: stage.envelope.payload }
+                        : {}),
+                    ...(stage.envelope.fork_choice !== undefined
+                        ? { fork_choice: stage.envelope.fork_choice }
+                        : {}),
+                    ...(stage.envelope.clone_forks !== undefined
+                        ? { clone_forks: stage.envelope.clone_forks }
+                        : {}),
+                }
+                : null,
+            artifacts: stage.artifacts,
+            last_at: stage.last_at,
+            ...(stage.pending_prompt
+                ? { pending_prompt: stage.pending_prompt }
+                : {}),
+        })),
+    };
+}
+export { projectRun as projectRunForMcp };

package/dist/prompt/priorEnvelope.d.ts

@@ -1,2 +1,2 @@
 import type { StageEnvelope } from "../types/envelope.js";
-export declare function formatPriorEnvelope(priorEnvelope: StageEnvelope | null): string;
+export declare function formatPriorEnvelope(priorEnvelope: StageEnvelope | null, priorEnvelopes?: StageEnvelope[]): string;

package/dist/prompt/priorEnvelope.js

@@ -1,4 +1,7 @@
-export function formatPriorEnvelope(priorEnvelope) {
+export function formatPriorEnvelope(priorEnvelope, priorEnvelopes) {
+    if (priorEnvelopes !== undefined && priorEnvelopes.length > 0) {
+        return `Prior envelopes (${priorEnvelopes.length} clones, clone-list order):\n${JSON.stringify(priorEnvelopes, null, 2)}`;
+    }
     return priorEnvelope === null
         ? "No prior envelope (first stage)."
         : `Prior envelope JSON:\n${JSON.stringify(priorEnvelope, null, 2)}`;

package/dist/runstore/paths.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { readdirSync, renameSync, rmdirSync, statSync } from "node:fs";
 import path from "node:path";
+import { guardStageId } from "./workspaceLayout.js";
 export function newRunId() {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     return `${stamp}-${randomBytes(3).toString("hex")}`;
@@ -56,5 +57,6 @@ export function runWorkspaceDir(storeRoot, runId) {
     return path.join(runsDir(storeRoot), runId);
 }
 export function stageDir(workspaceDir, stageId) {
+    guardStageId(stageId);
     return path.join(workspaceDir, "stages", stageId);
 }

package/dist/runstore/pipelineDagSnapshot.d.ts

@@ -3,3 +3,12 @@ import type { RunPipelineDagSnapshot } from "./port.js";
 export declare function buildPipelineDagSnapshotFromLoaded(loaded: LoadedPipeline): RunPipelineDagSnapshot;
 export declare function linearCompatDagSnapshot(stageIds: string[]): RunPipelineDagSnapshot;
 export declare function parsePipelineDagSnapshot(raw: unknown): RunPipelineDagSnapshot | null;
+export declare function instancesOfDefinition(snapshot: RunPipelineDagSnapshot, catalogId: string): string[];
+export declare function appendCloneInstances(snapshot: RunPipelineDagSnapshot, input: {
+    catalogId: string;
+    predecessorId: string;
+    count: number;
+}): {
+    snapshot: RunPipelineDagSnapshot;
+    instanceIds: string[];
+};