stageflow 0.3.0 → 0.9.0

package/dist/mcp/controlTools.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { mapRetryStageFailure, mapStartFailure, } from "../server/operatorResults.js";
+import { parseAskOperatorAnswer } from "../tools/askOperator.js";
+import { textResult } from "./toolResults.js";
+import { projectWaitingGates } from "./waitingGates.js";
+export function registerControlTools(server, deps) {
+    const { manager, store } = deps;
+    server.registerTool("list_waiting", {
+        description: "List stages waiting for operator input across runs (optional runId filter). Includes pending_prompt and waiting_* fields per gate.",
+        inputSchema: z.object({
+            runId: z.string().optional(),
+        }),
+    }, async ({ runId }) => {
+        const waiting = await projectWaitingGates(store, { runId });
+        return textResult({ waiting });
+    });
+    server.registerTool("answer_gate", {
+        description: "Deliver an AskOperatorAnswer for a stage in waiting_for_input (same semantics as POST /api/runs/:id/stages/:stageId/answer). Pass answer as { promptId, kind, ... } matching the pending prompt.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+            answer: z.record(z.string(), z.unknown()),
+        }),
+    }, async ({ runId, stageId, answer }) => {
+        let parsed;
+        try {
+            parsed = parseAskOperatorAnswer(answer);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return textResult({ error: message, status: 400 }, true);
+        }
+        const result = await manager.deliverAnswer(runId, stageId, parsed);
+        if (!result.ok) {
+            return textResult({ error: result.reason, status: result.status }, true);
+        }
+        return textResult({ ok: true });
+    });
+    server.registerTool("list_stage_events", {
+        description: "List persisted stage log events for a run stage (optional attempt filter). Prefer over bloating get_run.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+            attempt: z.number().int().positive().optional(),
+        }),
+    }, async ({ runId, stageId, attempt }) => {
+        try {
+            await store.readRunMeta(runId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return textResult({ error: message, status: 404 }, true);
+        }
+        try {
+            const detail = await store.readRun(runId);
+            const stage = detail.stages.find((s) => s.stage_id === stageId);
+            if (!stage) {
+                return textResult({ error: `Stage not found: ${stageId}`, status: 404 }, true);
+            }
+            const events = await store.listStageEvents(runId, stageId, attempt);
+            return textResult({ runId, stageId, attempt, events });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = /not found|no such/i.test(message);
+            return textResult({ error: message, status: notFound ? 404 : 500 }, true);
+        }
+    });
+    server.registerTool("get_envelope", {
+        description: "Read the full StageEnvelope for a run stage (latest attempt). Returns 404 when absent.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        try {
+            await store.readRunMeta(runId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return textResult({ error: message, status: 404 }, true);
+        }
+        try {
+            const detail = await store.readRun(runId);
+            if (!detail.stages.some((s) => s.stage_id === stageId)) {
+                return textResult({ error: `Stage not found: ${stageId}`, status: 404 }, true);
+            }
+            const envelope = await store.readEnvelope(runId, stageId);
+            return textResult({ runId, stageId, envelope });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = /not found|no such|envelope/i.test(message);
+            return textResult({ error: message, status: notFound ? 404 : 500 }, true);
+        }
+    });
+    server.registerTool("retry_stage", {
+        description: "Retry a failed stage (same as POST .../retry). Waiting stages cannot be retried — answer them with answer_gate instead.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        const result = await manager.retryStage(runId, stageId);
+        if (!result.ok) {
+            return textResult({ ...mapRetryStageFailure(result), status: result.status }, true);
+        }
+        return textResult({
+            runId: result.runId,
+            stageId: result.stageId,
+            attemptIndex: result.attemptIndex,
+        });
+    });
+    server.registerTool("abandon_stage", {
+        description: "Abandon a running stage (marks it failed/interrupted). Does not dismiss HITL — waiting stages return 409; answer them with answer_gate. There is no run-level cancel tool.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        const result = await manager.abandonStage(runId, stageId);
+        if (!result.ok) {
+            const fail = result;
+            return textResult({ error: fail.reason, status: fail.status }, true);
+        }
+        return textResult({
+            ok: true,
+            runId: result.runId,
+            stageId: result.stageId,
+        });
+    });
+    server.registerTool("rerun", {
+        description: "Start a new run from a completed or failed run's pipeline/task locators. Returns { runId } for the new run.",
+        inputSchema: z.object({
+            runId: z.string(),
+        }),
+    }, async ({ runId }) => {
+        const result = await manager.rerun(runId);
+        if (!result.ok) {
+            return textResult({
+                ...mapStartFailure(result),
+                ...(result.status !== undefined ? { status: result.status } : {}),
+            }, true);
+        }
+        return textResult({ runId: result.runId });
+    });
+}

package/dist/mcp/deps.d.ts

@@ -0,0 +1,11 @@
+import type { RunStore } from "../runstore/port.js";
+import type { RunChangeBus } from "../runtime/runChangeBus.js";
+import type { RunManager } from "../runtime/runManager.js";
+export type McpToolDeps = {
+    manager: RunManager;
+    store: RunStore;
+    cwd: string;
+};
+export type McpHttpDeps = McpToolDeps & {
+    runChangeBus: RunChangeBus;
+};

package/dist/mcp/deps.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/projectRun.d.ts

@@ -1,40 +1 @@
-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";
-export type McpStageProjection = {
-    stage_id: string;
-    status: StageSnapshot["status"];
-    envelope: {
-        status: StageEnvelope["status"];
-        summary: string;
-        artifacts: string[];
-        payload?: Record<string, unknown>;
-    } | null;
-    artifacts: string[];
-    last_at?: string;
-    pending_prompt?: AskOperatorPrompt;
-};
-export type McpRunProjection = {
-    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: McpStageProjection[];
-    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 projectRunForMcp(detail: RunDetail): McpRunProjection;
+export { projectRun as projectRunForMcp, type RunProjection as McpRunProjection, type StageProjection as McpStageProjection, } from "../projection/projectRun.js";

package/dist/mcp/projectRun.js

@@ -1,64 +1 @@
-export function projectRunForMcp(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 }
-                        : {}),
-                }
-                : null,
-            artifacts: stage.artifacts,
-            last_at: stage.last_at,
-            ...(stage.pending_prompt
-                ? { pending_prompt: stage.pending_prompt }
-                : {}),
-        })),
-    };
-}
+export { projectRun as projectRunForMcp, } from "../projection/projectRun.js";

package/dist/mcp/resources.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare const RUN_RESOURCE_URI_TEMPLATE = "stageflow://runs/{runId}";
+export declare function runResourceUri(runId: string): string;
+export declare function registerRunResources(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/resources.js

@@ -0,0 +1,45 @@
+import { ResourceNotFoundError, ResourceTemplate, } from "@modelcontextprotocol/server";
+import { projectRunForMcp } from "./projectRun.js";
+export const RUN_RESOURCE_URI_TEMPLATE = "stageflow://runs/{runId}";
+export function runResourceUri(runId) {
+    return `stageflow://runs/${runId}`;
+}
+export function registerRunResources(server, deps) {
+    const { store } = deps;
+    server.registerResource("run", new ResourceTemplate(RUN_RESOURCE_URI_TEMPLATE, {
+        list: async () => {
+            const runs = await store.listRuns();
+            return {
+                resources: runs.map((run) => ({
+                    uri: runResourceUri(run.run_id),
+                    name: run.run_id,
+                    mimeType: "application/json",
+                })),
+            };
+        },
+    }), {
+        description: "Lean Stageflow run projection (same shape as get_run; no stage events)",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const runId = variables.runId;
+        if (typeof runId !== "string" || runId.length === 0) {
+            throw new ResourceNotFoundError(uri.href);
+        }
+        try {
+            const detail = await store.readRun(runId);
+            const projected = projectRunForMcp(detail);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "application/json",
+                        text: JSON.stringify(projected, null, 2),
+                    },
+                ],
+            };
+        }
+        catch {
+            throw new ResourceNotFoundError(uri.href);
+        }
+    });
+}

package/dist/mcp/server.d.ts

@@ -1,7 +1,20 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { McpServer } from "@modelcontextprotocol/server";
-import { type McpToolDeps } from "./tools.js";
-export type { McpToolDeps };
+import type { McpHttpDeps, McpToolDeps } from "./deps.js";
+export type { McpHttpDeps, McpToolDeps };
+export type McpHttpOptions = {
+    /** Test/debug escape hatch — per-request create/teardown (no sessions). */
+    mcpStateless?: boolean;
+};
 export declare function createStageflowMcpServer(deps: McpToolDeps): McpServer;
-/** Stateless Streamable HTTP: new server + transport per request. */
+export type McpHttpHandler = {
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    close: () => Promise<void>;
+};
+/** Stateful Streamable HTTP session host (product default) or stateless escape hatch. */
+export declare function createMcpHttpHandler(deps: McpHttpDeps, options?: McpHttpOptions): McpHttpHandler;
 export declare function handleMcpHttpRequest(req: IncomingMessage, res: ServerResponse, deps: McpToolDeps): Promise<void>;
+export declare function resolveMcpStateless(options?: {
+    mcpStateless?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): boolean;

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;