stageflow 0.12.0 → 0.13.0

package/dist/config/resolveStageMcpServers.js

@@ -0,0 +1,207 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
+export class StageMcpError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "StageMcpError";
+        this.code = code;
+    }
+}
+export const MCP_CATALOG_FILENAME = ".mcp.json";
+export const STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV = "STAGEFLOW_STAGE_ARTIFACTS_DIR";
+const STAGEFLOW_STAGE_ARTIFACTS_DIR_TOKEN = `\${${STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV}}`;
+export function stampStagePromptArtifactsDir(prompt, artifactsDir) {
+    return prompt.replaceAll(STAGEFLOW_STAGE_ARTIFACTS_DIR_TOKEN, artifactsDir);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function mcpCatalogPath(projectRoot) {
+    return path.join(projectRoot, MCP_CATALOG_FILENAME);
+}
+export function parseMcpCatalog(raw, catalogPath = MCP_CATALOG_FILENAME) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" is not valid JSON`, "invalid_config");
+    }
+    if (!isPlainObject(parsed)) {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" must be a JSON object`, "invalid_config");
+    }
+    if (!Object.hasOwn(parsed, "mcpServers")) {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" is missing mcpServers`, "invalid_config");
+    }
+    const mcpServers = parsed.mcpServers;
+    if (!isPlainObject(mcpServers)) {
+        throw new StageMcpError(`MCP catalog "${catalogPath}" mcpServers must be an object`, "invalid_config");
+    }
+    const servers = {};
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        if (name === STAGEFLOW_MCP_SERVER_NAME) {
+            throw new StageMcpError(`MCP catalog must not include reserved name "${STAGEFLOW_MCP_SERVER_NAME}"`, "reserved_name");
+        }
+        if (!isPlainObject(entry)) {
+            throw new StageMcpError(`MCP catalog server "${name}" must be an object`, "invalid_config");
+        }
+        servers[name] = entry;
+    }
+    return servers;
+}
+export async function loadMcpCatalog(projectRoot) {
+    const catalogPath = mcpCatalogPath(projectRoot);
+    let raw;
+    try {
+        raw = await readFile(catalogPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
+        }
+        throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" could not be read`, "invalid_config");
+    }
+    return { path: catalogPath, servers: parseMcpCatalog(raw, catalogPath) };
+}
+function coarseMcpTransport(entry) {
+    if (Object.hasOwn(entry, "command")) {
+        return "stdio";
+    }
+    if (Object.hasOwn(entry, "url")) {
+        return "http";
+    }
+    return undefined;
+}
+export async function listProjectMcpCatalog(projectRoot) {
+    try {
+        const catalog = await loadMcpCatalog(projectRoot);
+        const servers = [];
+        for (const [name, entry] of Object.entries(catalog.servers)) {
+            const transport = coarseMcpTransport(entry);
+            if (transport === undefined) {
+                return { status: "invalid_config", servers: [] };
+            }
+            servers.push({ name, transport });
+        }
+        return { status: "ok", servers };
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            if (err.code === "missing_catalog") {
+                return { status: "missing_catalog", servers: [] };
+            }
+            return { status: "invalid_config", servers: [] };
+        }
+        throw err;
+    }
+}
+export function assertMcpAllowlistKnown(servers, allowlist) {
+    for (const name of allowlist) {
+        if (!Object.hasOwn(servers, name)) {
+            throw new StageMcpError(`Unknown MCP server "${name}"`, "unknown_server");
+        }
+    }
+}
+const INTERPOLATION_TOKEN = /\$\{([^}]*)\}/g;
+const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_VAR_WITH_DEFAULT = /^([A-Za-z_][A-Za-z0-9_]*):-(.*)$/;
+function interpolateString(value, env, serverName) {
+    return value.replace(INTERPOLATION_TOKEN, (_match, inner) => {
+        const withDefault = ENV_VAR_WITH_DEFAULT.exec(inner);
+        if (withDefault) {
+            const found = env[withDefault[1]];
+            return found !== undefined ? found : withDefault[2];
+        }
+        if (ENV_VAR_NAME.test(inner)) {
+            const found = env[inner];
+            if (found !== undefined) {
+                return found;
+            }
+            throw new StageMcpError(`Unresolved MCP catalog variable "${inner}"`, "unresolved_var");
+        }
+        throw new StageMcpError(`MCP catalog server "${serverName}" has an invalid interpolation form`, "invalid_config");
+    });
+}
+function interpolateField(key, value, env, serverName) {
+    if ((key === "command" || key === "url" || key === "cwd") && typeof value === "string") {
+        return interpolateString(value, env, serverName);
+    }
+    if (key === "args" && Array.isArray(value)) {
+        return value.map((item) => typeof item === "string" ? interpolateString(item, env, serverName) : item);
+    }
+    if ((key === "env" || key === "headers") && isPlainObject(value)) {
+        const copied = {};
+        for (const [field, fieldValue] of Object.entries(value)) {
+            copied[field] =
+                typeof fieldValue === "string"
+                    ? interpolateString(fieldValue, env, serverName)
+                    : fieldValue;
+        }
+        return copied;
+    }
+    return value;
+}
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function isRelativeFsPath(value) {
+    if (value.length === 0 || path.isAbsolute(value) || value.startsWith("-") || value.startsWith("@")) {
+        return false;
+    }
+    return hasPathSeparator(value) || value.startsWith(".");
+}
+function isInsideProjectRoot(projectRoot, candidate) {
+    const root = path.resolve(projectRoot);
+    const resolved = path.resolve(candidate);
+    const rel = path.relative(root, resolved);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function stampSpawnRoot(resolved, projectRoot, serverName) {
+    const command = resolved.command;
+    if (typeof command === "string" && hasPathSeparator(command) && !path.isAbsolute(command)) {
+        resolved.command = path.resolve(projectRoot, command);
+    }
+    if (Array.isArray(resolved.args)) {
+        resolved.args = resolved.args.map((item) => typeof item === "string" && isRelativeFsPath(item)
+            ? path.resolve(projectRoot, item)
+            : item);
+    }
+    const catalogCwd = resolved.cwd;
+    if (catalogCwd !== undefined) {
+        if (typeof catalogCwd !== "string" || catalogCwd.length === 0 || !path.isAbsolute(catalogCwd)) {
+            throw new StageMcpError(`MCP catalog server "${serverName}" cwd must be an absolute path inside the project root`, "invalid_config");
+        }
+        const canonical = path.resolve(catalogCwd);
+        if (!isInsideProjectRoot(projectRoot, canonical)) {
+            throw new StageMcpError(`MCP catalog server "${serverName}" cwd is outside the project root`, "invalid_config");
+        }
+        resolved.cwd = canonical;
+    }
+    else if (typeof command === "string") {
+        resolved.cwd = path.resolve(projectRoot);
+    }
+    return resolved;
+}
+function interpolateServer(entry, env, serverName, projectRoot) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(entry)) {
+        resolved[key] = interpolateField(key, value, env, serverName);
+    }
+    return stampSpawnRoot(resolved, projectRoot, serverName);
+}
+export async function resolveStageMcpServers(options) {
+    const allowlist = options.allowlist ?? [];
+    if (allowlist.length === 0) {
+        return {};
+    }
+    const catalog = await loadMcpCatalog(options.projectRoot);
+    assertMcpAllowlistKnown(catalog.servers, allowlist);
+    const resolved = {};
+    for (const name of allowlist) {
+        resolved[name] = interpolateServer(catalog.servers[name], options.env, name, options.projectRoot);
+    }
+    return resolved;
+}

package/dist/config/validateCatalog.d.ts

@@ -2,7 +2,7 @@ import type { LoadedPipeline } from "../types/pipeline.js";
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_agent" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_agent" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;

package/dist/config/validateCatalog.js

@@ -6,6 +6,7 @@ import { readYamlObject } from "./readYamlObject.js";
 import { resolveCatalogContext } from "./resolveCatalogContext.js";
 import { getCatalogScanPaths } from "./browseCatalog.js";
 import { manifestPathForProject } from "./loadStageflowManifest.js";
+import { MCP_CATALOG_FILENAME, StageMcpError, assertMcpAllowlistKnown, loadMcpCatalog, mcpCatalogPath, } from "./resolveStageMcpServers.js";
 export function relPath(cwd, absPath) {
     return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
@@ -171,6 +172,55 @@ async function validateStageFile(cwd, stagePath) {
     }
     return findings;
 }
+function collectMcpAllowlistNames(loaded) {
+    const names = new Set();
+    for (const stage of loaded.stages) {
+        for (const name of stage.mcp ?? []) {
+            names.add(name);
+        }
+    }
+    return [...names];
+}
+async function findingsForStageMcpCatalog(cwd, loaded) {
+    const allowlist = collectMcpAllowlistNames(loaded);
+    const ctx = await resolveCatalogContext(cwd);
+    const projectRoot = ctx.projectRoot;
+    const catalogAbsPath = projectRoot
+        ? mcpCatalogPath(projectRoot)
+        : path.resolve(cwd, MCP_CATALOG_FILENAME);
+    if (!projectRoot) {
+        if (allowlist.length === 0)
+            return [];
+        return [
+            findingCatalog(cwd, catalogAbsPath, `MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "catalog.invalid_mcp", "error"),
+        ];
+    }
+    let catalog;
+    try {
+        catalog = await loadMcpCatalog(projectRoot);
+    }
+    catch (err) {
+        if (!(err instanceof StageMcpError))
+            throw err;
+        if (err.code === "missing_catalog" && allowlist.length === 0)
+            return [];
+        return [
+            findingCatalog(cwd, catalogAbsPath, err.message, "catalog.invalid_mcp", "error"),
+        ];
+    }
+    try {
+        assertMcpAllowlistKnown(catalog.servers, allowlist);
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            return [
+                findingCatalog(cwd, catalogAbsPath, err.message, "catalog.invalid_mcp", "error"),
+            ];
+        }
+        throw err;
+    }
+    return [];
+}
 async function runPipelineValidation(nameOrPath, options) {
     const { cwd, validateStages } = options;
     let pipelinePath;
@@ -196,6 +246,7 @@ async function runPipelineValidation(nameOrPath, options) {
         findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
         return { ok: false, findings };
     }
+    findings.push(...(await findingsForStageMcpCatalog(cwd, outcome.value)));
     if (validateStages && outcome.value.stageSources) {
         for (const source of Object.values(outcome.value.stageSources)) {
             if (source.kind === "file") {

package/dist/mcp/readArtifact.d.ts

@@ -1,2 +1,4 @@
 import type { RunStore } from "../runstore/port.js";
+export declare function artifactMediaType(relativePath: string): string | undefined;
 export declare function readRunArtifact(store: RunStore, runId: string, relativePath: string): Promise<string>;
+export declare function readRunArtifactBytes(store: RunStore, runId: string, relativePath: string): Promise<Buffer>;

package/dist/mcp/readArtifact.js

@@ -12,7 +12,23 @@ function assertSafeRunId(runId) {
         throw new Error("runId must not contain path separators or ..");
     }
 }
-export async function readRunArtifact(store, runId, relativePath) {
+export function artifactMediaType(relativePath) {
+    const ext = path.extname(relativePath).toLowerCase();
+    switch (ext) {
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".webp":
+            return "image/webp";
+        default:
+            return undefined;
+    }
+}
+async function resolveRunArtifactFile(store, runId, relativePath) {
     assertSafeRunId(runId);
     if (typeof relativePath !== "string" || relativePath.trim().length === 0) {
         throw new Error("path must be a non-empty string");
@@ -42,5 +58,13 @@ export async function readRunArtifact(store, runId, relativePath) {
     if (!isInsideDir(fileReal, workspaceReal)) {
         throw new Error("path escapes the run workspace");
     }
+    return fileReal;
+}
+export async function readRunArtifact(store, runId, relativePath) {
+    const fileReal = await resolveRunArtifactFile(store, runId, relativePath);
     return readFile(fileReal, "utf8");
 }
+export async function readRunArtifactBytes(store, runId, relativePath) {
+    const fileReal = await resolveRunArtifactFile(store, runId, relativePath);
+    return readFile(fileReal);
+}

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.12.0";
+export declare const PACKAGE_VERSION = "0.13.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.12.0";
+export const PACKAGE_VERSION = "0.13.0";

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,4 +1,7 @@
 import { resolveSkillByName } from "../config/listSkills.js";
+import { mkdir } from "node:fs/promises";
+import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
+import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
 import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
@@ -20,16 +23,49 @@ async function resolveStageSkillForRun(stage, catalog) {
     }
     return { ok: true, skillFilePath: resolved.filePath };
 }
-async function openStageWithOperatorCatalog(agent, input, catalog) {
+async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir) {
+    const names = allowlist ?? [];
+    if (names.length === 0)
+        return undefined;
+    if (factoryCwd === undefined) {
+        throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
+    }
+    await mkdir(artifactsDir, { recursive: true });
+    const resolved = await resolveStageMcpServers({
+        projectRoot: factoryCwd,
+        allowlist: names,
+        env: {
+            ...process.env,
+            [STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV]: artifactsDir,
+        },
+    });
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, artifactsDir) {
     const skill = await resolveStageSkillForRun(input.stage, catalog);
     if (!skill.ok)
         return skill;
+    let resolvedMcpServers;
+    try {
+        resolvedMcpServers = await resolveAttemptMcpServers(input.stage.mcp, factoryCwd, artifactsDir);
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            return { ok: false, reason: err.message };
+        }
+        throw err;
+    }
     try {
         const handle = agent.openStage({
             ...input,
+            stage: {
+                ...input.stage,
+                system_prompt: stampStagePromptArtifactsDir(input.stage.system_prompt, artifactsDir),
+            },
             ...(skill.skillFilePath !== undefined
                 ? { skillFilePath: skill.skillFilePath }
                 : {}),
+            ...(resolvedMcpServers !== undefined ? { resolvedMcpServers } : {}),
         });
         return { ok: true, handle };
     }
@@ -159,7 +195,7 @@ export async function openStageAttempt(input) {
         ...(input.stage.timeout_ms !== undefined
             ? { timeoutMs: input.stage.timeout_ms }
             : {}),
-    }, input.operatorCatalog);
+    }, input.operatorCatalog, input.factoryCwd, attemptArtifactsDir(input.workspaceDir, stageId, attempt));
     if (!opened.ok)
         return opened;
     return {

package/dist/runtime/verifiedStageExecution.d.ts

@@ -3,6 +3,8 @@ import type { RunStore } from "../runstore/port.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
 import type { StageConfig } from "../types/stage.js";
 import type { StageRoots } from "./stageRoots.js";
+/** Sidecar written before completion command checks so they can inspect fork_choice. */
+export declare const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
 export type VerifiedStageExecution = {
     /** Establish durable observation before agent work begins. */
     prepare(): Promise<void>;

package/dist/runtime/verifiedStageExecution.js

@@ -1,9 +1,13 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { listQaExchanges } from "../hitl/qaTrail.js";
-import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
+import { attemptArtifactsDir, attemptWorkspaceDir, } from "../runstore/workspaceLayout.js";
 import { COMPLETION_VERIFICATION_FAILURE_PREFIX, } from "../types/completion.js";
 import { runCompletionContract, } from "./completionCheckRunner.js";
 import { readCompletionCheckoutBaseline, writeCompletionCheckoutBaseline, } from "./completionCheckoutBaseline.js";
 import { createGitCheckoutCapability } from "./gitCheckoutCapability.js";
+/** Sidecar written before completion command checks so they can inspect fork_choice. */
+export const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
 export function completionVerificationFailureReason(failedCheckIds) {
     return `${COMPLETION_VERIFICATION_FAILURE_PREFIX} ${failedCheckIds.join(", ")}`;
 }
@@ -65,11 +69,15 @@ export function createVerifiedStageExecution(options) {
             if (contract === undefined)
                 return candidate;
             try {
+                const artifactsDir = attemptArtifactsDir(roots.runWorkspaceDir, stageId, attempt);
+                const attemptDir = attemptWorkspaceDir(roots.runWorkspaceDir, stageId, attempt);
+                await mkdir(attemptDir, { recursive: true });
+                await writeFile(path.join(attemptDir, COMPLETION_CANDIDATE_ENVELOPE_FILENAME), `${JSON.stringify(candidate.envelope, null, 2)}\n`, "utf8");
                 const verification = await runCompletionContract({
                     contract,
                     envelope: candidate.envelope,
                     payloadSchema: stage.payload_schema,
-                    artifactsDir: attemptArtifactsDir(roots.runWorkspaceDir, stageId, attempt),
+                    artifactsDir,
                     commandWorkingDirectory: roots.cwd,
                     gates: gateDecisionsForAttempt({ store, runId, stageId, attempt }),
                     checkout,

package/dist/server/http.js

@@ -3,12 +3,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getCredentialSourceSettings, setCredentialSource, } from "../agent/providerAuth.js";
 import { handleProviderRoutes, providerAuthErrorBody, } from "./providerRoutes.js";
+import { handleProjectMcpRoutes } from "./projectMcpRoutes.js";
 import { createPipeline, parseCreatePipelineBody } from "../config/createPipeline.js";
 import { createStage, parseCreateStageBody } from "../config/createStage.js";
 import { browseCatalog } from "../config/browseCatalog.js";
 import { listExtensions } from "../config/listExtensions.js";
 import { listSkills } from "../config/listSkills.js";
-import { readRunArtifact } from "../mcp/readArtifact.js";
+import { artifactMediaType, readRunArtifact, readRunArtifactBytes, } from "../mcp/readArtifact.js";
 import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, } from "../runtime/settingsFile.js";
@@ -96,7 +97,8 @@ function isMutatingApi(method, pathname) {
         /^\/api\/providers\/[^/]+\/login$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login\/[^/]+\/answer$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login\/[^/]+\/cancel$/.test(pathname) ||
-        /^\/api\/providers\/[^/]+\/logout$/.test(pathname));
+        /^\/api\/providers\/[^/]+\/logout$/.test(pathname) ||
+        /^\/api\/project-mcp\/[^/]+\/probe$/.test(pathname));
 }
 function isCredentialMutatingApi(method, pathname) {
     if (method !== "POST")
@@ -210,8 +212,19 @@ export async function startUiServer(options) {
                         return true;
                     }
                     try {
-                        const content = await readRunArtifact(store, runId, artifactPath);
-                        textPlain(res, 200, content);
+                        const mediaType = artifactMediaType(artifactPath);
+                        if (mediaType !== undefined) {
+                            const bytes = await readRunArtifactBytes(store, runId, artifactPath);
+                            res.writeHead(200, {
+                                "Content-Type": mediaType,
+                                "Content-Length": bytes.length,
+                            });
+                            res.end(bytes);
+                        }
+                        else {
+                            const content = await readRunArtifact(store, runId, artifactPath);
+                            textPlain(res, 200, content);
+                        }
                     }
                     catch (err) {
                         const message = err instanceof Error ? err.message : String(err);
@@ -527,6 +540,12 @@ export async function startUiServer(options) {
                 })) {
                     return true;
                 }
+                if (await handleProjectMcpRoutes(req, res, {
+                    projectRoot: boot.rootDir,
+                    json,
+                })) {
+                    return true;
+                }
                 if (method === "GET" && pathname === "/api/skills") {
                     json(res, 200, await listSkills({ cwd, agentDir }));
                     return true;

package/dist/server/projectMcpRoutes.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export type ProjectMcpRoutesCtx = {
+    projectRoot: string;
+    json: (res: ServerResponse, status: number, body: unknown) => void;
+};
+export declare function handleProjectMcpRoutes(req: IncomingMessage, res: ServerResponse, ctx: ProjectMcpRoutesCtx): Promise<boolean>;

package/dist/server/projectMcpRoutes.js

@@ -0,0 +1,38 @@
+import { probeProjectMcpServer } from "../agent/piIsolatedMcpProbe.js";
+import { listProjectMcpCatalog } from "../config/resolveStageMcpServers.js";
+function requestAbortSignal(req) {
+    const controller = new AbortController();
+    const abort = () => {
+        if (!controller.signal.aborted)
+            controller.abort();
+    };
+    if (req.aborted || req.destroyed) {
+        abort();
+        return controller.signal;
+    }
+    req.once("aborted", abort);
+    req.once("close", abort);
+    return controller.signal;
+}
+export async function handleProjectMcpRoutes(req, res, ctx) {
+    const { projectRoot, json } = ctx;
+    const method = req.method ?? "GET";
+    const rawUrl = req.url ?? "/";
+    const pathname = new URL(rawUrl, "http://localhost").pathname;
+    if (method === "GET" && pathname === "/api/project-mcp") {
+        json(res, 200, await listProjectMcpCatalog(projectRoot));
+        return true;
+    }
+    const probeMatch = pathname.match(/^\/api\/project-mcp\/([^/]+)\/probe$/);
+    if (method === "POST" && probeMatch) {
+        const name = decodeURIComponent(probeMatch[1] ?? "");
+        const result = await probeProjectMcpServer({
+            projectRoot,
+            name,
+            signal: requestAbortSignal(req),
+        });
+        json(res, 200, result);
+        return true;
+    }
+    return false;
+}

package/dist/types/pipeline.d.ts

@@ -52,6 +52,7 @@ export type PipelineStageYamlEntry = PipelineStageRef & {
     clone_input_schema?: unknown;
     clone_actions?: CloneAction[];
     skill?: string;
+    mcp?: string[];
 };
 export type PipelineIncludeEntry = {
     local: string;
@@ -74,6 +75,7 @@ export type NormalizedPipelineStageEntry = {
     feedback_loop?: FeedbackLoopConfig;
     replay_safe?: boolean;
     skill?: string;
+    mcp?: string[];
     body: {
         kind: "inline";
         raw: Record<string, unknown>;

package/dist/types/stage.d.ts

@@ -14,9 +14,10 @@ export type StageConfig = {
     pre_emit_checks?: PreEmitCheck[];
     clone_input_schema?: unknown;
     clone_actions?: CloneAction[];
-    /** Optional stage wall-clock timeout in milliseconds (default 15 minutes). */
+    /** Optional stage wall-clock timeout in milliseconds (default 60 minutes). */
     timeout_ms?: number;
     skill?: string;
+    mcp?: string[];
     /**
      * Selects the AgentPort backend for this stage, overriding pipeline/global.
      * Parsed but not yet consulted — see STAGE_LEVEL_AGENT_OVERRIDE_ENABLED.