stageflow 0.3.0 → 0.8.0

package/dist/mcp/catalogTools.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { browseCatalog } from "../config/browseCatalog.js";
+import { loadPipeline } from "../config/loadPipeline.js";
+import { validateCatalog } from "../config/validateCatalog.js";
+import { projectRunForMcp } from "./projectRun.js";
+import { readRunArtifact } from "./readArtifact.js";
+import { textResult } from "./toolResults.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",
+});
+const runStatusSchema = z.enum(["created", "running", "succeeded", "failed"]);
+export function registerCatalogTools(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. Optional filters: status, since (ISO created_at lower bound), pipeline (id or path).",
+        inputSchema: z.object({
+            status: runStatusSchema.optional(),
+            since: z.string().optional(),
+            pipeline: z.string().optional(),
+        }),
+    }, async ({ status, since, pipeline }) => {
+        const filter = {};
+        if (status !== undefined)
+            filter.status = status;
+        if (since !== undefined) {
+            if (!Number.isFinite(Date.parse(since))) {
+                return textResult({ error: "since must be a valid date", status: 400 }, true);
+            }
+            filter.since = since;
+        }
+        if (pipeline !== undefined)
+            filter.pipeline = pipeline;
+        const runs = await store.listRuns(Object.keys(filter).length > 0 ? filter : undefined);
+        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, waiting_* / pending_prompt HITL fields, and envelope summary/payload/artifact paths (no events). Use list_stage_events / get_envelope for timelines and full envelopes.",
+        inputSchema: z.object({
+            runId: z.string(),
+        }),
+    }, 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);
+            return textResult({
+                error: message,
+                status: notFound ? 404 : 400,
+            }, true);
+        }
+    });
+    server.registerTool("validate", {
+        description: "Validate the project catalog (full), a pipeline path, or a task path. Returns ValidationResult JSON (ok, summary, findings).",
+        inputSchema: z.object({
+            pipeline: z.string().optional(),
+            task: z.string().optional(),
+            strict: z.boolean().optional(),
+        }),
+    }, async ({ pipeline, task, strict }) => {
+        try {
+            let scope = "full";
+            if (pipeline !== undefined && pipeline.trim())
+                scope = "pipeline";
+            else if (task !== undefined && task.trim())
+                scope = "task";
+            const result = await validateCatalog({
+                cwd,
+                scope,
+                ...(scope === "pipeline" ? { pipeline: pipeline.trim() } : {}),
+                ...(scope === "task" ? { task: task.trim() } : {}),
+                strict: strict ?? false,
+            });
+            return textResult(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return textResult({ error: message, status: 400 }, true);
+        }
+    });
+    server.registerTool("describe_pipeline", {
+        description: "Describe a pipeline DAG: stages with needs, fork, clonable, clone_cap, and gate_kinds. Input is a filesystem pipeline path (same as start_run).",
+        inputSchema: z.object({
+            pipeline: z.string(),
+        }),
+    }, async ({ pipeline }) => {
+        if (!pipeline.trim()) {
+            return textResult({ error: "pipeline is required", status: 400 }, true);
+        }
+        try {
+            const loaded = await loadPipeline(pipeline.trim(), { cwd });
+            const gateById = new Map(loaded.stages.map((s) => [s.id, s.gate_kinds]));
+            const stages = loaded.dag.nodes.map((node) => ({
+                id: node.id,
+                needs: node.needs,
+                ...(node.fork !== undefined ? { fork: node.fork } : {}),
+                ...(node.clonable !== undefined ? { clonable: node.clonable } : {}),
+                ...(node.clone_cap !== undefined ? { clone_cap: node.clone_cap } : {}),
+                ...(gateById.get(node.id) !== undefined
+                    ? { gate_kinds: gateById.get(node.id) }
+                    : {}),
+            }));
+            return textResult({
+                id: loaded.pipeline.id,
+                path: loaded.pipelinePath,
+                stages,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return textResult({ error: message, status: 404 }, true);
+        }
+    });
+}

package/dist/mcp/controlTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare function registerControlTools(server: McpServer, deps: McpToolDeps): void;

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;