stageflow 0.2.0 → 0.8.0

package/dist/mcp/server.js

@@ -1,16 +1,67 @@
+import { randomUUID } from "node:crypto";
 import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
-import { McpServer } from "@modelcontextprotocol/server";
+import { isInitializeRequest, McpServer, } from "@modelcontextprotocol/server";
+import { registerRunResources, runResourceUri } from "./resources.js";
 import { registerMcpTools } from "./tools.js";
+function jsonRpcError(res, status, code, message) {
+    const payload = JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id: null,
+    });
+    res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Content-Length": Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function sessionIdFromRequest(req) {
+    const raw = req.headers["mcp-session-id"];
+    if (typeof raw === "string" && raw.length > 0)
+        return raw;
+    if (Array.isArray(raw) && typeof raw[0] === "string" && raw[0].length > 0) {
+        return raw[0];
+    }
+    return undefined;
+}
+function toolDepsFrom(deps) {
+    return { manager: deps.manager, store: deps.store, cwd: deps.cwd };
+}
+function attachBusNotifications(server, bus) {
+    return bus.on((event) => {
+        const uri = runResourceUri(event.runId);
+        void server.server.sendResourceUpdated({ uri }).catch(() => undefined);
+        if (event.kind === "created") {
+            void server.server.sendResourceListChanged().catch(() => undefined);
+        }
+    });
+}
 export function createStageflowMcpServer(deps) {
     const server = new McpServer({
         name: "stageflow",
         version: "0.2.0",
+    }, {
+        capabilities: {
+            resources: {
+                subscribe: true,
+                listChanged: true,
+            },
+        },
     });
     registerMcpTools(server, deps);
+    registerRunResources(server, deps);
     return server;
 }
-/** Stateless Streamable HTTP: new server + transport per request. */
-export async function handleMcpHttpRequest(req, res, deps) {
+async function handleStatelessMcpRequest(req, res, deps) {
     const server = createStageflowMcpServer(deps);
     const transport = new NodeStreamableHTTPServerTransport({
         sessionIdGenerator: undefined,
@@ -24,3 +75,108 @@ export async function handleMcpHttpRequest(req, res, deps) {
         await server.close().catch(() => undefined);
     }
 }
+/** Stateful Streamable HTTP session host (product default) or stateless escape hatch. */
+export function createMcpHttpHandler(deps, options = {}) {
+    const stateless = options.mcpStateless === true;
+    const sessions = new Map();
+    const tools = toolDepsFrom(deps);
+    async function disposeSession(sessionId, opts) {
+        const entry = sessions.get(sessionId);
+        if (!entry)
+            return;
+        sessions.delete(sessionId);
+        const unsub = entry.unsubscribeBus;
+        entry.unsubscribeBus = undefined;
+        unsub?.();
+        if (opts.closeTransport) {
+            await entry.transport.close().catch(() => undefined);
+        }
+        await entry.server.close().catch(() => undefined);
+    }
+    async function closeSession(sessionId) {
+        await disposeSession(sessionId, { closeTransport: true });
+    }
+    async function handleStateful(req, res) {
+        const sessionId = sessionIdFromRequest(req);
+        const method = req.method ?? "GET";
+        if (sessionId && sessions.has(sessionId)) {
+            const entry = sessions.get(sessionId);
+            await entry.transport.handleRequest(req, res);
+            return;
+        }
+        if (sessionId) {
+            jsonRpcError(res, 404, -32001, "Session not found");
+            return;
+        }
+        if (method === "POST") {
+            let body;
+            try {
+                body = await readJsonBody(req);
+            }
+            catch {
+                jsonRpcError(res, 400, -32700, "Parse error");
+                return;
+            }
+            if (!isInitializeRequest(body)) {
+                jsonRpcError(res, 400, -32000, "Bad Request: Session ID required");
+                return;
+            }
+            const server = createStageflowMcpServer(tools);
+            let sessionRegistered = false;
+            const transport = new NodeStreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (id) => {
+                    sessions.set(id, {
+                        transport,
+                        server,
+                        unsubscribeBus: attachBusNotifications(server, deps.runChangeBus),
+                    });
+                    sessionRegistered = true;
+                },
+                onsessionclosed: (id) => {
+                    void disposeSession(id, { closeTransport: false });
+                },
+            });
+            transport.onclose = () => {
+                const id = transport.sessionId;
+                if (!id)
+                    return;
+                void disposeSession(id, { closeTransport: false });
+            };
+            try {
+                await server.connect(transport);
+                await transport.handleRequest(req, res, body);
+            }
+            finally {
+                if (!sessionRegistered) {
+                    await transport.close().catch(() => undefined);
+                    await server.close().catch(() => undefined);
+                }
+            }
+            return;
+        }
+        jsonRpcError(res, 400, -32000, "Bad Request: Session ID required");
+    }
+    return {
+        handle: async (req, res) => {
+            if (stateless) {
+                await handleStatelessMcpRequest(req, res, tools);
+                return;
+            }
+            await handleStateful(req, res);
+        },
+        close: async () => {
+            const ids = [...sessions.keys()];
+            await Promise.all(ids.map((id) => closeSession(id)));
+        },
+    };
+}
+export async function handleMcpHttpRequest(req, res, deps) {
+    await handleStatelessMcpRequest(req, res, deps);
+}
+export function resolveMcpStateless(options) {
+    if (options?.mcpStateless === true)
+        return true;
+    const env = options?.env ?? process.env;
+    return env.STAGEFLOW_MCP_STATELESS === "1";
+}

package/dist/mcp/toolResults.d.ts

@@ -0,0 +1,7 @@
+export declare function textResult(data: unknown, isError?: boolean): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean | undefined;
+};

package/dist/mcp/toolResults.js

@@ -0,0 +1,6 @@
+export function textResult(data, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}

package/dist/mcp/tools.d.ts

@@ -1,9 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/server";
-import type { RunStore } from "../runstore/port.js";
-import type { RunManager } from "../runtime/runManager.js";
-export type McpToolDeps = {
-    manager: RunManager;
-    store: RunStore;
-    cwd: string;
-};
+import type { McpToolDeps } from "./deps.js";
+export type { McpToolDeps };
 export declare function registerMcpTools(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/tools.js

@@ -1,96 +1,62 @@
 import { z } from "zod";
-import { listPipelines } from "../config/listConfig.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(),
-});
-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 runnable pipeline ids from the factory cwd",
-        inputSchema: z.object({}),
-    }, async () => {
-        const pipelines = await listPipelines(cwd);
-        return textResult({ pipelines });
-    });
-    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 with an inline TaskFile (not written under tasks/). 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: z.object({
-            pipeline: z.string(),
-            task: taskFileSchema,
-        }),
-    }, async ({ pipeline, task }) => {
-        if (!pipeline.trim()) {
-            return textResult({ error: "pipeline is required" }, true);
-        }
-        const result = await manager.startRun({ pipeline, task });
-        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/project/findProjectRoot.d.ts

@@ -0,0 +1,2 @@
+export declare function findProjectRoot(startDir: string): string | null;
+export declare function clearFindProjectRootCacheForTests(): void;