stageflow 0.12.0 → 0.13.0

package/dist/agent/piIsolatedMcpProbe.js

@@ -0,0 +1,292 @@
+import { StageMcpError, resolveStageMcpServers, } from "../config/resolveStageMcpServers.js";
+import * as piIsolatedMcp from "./piIsolatedMcp.js";
+export const PROJECT_MCP_PROBE_TIMEOUT_MS = 30_000;
+const MCP_STATUS_EVENT = "pi-mcp-adapter/status/v1";
+function scrub(message, secrets) {
+    let out = message;
+    for (const secret of secrets) {
+        if (secret.length === 0)
+            continue;
+        out = out.split(secret).join("[redacted]");
+    }
+    return out;
+}
+function collectInterpolatedSecrets(entry) {
+    const secrets = [];
+    for (const field of ["env", "headers"]) {
+        const value = entry[field];
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            continue;
+        }
+        for (const item of Object.values(value)) {
+            if (typeof item === "string" && item.length > 0) {
+                secrets.push(item);
+            }
+        }
+    }
+    return secrets;
+}
+function catalogErrorResult(name, err) {
+    if (!(err instanceof StageMcpError))
+        return undefined;
+    if (err.code === "unresolved_var") {
+        return { name, status: "unresolved_var", error: err.message };
+    }
+    if (err.code === "missing_catalog") {
+        return { name, status: "missing_catalog" };
+    }
+    if (err.code === "invalid_config" ||
+        err.code === "reserved_name" ||
+        err.code === "unknown_server") {
+        return { name, status: "invalid_config" };
+    }
+    return undefined;
+}
+function asStatusServers(data) {
+    if (data === null || typeof data !== "object")
+        return undefined;
+    const servers = data.servers;
+    if (!Array.isArray(servers))
+        return undefined;
+    const parsed = [];
+    for (const entry of servers) {
+        if (entry === null || typeof entry !== "object")
+            continue;
+        const name = entry.name;
+        const status = entry.status;
+        if (typeof name === "string" && typeof status === "string") {
+            parsed.push({ name, status });
+        }
+    }
+    return parsed;
+}
+function mapRuntimeStatus(status) {
+    if (status === "connected" || status === "cached")
+        return "connected";
+    if (status === "needs-auth")
+        return "needs_auth";
+    if (status === "failed" || status === "disabled")
+        return "connect_failed";
+    return undefined;
+}
+function createProbeExtensionApi(eventBus) {
+    const handlers = new Map();
+    const api = {
+        events: eventBus,
+        on(event, handler) {
+            const list = handlers.get(event) ?? [];
+            list.push(handler);
+            handlers.set(event, list);
+        },
+        registerTool() { },
+        registerCommand() { },
+        registerShortcut() { },
+        registerFlag() { },
+        getFlag() {
+            return undefined;
+        },
+        registerMessageRenderer() { },
+        registerMarkdownTransformer() { },
+        registerEntryRenderer() { },
+        sendMessage() { },
+        sendUserMessage() { },
+        appendEntry() { },
+        setSessionName() { },
+        getSessionName() {
+            return undefined;
+        },
+        setLabel() { },
+        async exec() {
+            return { code: 0, stdout: "", stderr: "" };
+        },
+        getActiveTools() {
+            return [];
+        },
+        setActiveTools() { },
+        getAllTools() {
+            return [];
+        },
+    };
+    async function emit(event, ...args) {
+        for (const handler of handlers.get(event) ?? []) {
+            await handler(...args);
+        }
+    }
+    return {
+        api: api,
+        emitSessionStart(cwd) {
+            void emit("session_start", {}, { mode: "print", hasUI: false, cwd });
+        },
+        emitSessionShutdown() {
+            return emit("session_shutdown", {});
+        },
+    };
+}
+function instantiateProbeFactories(attached, projectRoot) {
+    const factories = attached.extensionFactories ?? [];
+    const eventBus = attached.eventBus;
+    if (factories.length === 0 || eventBus === undefined) {
+        return async () => { };
+    }
+    const probeApi = createProbeExtensionApi(eventBus);
+    for (const ext of factories) {
+        const factory = typeof ext === "function" ? ext : ext.factory;
+        factory(probeApi.api);
+    }
+    probeApi.emitSessionStart(projectRoot);
+    return () => probeApi.emitSessionShutdown();
+}
+function mapConnectingError(err, aborted) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (aborted || /cancelled/i.test(message)) {
+        return { kind: "cancelled" };
+    }
+    if (/needs-auth/.test(message)) {
+        return { kind: "mapped", status: "needs_auth" };
+    }
+    return {
+        kind: "mapped",
+        status: "connect_failed",
+        error: message.length > 0 ? message : undefined,
+    };
+}
+async function waitForProbeStatus(eventBus, serverName, connecting, options) {
+    if (options.signal?.aborted) {
+        return { kind: "cancelled" };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let unsubscribe;
+        let timer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            unsubscribe?.();
+            if (timer !== undefined)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        const onAbort = () => finish({ kind: "cancelled" });
+        const consider = (data) => {
+            const servers = asStatusServers(data);
+            if (servers === undefined)
+                return;
+            const entry = servers.find((server) => server.name === serverName);
+            if (entry === undefined)
+                return;
+            const mapped = mapRuntimeStatus(entry.status);
+            if (mapped === undefined)
+                return;
+            if (mapped === "connect_failed") {
+                finish({
+                    kind: "mapped",
+                    status: "connect_failed",
+                    error: `MCP server "${serverName}" failed to connect (status: ${entry.status})`,
+                });
+                return;
+            }
+            finish({ kind: "mapped", status: mapped });
+        };
+        const handler = (data) => consider(data);
+        const maybeUnsub = eventBus.on(MCP_STATUS_EVENT, handler);
+        unsubscribe = typeof maybeUnsub === "function" ? maybeUnsub : undefined;
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        void (connecting ?? Promise.resolve()).then(() => finish({ kind: "mapped", status: "connected" }), (err) => finish(mapConnectingError(err, options.signal?.aborted === true)));
+        timer = setTimeout(() => {
+            finish({
+                kind: "mapped",
+                status: "connect_failed",
+                error: `MCP server "${serverName}" failed to connect (status: timed out)`,
+            });
+        }, options.timeoutMs);
+    });
+}
+export async function probeProjectMcpServer(options) {
+    const name = options.name;
+    const timeoutMs = options.timeoutMs ?? PROJECT_MCP_PROBE_TIMEOUT_MS;
+    const env = options.env ?? process.env;
+    if (options.signal?.aborted) {
+        return { name, status: "cancelled" };
+    }
+    let snapshot;
+    try {
+        snapshot = await resolveStageMcpServers({
+            projectRoot: options.projectRoot,
+            allowlist: [name],
+            env,
+        });
+    }
+    catch (err) {
+        return (catalogErrorResult(name, err) ?? {
+            name,
+            status: "invalid_config",
+        });
+    }
+    const resolved = snapshot[name];
+    if (resolved === undefined) {
+        return { name, status: "invalid_config" };
+    }
+    const secrets = collectInterpolatedSecrets(resolved);
+    let attached;
+    let shutdownFactories;
+    const dispose = async () => {
+        if (attached?.connecting !== undefined) {
+            void attached.connecting.then(() => undefined, () => undefined);
+        }
+        attached?.cancel?.();
+        if (shutdownFactories !== undefined) {
+            const stop = shutdownFactories;
+            shutdownFactories = undefined;
+            await stop();
+        }
+    };
+    try {
+        if (options.signal?.aborted) {
+            return { name, status: "cancelled" };
+        }
+        attached = await piIsolatedMcp.attachIsolatedMcp(snapshot, {
+            timeoutMs,
+            lifecycle: "eager",
+        });
+        if (attached.eventBus === undefined) {
+            return { name, status: "invalid_config" };
+        }
+        shutdownFactories = instantiateProbeFactories(attached, options.projectRoot);
+        const waited = await waitForProbeStatus(attached.eventBus, name, attached.connecting, { timeoutMs, signal: options.signal });
+        if (waited.kind === "cancelled") {
+            return { name, status: "cancelled" };
+        }
+        if (waited.status === "connect_failed") {
+            return {
+                name,
+                status: "connect_failed",
+                ...(waited.error !== undefined
+                    ? { error: scrub(waited.error, secrets) }
+                    : {}),
+            };
+        }
+        return { name, status: waited.status };
+    }
+    catch (err) {
+        if (options.signal?.aborted) {
+            return { name, status: "cancelled" };
+        }
+        const catalog = catalogErrorResult(name, err);
+        if (catalog)
+            return catalog;
+        const message = err instanceof Error ? err.message : String(err);
+        if (/cancelled/i.test(message)) {
+            return { name, status: "cancelled" };
+        }
+        return {
+            name,
+            status: "connect_failed",
+            error: scrub(message, secrets),
+        };
+    }
+    finally {
+        await dispose();
+    }
+}

package/dist/agent/port.d.ts

@@ -5,6 +5,7 @@ import type { StageConfig } from "../types/stage.js";
 import type { FeedbackLoopConfig } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
 import type { StageActivityEvent } from "./activity.js";
+import type { ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import type { QaExchange } from "../hitl/qaTrail.js";
 /** Opaque to runtime; adapters interpret. */
@@ -52,6 +53,7 @@ export type StageRunInput = {
     priorEnvelopes?: StageEnvelope[];
     priorEnvelopesByStage?: Record<string, TerminalEnvelope | TerminalEnvelope[]>;
     timeoutMs?: number;
+    resolvedMcpServers?: ResolvedMcpServers;
     resumeToken?: StageResumeToken;
     /** Launch/session mode; omitted is treated as `"fresh"`. */
     sessionMode?: StageSessionMode;

package/dist/agent/port.js

@@ -46,4 +46,4 @@ export function createCompletedOnlyStageHandle(options) {
         },
     };
 }
-export const DEFAULT_STAGE_TIMEOUT_MS = 15 * 60 * 1000;
+export const DEFAULT_STAGE_TIMEOUT_MS = 60 * 60 * 1000;

package/dist/config/loadPipeline.js

@@ -100,6 +100,7 @@ async function loadPipelineFromPath(pipelinePath) {
         const stage = {
             ...stageOutcome.value,
             ...(entry.skill !== undefined ? { skill: entry.skill } : {}),
+            ...(entry.mcp !== undefined ? { mcp: entry.mcp } : {}),
         };
         stages.push(stage);
         stageSources[stageId] = { kind: "file", path: entry.body.absolutePath };

package/dist/config/loadStage.d.ts

@@ -1,5 +1,6 @@
 import { type StageConfig } from "../types/stage.js";
 import { type LoadOutcome } from "./loadOutcome.js";
+export declare function parseStageMcp(raw: unknown, label: string, stageId?: string): LoadOutcome<string[] | undefined>;
 export declare function loadStageFromObjectOutcome(raw: Record<string, unknown>, ctx: {
     entryId: string;
     declaringPath: string;

package/dist/config/loadStage.js

@@ -1,4 +1,5 @@
 import { parseAgentField } from "../agent/agentBackend.js";
+import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
 import { CLONE_ACTIONS } from "../types/forkChoice.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
 import { compilePayloadSchema } from "../envelope/payloadSchema.js";
@@ -91,6 +92,68 @@ function parseGateKinds(raw, label) {
     }
     return loadSuccess(kinds);
 }
+export function parseStageMcp(raw, label, stageId) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw)) {
+        return loadFailure([
+            {
+                code: "stage.invalid_mcp",
+                message: `Invalid stage ${label}: mcp must be an array of server names`,
+                category: "stage",
+                stageId,
+            },
+        ]);
+    }
+    const names = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (typeof item !== "string") {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp entries must be strings`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        const name = item.trim();
+        if (name === "") {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp entries must be non-empty strings`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        if (name === STAGEFLOW_MCP_SERVER_NAME) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp must not include reserved name "${STAGEFLOW_MCP_SERVER_NAME}"`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        if (seen.has(name)) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_mcp",
+                    message: `Invalid stage ${label}: mcp contains duplicate name "${name}"`,
+                    category: "stage",
+                    stageId,
+                },
+            ]);
+        }
+        seen.add(name);
+        names.push(name);
+    }
+    return loadSuccess(names);
+}
 function parseStageFields(raw, label, entryId) {
     if (typeof raw.system_prompt !== "string" ||
         typeof raw.model !== "string") {
@@ -223,6 +286,12 @@ function parseStageFields(raw, label, entryId) {
         }
         stage.skill = raw.skill.trim();
     }
+    const mcpOutcome = parseStageMcp(raw.mcp, label, entryId);
+    if (!mcpOutcome.ok)
+        return mcpOutcome;
+    if (mcpOutcome.value !== undefined) {
+        stage.mcp = mcpOutcome.value;
+    }
     const agentField = parseAgentField(raw.agent);
     if (!agentField.ok) {
         return loadFailure([

package/dist/config/normalizePipelineStageEntry.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parseStageMcp } from "./loadStage.js";
 import { BODY_KEYS, isAllowedPipelineStageEntryKey, } from "./pipelineStageKeys.js";
 import { parseExecutionPolicy } from "./parseCompletionContract.js";
 import { parsePipelineNeeds } from "./pipelineNeeds.js";
@@ -31,7 +32,7 @@ function extractBodyRaw(raw) {
     return body;
 }
 function hasBodyKey(raw) {
-    return Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill");
+    return Object.keys(raw).some((key) => BODY_KEYS.has(key) && key !== "skill" && key !== "mcp");
 }
 function readSkill(raw) {
     if (raw.skill === undefined)
@@ -96,6 +97,10 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             return skillOutcome;
         }
         const skill = skillOutcome?.ok ? skillOutcome.value : undefined;
+        const mcpOutcome = parseStageMcp(raw.mcp, `entry at index ${index} in ${declaringPath}`);
+        if (!mcpOutcome.ok)
+            return mcpOutcome;
+        const mcp = mcpOutcome.value;
         if (uses && hasBody) {
             return loadFailure([
                 {
@@ -220,6 +225,7 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 ? { replay_safe: raw.replay_safe }
                 : {}),
             ...(skill !== undefined ? { skill } : {}),
+            ...(mcp !== undefined ? { mcp } : {}),
         };
         const priorPath = normalized.find((e) => e.id === id)?.declaringPath;
         if (priorPath) {

package/dist/config/pipelineStageKeys.js

@@ -20,6 +20,7 @@ export const BODY_KEYS = new Set([
     "clone_actions",
     "timeout_ms",
     "skill",
+    "mcp",
 ]);
 export function isPipelineStageBodyKey(key) {
     return BODY_KEYS.has(key);

package/dist/config/resolveStageMcpServers.d.ts

@@ -0,0 +1,35 @@
+export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "connect_failed";
+export declare class StageMcpError extends Error {
+    readonly code: StageMcpErrorCode;
+    constructor(message: string, code: StageMcpErrorCode);
+}
+export type ResolvedMcpServerConfig = Record<string, unknown>;
+export type ResolvedMcpServers = Record<string, ResolvedMcpServerConfig>;
+export declare const MCP_CATALOG_FILENAME = ".mcp.json";
+export declare const STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV = "STAGEFLOW_STAGE_ARTIFACTS_DIR";
+export declare function stampStagePromptArtifactsDir(prompt: string, artifactsDir: string): string;
+export type McpCatalogServers = Record<string, Record<string, unknown>>;
+export type InspectedMcpCatalog = {
+    path: string;
+    servers: McpCatalogServers;
+};
+export declare function mcpCatalogPath(projectRoot: string): string;
+export declare function parseMcpCatalog(raw: string, catalogPath?: string): McpCatalogServers;
+export declare function loadMcpCatalog(projectRoot: string): Promise<InspectedMcpCatalog>;
+export type ProjectMcpCatalogTransport = "stdio" | "http";
+export type ProjectMcpCatalogEntry = {
+    name: string;
+    transport: ProjectMcpCatalogTransport;
+};
+export type ProjectMcpCatalogListStatus = "ok" | "missing_catalog" | "invalid_config";
+export type ProjectMcpCatalogList = {
+    status: ProjectMcpCatalogListStatus;
+    servers: ProjectMcpCatalogEntry[];
+};
+export declare function listProjectMcpCatalog(projectRoot: string): Promise<ProjectMcpCatalogList>;
+export declare function assertMcpAllowlistKnown(servers: McpCatalogServers, allowlist: readonly string[]): void;
+export declare function resolveStageMcpServers(options: {
+    projectRoot: string;
+    allowlist?: readonly string[];
+    env: NodeJS.ProcessEnv;
+}): Promise<ResolvedMcpServers>;