stageflow 0.9.0 → 0.13.0

package/dist/agent/piAdapter.js

@@ -26,14 +26,17 @@
  * fails closed with `StageSessionReconstructError` (KTD7). Epic proving
  * vehicle: pipeline `plan-review-proving` (Pi live wait + console answers).
  *
- * `ask_operator` is always registered on sealed stage sessions (allowlist +
- * customTools).
+ * `ask_operator` is registered on sealed stage sessions unless the stage
+ * declares `gate_kinds: []`.
  */
 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";
 import { attemptContext, noAttemptContext, } from "../runtime/stageAttemptContext.js";
 import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
@@ -46,18 +49,21 @@ import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
- * Always includes `ask_operator` (R7); `write_stage_artifact` when registered
- * (always, for bound and unbound — bound/unbound only gates cwd / env bind).
+ * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
+ * `write_stage_artifact` when registered (always, for bound and unbound —
+ * bound/unbound only gates cwd / env bind).
  */
-export function resolveStageToolNames(emitToolName, artifactToolName, askOperatorToolName = "ask_operator") {
+export function resolveStageToolNames(emitToolName, artifactToolName, askOperatorToolName = "ask_operator", gateKinds) {
     const tools = [
         "read",
         "bash",
         "write",
         "edit",
         emitToolName,
-        askOperatorToolName,
     ];
+    if (gateKinds === undefined || gateKinds.length > 0) {
+        tools.push(askOperatorToolName);
+    }
     if (artifactToolName) {
         tools.push(artifactToolName);
     }
@@ -364,6 +370,37 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
     if (input.stage.payload_schema !== undefined) {
         emitHint += `\nOn status=success, payload is required and must match this JSON Schema:\n${JSON.stringify(input.stage.payload_schema, null, 2)}`;
     }
+    const checklistChecks = input.completionContract?.checks.filter((check) => check.type === "checklist") ?? [];
+    if (checklistChecks.length > 0) {
+        emitHint += `\nBefore emitting success, self-review every required checklist item. Include checklist_attestations in the envelope with each check_id and its complete item list exactly as declared:\n${JSON.stringify(checklistChecks, null, 2)}`;
+    }
+    if (input.repairContext !== undefined) {
+        emitHint += `\nThis is recovery attempt ${input.roots.attempt ?? input.repairContext.prior_attempt + 1}. The previous candidate did not pass Stageflow verification. Address the failed checks before emitting success.`;
+        if (input.repairContext.operator_guidance) {
+            emitHint += `\nThe operator approved this retry with these instructions:\n${input.repairContext.operator_guidance}`;
+        }
+        if (input.repairContext.failed_checks?.length) {
+            emitHint += `\nFailed-check evidence from attempt ${input.repairContext.prior_attempt}:\n${JSON.stringify(input.repairContext.failed_checks, null, 2)}`;
+        }
+    }
+    if (input.cloneEmitContext !== undefined) {
+        const allowedActions = input.cloneEmitContext.allowedActions ?? ["skip", "once", "fanout"];
+        const successorLines = input.cloneEmitContext.clonableSuccessors.map((successor) => {
+            const header = `- ${successor.successorId} (clone_cap: ${successor.cloneCap})`;
+            if (successor.cloneInputSchema === undefined) {
+                return header;
+            }
+            return `${header}\n  Assignment schema (clone_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 += `\nAllowed clone actions: ${allowedActions.join(", ")}`;
+    }
+    if (input.feedbackLoopEmitContext !== undefined) {
+        emitHint += `\nFeedback-loop decision: this stage is a feedback-loop source. On status=success, feedback_loop is required. Emit either {"action":"continue"} to proceed downstream or {"action":"send_back","target":"…"} to request another pass.`;
+        emitHint += `\nAllowed send_back target: ${input.feedbackLoopEmitContext.target}.`;
+        emitHint += `\nA send_back decision cannot be combined with fork_choice or clone_forks.`;
+    }
     const attempt = input.roots.attempt ?? 1;
     const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;
     const skillBaseDir = input.stage.skill !== undefined && input.skillFilePath !== undefined
@@ -394,7 +431,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
         `Goal: ${input.task.goal}`,
         input.task.context ? `Context: ${input.task.context}` : "",
         input.task.constraints ? `Constraints: ${input.task.constraints}` : "",
-        formatPriorEnvelope(input.priorEnvelope, input.priorEnvelopes),
+        formatPriorEnvelope(input.priorEnvelope, input.priorEnvelopes, input.priorEnvelopesByStage),
+        input.feedbackLoopContext !== undefined
+            ? formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode)
+            : "",
         "",
         artifactGuidance,
         emitHint,
@@ -409,6 +449,16 @@ export function composeStageUserPrompt(input, emitToolName, emitHintOverride, ar
     }
     return body;
 }
+export function composeFeedbackResumePrompt(input) {
+    if (input.feedbackLoopContext === undefined) {
+        throw new Error("feedback_resume requires feedbackLoopContext");
+    }
+    return [
+        "Continue this stage after feedback-loop send-back.",
+        "Incorporate the operator/source feedback below, then complete the stage (emit an envelope when done).",
+        formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode ?? "feedback_resume"),
+    ].join("\n\n");
+}
 /**
  * DefaultResourceLoader with host/global discovery turned off.
  *
@@ -416,9 +466,9 @@ export function composeStageUserPrompt(input, emitToolName, emitHintOverride, ar
  * 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) {
@@ -430,6 +480,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,
@@ -437,6 +491,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;
@@ -686,12 +750,20 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     const provider = findProviderSupport(input.stage.model);
     const capture = {};
     const askWaitChannel = existingAskWaitChannel ?? new AskOperatorWaitChannel();
-    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext, input.cloneEmitContext);
+    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext, input.cloneEmitContext, {
+        checks: input.stage.pre_emit_checks,
+        readQaTrail: input.readQaTrail,
+    }, input.feedbackLoopEmitContext);
     const emitTool = defineTool(emitDef);
-    const askDef = createAskOperatorTool({
-        requestWait: (prompt) => askWaitChannel.requestWait(prompt),
-    });
-    const askTool = defineTool(askDef);
+    const gateKinds = input.stage.gate_kinds;
+    const includeAsk = gateKinds === undefined || gateKinds.length > 0;
+    const askDef = includeAsk
+        ? createAskOperatorTool({
+            requestWait: (prompt) => askWaitChannel.requestWait(prompt),
+            ...(gateKinds !== undefined ? { allowedKinds: gateKinds } : {}),
+        })
+        : undefined;
+    const askTool = askDef ? defineTool(askDef) : undefined;
     const artifactDef = createWriteStageArtifactTool({
         runWorkspaceDir: roots.runWorkspaceDir,
         stageId: runtimeStageId(input),
@@ -714,11 +786,28 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         additionalExtensionPaths.push(...prepared.extensionPaths);
         restoreProvider = prepared.restore;
     }
+    let attached;
     try {
-        const modelRuntime = await ModelRuntime.create(roots.authPath ? { authPath: roots.authPath } : undefined);
+        const modelRuntime = await ModelRuntime.create(roots.authPath
+            ? {
+                authPath: roots.authPath,
+                // ModelRuntime otherwise resolves models.json from getAgentDir(),
+                // which bindPiAgentDirEnv seals to an empty per-attempt sandbox
+                // dir. Point it at the same durable agent dir as authPath so
+                // custom providers (e.g. a self-hosted OpenAI-compatible
+                // gateway) defined there stay usable in sealed stage sessions.
+                modelsPath: path.join(path.dirname(roots.authPath), "models.json"),
+            }
+            : undefined);
         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,
@@ -728,57 +817,61 @@ 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));
         }
-        const customTools = [emitTool, askTool, artifactTool];
         return {
             sessionManager,
             modelRuntime,
             settingsManager,
             loader,
-            tools: resolveStageToolNames(emitDef.name, artifactDef.name, askDef.name),
+            tools,
             customTools,
             emitDefName: emitDef.name,
-            askOperatorDefName: askDef.name,
+            ...(askDef ? { askOperatorDefName: askDef.name } : {}),
             artifactDefName: artifactDef.name,
             providerEmitHint: provider?.emitToolHint?.(emitDef.name),
             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;
     }
 }
@@ -818,6 +911,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,
@@ -845,6 +941,7 @@ export async function reconstructStageSessionForAnswer(input, answer) {
         };
     }
     catch (err) {
+        wiring.cancelConnecting?.();
         await shutdownSession(session);
         wiring.restoreProvider?.();
         if (err instanceof StageSessionReconstructError)
@@ -866,7 +963,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,
@@ -901,30 +1011,65 @@ export class PiAgentAdapter {
         const timeoutMs = input.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
         const askWaitChannel = new AskOperatorWaitChannel();
         const sessionFile = resolveStageSessionFile(input);
+        const sessionMode = input.sessionMode ?? "fresh";
         let sessionManager;
         let resumeWaiting = false;
-        if (existsSync(sessionFile)) {
+        let feedbackResume = false;
+        let forceNewSession = sessionMode === "new_session";
+        if (sessionMode === "feedback_resume") {
+            if (input.feedbackLoopContext === undefined) {
+                throw new StageSessionReconstructError(`feedback_resume requires feedbackLoopContext: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            }
+            if (!existsSync(sessionFile)) {
+                throw new StageSessionReconstructError(`stage session file missing for feedback_resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            }
             try {
                 sessionManager = SessionManager.open(sessionFile, path.dirname(sessionFile), input.roots.cwd);
             }
             catch (err) {
-                throw new StageSessionReconstructError(`stage session file corrupt or unreadable for resume: ${sessionFile}`, {
+                throw new StageSessionReconstructError(`stage session file corrupt or unreadable for feedback_resume: ${sessionFile}`, {
                     stageId: runtimeStageId(input),
                     sessionFile,
                     cause: err,
                 });
             }
             ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
-            if (!findOpenToolCall(sessionManager)) {
-                throw new StageSessionReconstructError(`stage session has no open tool call for resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            feedbackResume = true;
+        }
+        else if (sessionMode !== "new_session") {
+            if (sessionMode === "waiting_resume" || existsSync(sessionFile)) {
+                if (existsSync(sessionFile)) {
+                    try {
+                        sessionManager = SessionManager.open(sessionFile, path.dirname(sessionFile), input.roots.cwd);
+                    }
+                    catch (err) {
+                        throw new StageSessionReconstructError(`stage session file corrupt or unreadable for resume: ${sessionFile}`, {
+                            stageId: runtimeStageId(input),
+                            sessionFile,
+                            cause: err,
+                        });
+                    }
+                    ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
+                    if (!findOpenToolCall(sessionManager)) {
+                        throw new StageSessionReconstructError(`stage session has no open tool call for resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+                    }
+                    resumeWaiting = true;
+                }
+                else {
+                    throw new StageSessionReconstructError(`stage session file missing for resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+                }
             }
-            resumeWaiting = true;
         }
         let session;
         let wiring;
         let unsubscribeProgress;
         let prepareError;
         const preparePromise = (async () => {
+            if (forceNewSession) {
+                await mkdir(path.dirname(sessionFile), { recursive: true });
+                await writeFile(sessionFile, "");
+                sessionManager = undefined;
+            }
             if (!sessionManager) {
                 sessionManager = await createStageSessionManager(input.roots, runtimeStageId(input), sessionFile);
             }
@@ -987,6 +1132,11 @@ export class PiAgentAdapter {
             },
             run: async () => {
                 return runWithTimeout(async () => {
+                    if (feedbackResume) {
+                        syncAgentMessagesFromSession(session, sessionManager);
+                        await session.prompt(composeFeedbackResumePrompt(input));
+                        return;
+                    }
                     const userPrompt = composeStageUserPrompt(input, wiring.emitDefName, wiring.providerEmitHint, wiring.artifactDefName);
                     await session.prompt(userPrompt);
                 });

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>;