stageflow 0.12.0 → 0.15.0

package/README.md

@@ -193,6 +193,8 @@ Host MCP via `sf ui` or `sf mcp` at `http://127.0.0.1:3847/mcp` (URL printed on
 
 HITL-aware tools include `wait_run`, `answer_gate`, and `list_waiting`. Full tool list: [docs/mcp.md](docs/mcp.md).
 
+Stages use project `.mcp.json` plus stage `mcp` names. See [YAML catalog — Stage MCP](docs/yaml-catalog.md#stage-mcp).
+
 ## Stageflow vs Conductor
 
 Both projects address multi-step agent workflows. They differ in orchestration model and runtime.
@@ -218,6 +220,9 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 | [plan-review](examples/plan-review/) | Multi-stage with operator gate — SDLC-style **example** |
 | [conditional-fork](examples/conditional-fork/) | Exclusive fork routing with operator branch choice |
 | [clonable-fanout](examples/clonable-fanout/) | Clone one successor N times, then join |
+| [stage-mcp](examples/stage-mcp/) | Stage MCP via project `.mcp.json` and a local echo fixture |
+| [playwright-mcp](examples/playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) |
+| [context7-mcp](examples/context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) |
 | [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
 | [ci-validate](examples/ci-validate/) | Strict validate in CI |
 
@@ -241,7 +246,6 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
 | [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
 | [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |
-| [docs/compare-conductor.md](docs/compare-conductor.md) | Positioning deep dive |
 
 ## Develop from source
 

package/dist/agent/claudeAdapter.js

@@ -46,6 +46,7 @@ import { createClaudeActivityMapper } from "./claudeActivity.js";
 import { composeStageUserPrompt } from "./piAdapter.js";
 import { claudeSessionMarkerPath, clearClaudeSessionMarker, readClaudeSessionMarker, writeClaudeSessionMarker, } from "./claudeSession.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen, runtimeStageId, } from "./port.js";
+import { StageMcpError } from "../config/resolveStageMcpServers.js";
 /** Built-in tool allowlist, mirroring Pi's sealed-session base set (read/bash/write/edit). */
 const CLAUDE_BUILTIN_TOOLS = ["Read", "Write", "Edit", "Bash"];
 function resolveClaudeModel(stageModel) {
@@ -87,6 +88,20 @@ function resultFromCapture(capture) {
     }
     return { ok: true, envelope: capture.envelope };
 }
+function failedPassedMcpConnect(resolved, listed) {
+    const names = Object.keys(resolved ?? {});
+    if (names.length === 0)
+        return undefined;
+    const byName = new Map(listed.map((entry) => [entry.name, entry]));
+    for (const name of names) {
+        const entry = byName.get(name);
+        if (entry?.status === "connected")
+            continue;
+        const statusOrError = entry?.error ?? entry?.status ?? "missing";
+        return new StageMcpError(`MCP server "${name}" failed to connect (status: ${statusOrError})`, "connect_failed");
+    }
+    return undefined;
+}
 async function* singleUserMessage(text) {
     yield {
         type: "user",
@@ -131,6 +146,10 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
                 }
                 : {}),
         });
+        const passedServers = Object.fromEntries(Object.entries(input.resolvedMcpServers ?? {}).map(([name, config]) => [
+            name,
+            { ...config, alwaysLoad: true },
+        ]));
         const stream = query({
             prompt: singleUserMessage(promptText),
             options: {
@@ -140,10 +159,11 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
                 systemPrompt: { type: "custom", prompt: input.stage.system_prompt },
                 settingSources: [],
                 tools: CLAUDE_BUILTIN_TOOLS,
-                mcpServers: { [STAGEFLOW_MCP_SERVER_NAME]: mcpServer },
+                mcpServers: { [STAGEFLOW_MCP_SERVER_NAME]: mcpServer, ...passedServers },
                 permissionMode: "bypassPermissions",
                 allowDangerouslySkipPermissions: true,
                 persistSession: true,
+                strictMcpConfig: true,
                 ...(resumeSessionId !== undefined ? { resume: resumeSessionId } : {}),
             },
         });
@@ -154,6 +174,16 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
             if (message.type === "system" && message.subtype === "init") {
                 sessionId = message.session_id;
                 await writeClaudeSessionMarker(markerPath, { sessionId: message.session_id });
+                const connectError = failedPassedMcpConnect(input.resolvedMcpServers, message.mcp_servers);
+                if (connectError) {
+                    try {
+                        await stream.interrupt();
+                    }
+                    catch {
+                        // best-effort backstop; a natural stop may have already ended the turn
+                    }
+                    return { kind: "completed", result: { ok: false, reason: connectError.message } };
+                }
             }
             if (message.type === "user" &&
                 (emitCapture.envelope !== undefined || askCapture.prompt !== undefined)) {

package/dist/agent/piAdapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type EventBus, type InlineExtension, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
@@ -72,9 +72,9 @@ export declare function composeFeedbackResumePrompt(input: StageRunInput): strin
  * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
  * and APPEND_SYSTEM.md. Stages must not inherit that context.
  *
- * `additionalExtensionPaths` is the only way extensions enter a sealed stage
- * (used by StageProviderSupport implementations). With `noExtensions: true`,
- * discovered global/project packages stay out; only allowlisted paths load.
+ * `additionalExtensionPaths` is the Cursor/provider seam. `extensionFactories`
+ * is the isolated MCP seam. With `noExtensions: true`, discovered
+ * global/project packages stay out; only those allowlists load.
  * `additionalSkillPaths` is the matching allowlist for one named skill.
  */
 export declare function createSealedResourceLoader(options: {
@@ -84,6 +84,8 @@ export declare function createSealedResourceLoader(options: {
     systemPrompt: string;
     additionalExtensionPaths?: string[];
     additionalSkillPaths?: string[];
+    extensionFactories?: InlineExtension[];
+    eventBus?: EventBus;
 }): DefaultResourceLoader;
 /** Stable Pi session JSONL path under the run workspace stage dir. */
 export declare function stageSessionFilePath(roots: Pick<StageRoots, "runWorkspaceDir" | "attempt">, stageId: string): string;

package/dist/agent/piAdapter.js

@@ -33,6 +33,8 @@ import { existsSync } from "node:fs";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createAgentSession, DefaultResourceLoader, defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { StageMcpError } from "../config/resolveStageMcpServers.js";
+import { attachIsolatedMcp, STAGEFLOW_PI_MCP_EXTENSION_NAME, } from "./piIsolatedMcp.js";
 import { isAdvancingEnvelope } from "../envelope/check.js";
 import { formatFeedbackLoopContext } from "../prompt/feedbackLoopContext.js";
 import { formatPriorEnvelope } from "../prompt/priorEnvelope.js";
@@ -388,10 +390,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             if (successor.cloneInputSchema === undefined) {
                 return header;
             }
-            return `${header}\n  Assignment schema (clone_input_schema):\n${JSON.stringify(successor.cloneInputSchema, null, 2)}`;
+            return `${header}\n  Assignment schema (io.input.schema):\n${JSON.stringify(successor.cloneInputSchema, null, 2)}`;
         });
         emitHint += `\nClonable successors — emit clone_forks covering each of these ids exactly once:\n${successorLines.join("\n")}`;
-        emitHint += `\nEach once or fanout envelope is a full StageEnvelope — it requires status ("success" or "failure"), summary (non-empty string), and artifacts (array of strings). clone_input_schema fields belong in envelope.payload, not at the top level of the clone_forks item.`;
+        emitHint += `\nEach once or fanout envelope is a full StageEnvelope — it requires status ("success" or "failure"), summary (non-empty string), and artifacts (array of strings). io.input.schema fields belong in envelope.payload, not at the top level of the clone_forks item.`;
         emitHint += `\nAllowed clone actions: ${allowedActions.join(", ")}`;
     }
     if (input.feedbackLoopEmitContext !== undefined) {
@@ -429,6 +431,9 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
         `Goal: ${input.task.goal}`,
         input.task.context ? `Context: ${input.task.context}` : "",
         input.task.constraints ? `Constraints: ${input.task.constraints}` : "",
+        input.task.input !== undefined
+            ? `Input: ${JSON.stringify(input.task.input, null, 2)}`
+            : "",
         formatPriorEnvelope(input.priorEnvelope, input.priorEnvelopes, input.priorEnvelopesByStage),
         input.feedbackLoopContext !== undefined
             ? formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode)
@@ -464,9 +469,9 @@ export function composeFeedbackResumePrompt(input) {
  * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
  * and APPEND_SYSTEM.md. Stages must not inherit that context.
  *
- * `additionalExtensionPaths` is the only way extensions enter a sealed stage
- * (used by StageProviderSupport implementations). With `noExtensions: true`,
- * discovered global/project packages stay out; only allowlisted paths load.
+ * `additionalExtensionPaths` is the Cursor/provider seam. `extensionFactories`
+ * is the isolated MCP seam. With `noExtensions: true`, discovered
+ * global/project packages stay out; only those allowlists load.
  * `additionalSkillPaths` is the matching allowlist for one named skill.
  */
 export function createSealedResourceLoader(options) {
@@ -478,6 +483,10 @@ export function createSealedResourceLoader(options) {
         appendSystemPromptOverride: () => [],
         additionalExtensionPaths: options.additionalExtensionPaths,
         additionalSkillPaths: options.additionalSkillPaths,
+        ...(options.extensionFactories !== undefined
+            ? { extensionFactories: options.extensionFactories }
+            : {}),
+        ...(options.eventBus !== undefined ? { eventBus: options.eventBus } : {}),
         noContextFiles: true,
         noExtensions: true,
         noSkills: true,
@@ -485,6 +494,16 @@ export function createSealedResourceLoader(options) {
         noThemes: true,
     });
 }
+function collectMcpExtensionToolNames(loader) {
+    const inlinePath = `<inline:${STAGEFLOW_PI_MCP_EXTENSION_NAME}>`;
+    const names = [];
+    for (const ext of loader.getExtensions().extensions) {
+        if (ext.path !== inlinePath)
+            continue;
+        names.push(...ext.tools.keys());
+    }
+    return names;
+}
 async function shutdownSession(session) {
     if (!session) {
         return;
@@ -770,6 +789,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         additionalExtensionPaths.push(...prepared.extensionPaths);
         restoreProvider = prepared.restore;
     }
+    let attached;
     try {
         const modelRuntime = await ModelRuntime.create(roots.authPath
             ? {
@@ -785,6 +805,12 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         const settingsManager = SettingsManager.inMemory({
             compaction: { enabled: false },
         });
+        attached = await attachIsolatedMcp(input.resolvedMcpServers);
+        const failAfterAttach = (reason) => {
+            attached?.cancel?.();
+            restoreProvider?.();
+            return { ok: false, reason };
+        };
         const loader = createSealedResourceLoader({
             cwd: roots.cwd,
             agentDir: roots.agentDir,
@@ -794,47 +820,43 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             ...(input.skillFilePath !== undefined
                 ? { additionalSkillPaths: [input.skillFilePath] }
                 : {}),
+            ...(attached.extensionFactories !== undefined
+                ? { extensionFactories: attached.extensionFactories }
+                : {}),
+            ...(attached.eventBus !== undefined ? { eventBus: attached.eventBus } : {}),
         });
         await loader.reload();
         const extensionErrors = loader.getExtensions().errors;
         if (extensionErrors.length > 0) {
-            restoreProvider?.();
-            return {
-                ok: false,
-                reason: `Failed to load Pi extension(s): ${extensionErrors
-                    .map((e) => `${e.path}: ${e.error}`)
-                    .join("; ")}`,
-            };
+            return failAfterAttach(`Failed to load Pi extension(s): ${extensionErrors
+                .map((e) => `${e.path}: ${e.error}`)
+                .join("; ")}`);
         }
         const skillDiagnostics = loader
             .getSkills()
             .diagnostics.filter((d) => d.type === "error" || d.type === "collision");
         if (skillDiagnostics.length > 0) {
-            restoreProvider?.();
-            return {
-                ok: false,
-                reason: `Failed to load skill(s): ${skillDiagnostics
-                    .map((d) => (d.path !== undefined ? `${d.path}: ${d.message}` : d.message))
-                    .join("; ")}`,
-            };
+            return failAfterAttach(`Failed to load skill(s): ${skillDiagnostics
+                .map((d) => (d.path !== undefined ? `${d.path}: ${d.message}` : d.message))
+                .join("; ")}`);
         }
         if (input.stage.skill !== undefined &&
             !loader.getSkills().skills.some((skill) => skill.name === input.stage.skill)) {
-            restoreProvider?.();
-            return {
-                ok: false,
-                reason: `Skill "${input.stage.skill}" is not installed`,
-            };
+            return failAfterAttach(`Skill "${input.stage.skill}" is not installed`);
         }
         const customTools = askTool
             ? [emitTool, askTool, artifactTool]
             : [emitTool, artifactTool];
+        const tools = resolveStageToolNames(emitDef.name, artifactDef.name, askDef?.name ?? "ask_operator", gateKinds);
+        if (attached.extensionFactories !== undefined) {
+            tools.push(...collectMcpExtensionToolNames(loader));
+        }
         return {
             sessionManager,
             modelRuntime,
             settingsManager,
             loader,
-            tools: resolveStageToolNames(emitDef.name, artifactDef.name, askDef?.name ?? "ask_operator", gateKinds),
+            tools,
             customTools,
             emitDefName: emitDef.name,
             ...(askDef ? { askOperatorDefName: askDef.name } : {}),
@@ -843,10 +865,16 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             restoreProvider,
             capture,
             askWaitChannel,
+            connecting: attached.connecting,
+            cancelConnecting: attached.cancel,
         };
     }
     catch (err) {
+        attached?.cancel?.();
         restoreProvider?.();
+        if (err instanceof StageMcpError) {
+            return { ok: false, reason: err.message };
+        }
         throw err;
     }
 }
@@ -886,6 +914,9 @@ export async function reconstructStageSessionForAnswer(input, answer) {
         });
         session = created.session;
         await session.bindExtensions({});
+        if (wiring.connecting !== undefined) {
+            await wiring.connecting;
+        }
         const resolved = resolveCliModel({
             cliModel: input.stage.model,
             modelRuntime: wiring.modelRuntime,
@@ -913,6 +944,7 @@ export async function reconstructStageSessionForAnswer(input, answer) {
         };
     }
     catch (err) {
+        wiring.cancelConnecting?.();
         await shutdownSession(session);
         wiring.restoreProvider?.();
         if (err instanceof StageSessionReconstructError)
@@ -934,7 +966,20 @@ async function bindStageSession(input, sessionManager, wiring) {
     });
     const session = created.session;
     ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
-    await session.bindExtensions({});
+    try {
+        await session.bindExtensions({});
+        if (wiring.connecting !== undefined) {
+            await wiring.connecting;
+        }
+    }
+    catch (err) {
+        wiring.cancelConnecting?.();
+        await shutdownSession(session);
+        if (err instanceof StageMcpError) {
+            return { ok: false, reason: err.message };
+        }
+        throw err;
+    }
     const resolved = resolveCliModel({
         cliModel: input.stage.model,
         modelRuntime: wiring.modelRuntime,

package/dist/agent/piIsolatedMcp.d.ts

@@ -0,0 +1,23 @@
+import { type EventBus, type InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
+export declare const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
+type IsolatedMcpServerEntry = Record<string, unknown> & {
+    lifecycle: "lazy" | "eager";
+    directTools: true;
+};
+export type IsolatedMcpAttachOptions = {
+    timeoutMs?: number;
+    lifecycle?: IsolatedMcpServerEntry["lifecycle"];
+};
+export type IsolatedMcpAttach = {
+    extensionFactories: InlineExtension[] | undefined;
+    eventBus: EventBus | undefined;
+    connecting: Promise<void> | undefined;
+    cancel?: () => void;
+};
+export declare function emitIsolatedMcpStatus(eventBus: EventBus, servers: ReadonlyArray<{
+    name: string;
+    status: string;
+}>): void;
+export declare function attachIsolatedMcp(snapshot?: ResolvedMcpServers, options?: IsolatedMcpAttachOptions): Promise<IsolatedMcpAttach>;
+export {};

package/dist/agent/piIsolatedMcp.js

@@ -0,0 +1,223 @@
+import { createEventBus, } from "@earendil-works/pi-coding-agent";
+import { StageMcpError, } from "../config/resolveStageMcpServers.js";
+export const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
+const MCP_STATUS_EVENT = "pi-mcp-adapter/status/v1";
+const DEFAULT_ISOLATED_MCP_CONNECT_TIMEOUT_MS = 5_000;
+const STATUS_POLL_MS = 50;
+const PI_MCP_ADAPTER_SPEC = "pi-mcp-adapter";
+const ISOLATED_MCP_SETTINGS = {
+    directTools: true,
+    elicitation: false,
+    hostConfigDiscovery: "off",
+};
+const SUCCESS_STATUSES = new Set([
+    "connected",
+    "cached",
+]);
+const FAILURE_STATUSES = new Set([
+    "failed",
+    "needs-auth",
+    "disabled",
+]);
+const EMPTY_ATTACH = {
+    extensionFactories: undefined,
+    eventBus: undefined,
+    connecting: undefined,
+};
+let cachedCreateMcpAdapter;
+function toIsolatedMcpConfig(snapshot, lifecycle = "lazy") {
+    const mcpServers = {};
+    for (const [name, entry] of Object.entries(snapshot)) {
+        const isolated = {
+            ...entry,
+            lifecycle,
+            directTools: true,
+        };
+        if (typeof entry.cwd === "string") {
+            isolated.cwd = entry.cwd;
+        }
+        mcpServers[name] = isolated;
+    }
+    return {
+        mcpServers,
+        settings: { ...ISOLATED_MCP_SETTINGS },
+    };
+}
+async function loadCreateMcpAdapter() {
+    if (cachedCreateMcpAdapter !== undefined) {
+        return cachedCreateMcpAdapter;
+    }
+    try {
+        const mod = (await import(PI_MCP_ADAPTER_SPEC));
+        if (typeof mod.createMcpAdapter === "function") {
+            cachedCreateMcpAdapter = mod.createMcpAdapter;
+            return cachedCreateMcpAdapter;
+        }
+    }
+    catch {
+        // Node does not type-strip .ts under node_modules.
+    }
+    const { createJiti } = await import("jiti/static");
+    const jiti = createJiti(import.meta.url);
+    const mod = (await jiti.import(PI_MCP_ADAPTER_SPEC));
+    cachedCreateMcpAdapter = mod.createMcpAdapter;
+    return cachedCreateMcpAdapter;
+}
+function isRuntimeStatus(value) {
+    return (value === "connected" ||
+        value === "cached" ||
+        value === "failed" ||
+        value === "needs-auth" ||
+        value === "not-connected" ||
+        value === "disabled");
+}
+function asIsolatedMcpStatusSnapshot(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")
+            continue;
+        if (!isRuntimeStatus(status))
+            continue;
+        parsed.push({ name, status });
+    }
+    return { servers: parsed };
+}
+function mcpStatusSourceFromEvents(events) {
+    return {
+        subscribe(listener) {
+            const handler = (data) => {
+                const snapshot = asIsolatedMcpStatusSnapshot(data);
+                if (snapshot)
+                    listener(snapshot);
+            };
+            const unsubscribe = events.on(MCP_STATUS_EVENT, handler);
+            if (typeof unsubscribe === "function")
+                return unsubscribe;
+            return () => {
+                events.off?.(MCP_STATUS_EVENT, handler);
+            };
+        },
+    };
+}
+function connectFailed(name, status) {
+    return new StageMcpError(`MCP server "${name}" failed to connect (status: ${status})`, "connect_failed");
+}
+function timeoutError(pendingNames) {
+    if (pendingNames.length === 1) {
+        return connectFailed(pendingNames[0], "timed out");
+    }
+    const listed = pendingNames.map((name) => `"${name}"`).join(", ");
+    return new StageMcpError(`MCP servers ${listed} failed to connect (status: timed out)`, "connect_failed");
+}
+function evaluateConnectStatus(serverNames, snapshot) {
+    if (snapshot === undefined) {
+        return { kind: "wait", pending: [...serverNames] };
+    }
+    const byName = new Map(snapshot.servers.map((entry) => [entry.name, entry]));
+    const pending = [];
+    for (const name of serverNames) {
+        const entry = byName.get(name);
+        if (entry === undefined || entry.status === "not-connected") {
+            pending.push(name);
+            continue;
+        }
+        if (FAILURE_STATUSES.has(entry.status)) {
+            return { kind: "fail", name, status: entry.status };
+        }
+        if (!SUCCESS_STATUSES.has(entry.status)) {
+            pending.push(name);
+        }
+    }
+    if (pending.length > 0) {
+        return { kind: "wait", pending };
+    }
+    return { kind: "ok" };
+}
+function waitForIsolatedMcpConnect(snapshot, source, options) {
+    const serverNames = Object.keys(snapshot);
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_ISOLATED_MCP_CONNECT_TIMEOUT_MS;
+    let lastSnapshot = source.read?.();
+    let finish = () => { };
+    const connecting = new Promise((resolve, reject) => {
+        let settled = false;
+        let unsubscribe;
+        let poll;
+        let timer;
+        finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            unsubscribe?.();
+            if (poll !== undefined)
+                clearInterval(poll);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const consider = (next) => {
+            if (next !== undefined)
+                lastSnapshot = next;
+            const result = evaluateConnectStatus(serverNames, lastSnapshot);
+            if (result.kind === "ok") {
+                finish();
+                return;
+            }
+            if (result.kind === "fail") {
+                finish(connectFailed(result.name, result.status));
+            }
+        };
+        consider(lastSnapshot);
+        if (settled)
+            return;
+        unsubscribe = source.subscribe?.((next) => consider(next));
+        consider(source.read?.());
+        if (settled)
+            return;
+        if (source.read) {
+            poll = setInterval(() => consider(source.read?.()), STATUS_POLL_MS);
+        }
+        timer = setTimeout(() => {
+            const pending = evaluateConnectStatus(serverNames, lastSnapshot);
+            finish(timeoutError(pending.kind === "wait" ? pending.pending : serverNames));
+        }, timeoutMs);
+    });
+    return {
+        connecting,
+        cancel() {
+            void connecting.then(() => undefined, () => undefined);
+            finish(new StageMcpError("MCP connect wait cancelled", "connect_failed"));
+        },
+    };
+}
+export function emitIsolatedMcpStatus(eventBus, servers) {
+    eventBus.emit(MCP_STATUS_EVENT, { servers });
+}
+export async function attachIsolatedMcp(snapshot, options) {
+    if (snapshot === undefined || Object.keys(snapshot).length === 0) {
+        return EMPTY_ATTACH;
+    }
+    const createMcpAdapter = await loadCreateMcpAdapter();
+    const extensionFactories = [
+        {
+            name: STAGEFLOW_PI_MCP_EXTENSION_NAME,
+            factory: createMcpAdapter({
+                config: toIsolatedMcpConfig(snapshot, options?.lifecycle ?? "lazy"),
+            }),
+        },
+    ];
+    const eventBus = createEventBus();
+    const { connecting, cancel } = waitForIsolatedMcpConnect(snapshot, mcpStatusSourceFromEvents(eventBus), options);
+    return { extensionFactories, eventBus, connecting, cancel };
+}

package/dist/agent/piIsolatedMcpProbe.d.ts

@@ -0,0 +1,15 @@
+export declare const PROJECT_MCP_PROBE_TIMEOUT_MS = 30000;
+export type ProjectMcpProbeStatus = "connected" | "needs_auth" | "connect_failed" | "unresolved_var" | "invalid_config" | "missing_catalog" | "cancelled";
+export type ProjectMcpProbeResult = {
+    name: string;
+    status: ProjectMcpProbeStatus;
+    error?: string;
+};
+export type ProbeProjectMcpServerOptions = {
+    projectRoot: string;
+    name: string;
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export declare function probeProjectMcpServer(options: ProbeProjectMcpServerOptions): Promise<ProjectMcpProbeResult>;