@wix/pathgrade 0.32.0 → 0.33.0

package/dist/agents/claude/sdk-message-projector.js

@@ -165,6 +165,26 @@ function buildToolEvent(block, turnNumber, answerStore) {
     const providerToolName = String(block.name || 'unknown');
     const rawInput = block.input ?? undefined;
     const toolUseId = typeof block.id === 'string' ? block.id : undefined;
+    const mcpTool = parseClaudeSdkMcpToolName(providerToolName);
+    if (mcpTool) {
+        const normalizedProviderToolName = `${mcpTool.server}.${mcpTool.tool}`;
+        const args = {
+            ...(rawInput ?? {}),
+            server: mcpTool.server,
+            tool: mcpTool.tool,
+            status: 'completed',
+        };
+        return {
+            action: 'mcp_tool_call',
+            provider: 'claude',
+            providerToolName: normalizedProviderToolName,
+            turnNumber,
+            arguments: args,
+            summary: `MCP tool ${normalizedProviderToolName} completed`,
+            confidence: 'high',
+            rawSnippet: JSON.stringify(block).slice(0, 200),
+        };
+    }
     const action = TOOL_NAME_MAP[providerToolName] ?? 'unknown';
     const args = action === 'ask_user'
         ? buildAskUserArguments(rawInput, answerStore?.get(toolUseId))
@@ -182,6 +202,12 @@ function buildToolEvent(block, turnNumber, answerStore) {
         rawSnippet,
     };
 }
+function parseClaudeSdkMcpToolName(providerToolName) {
+    const match = providerToolName.match(/^mcp__([^_].*?)__(.+)$/);
+    if (!match)
+        return undefined;
+    return { server: match[1], tool: match[2] };
+}
 /**
  * Boundary with the ask-user bridge.
  *

package/dist/agents/claude/sdk-options.d.ts

@@ -1,5 +1,5 @@
 import type { CanUseTool, Options, SpawnedProcess, SpawnOptions as SdkSpawnOptions } from '@anthropic-ai/claude-agent-sdk';
-import type { McpServersObject } from '../../providers/mcp-config.js';
+import type { McpServersObject } from '../../providers/mcp-runtime-mounting.js';
 export interface ClaudeSdkOptionsInputs {
     /** Per-trial workspace; cwd for the SDK so project-staged skills resolve. */
     workspacePath: string;
@@ -31,8 +31,10 @@ export interface ClaudeSdkOptionsInputs {
      * `session_id` on every turn after.
      */
     resume?: string;
-    /** MCP servers in the SDK's object form, from `loadMcpServersForSdk`. */
+    /** MCP servers in the SDK's object form, from `mountMcpForClaudeSdk`. */
     mcpServers?: McpServersObject;
+    /** Per-turn cancellation controller linked to PathGrade's turn timeout. */
+    abortController?: AbortController;
 }
 /**
  * Pick the Claude executable. Precedence:

package/dist/agents/claude/sdk-options.js

@@ -58,6 +58,8 @@ export function buildClaudeSdkOptions(inputs) {
         opts.resume = inputs.resume;
     if (inputs.mcpServers !== undefined)
         opts.mcpServers = inputs.mcpServers;
+    if (inputs.abortController !== undefined)
+        opts.abortController = inputs.abortController;
     // Env composition ownership: the driver does NOT pluck specific keys.
     // `prepareWorkspace` curates the runtime env (safe host vars, sandbox
     // HOME/TMPDIR, resolveCredentials() output, user-supplied

package/dist/agents/claude.d.ts

@@ -8,7 +8,7 @@
  *   - `sandboxedClaudeSpawn`      — `Options.spawnClaudeCodeProcess` adapter
  *                                   that filters env and (optionally) wraps
  *                                   argv with macOS sandbox-exec.
- *   - `loadMcpServersForSdk`      — reads pathgrade's MCP config JSON into
+ *   - `mountMcpForClaudeSdk`      — reads pathgrade's MCP config JSON into
  *                                   the SDK's `Options.mcpServers` shape.
  *   - `buildClaudeSdkOptions`     — pure builder for the per-turn `Options`.
  *   - `createAskUserBridge`       — live `canUseTool` that auto-allows

package/dist/agents/claude.js

@@ -8,7 +8,7 @@
  *   - `sandboxedClaudeSpawn`      — `Options.spawnClaudeCodeProcess` adapter
  *                                   that filters env and (optionally) wraps
  *                                   argv with macOS sandbox-exec.
- *   - `loadMcpServersForSdk`      — reads pathgrade's MCP config JSON into
+ *   - `mountMcpForClaudeSdk`      — reads pathgrade's MCP config JSON into
  *                                   the SDK's `Options.mcpServers` shape.
  *   - `buildClaudeSdkOptions`     — pure builder for the per-turn `Options`.
  *   - `createAskUserBridge`       — live `canUseTool` that auto-allows
@@ -24,12 +24,26 @@
 import { query as sdkQuery, } from '@anthropic-ai/claude-agent-sdk';
 import { BaseAgent, getRuntimeEnv, getWorkspacePath, } from '../types.js';
 import { createSandboxedClaudeSpawn } from '../providers/sandboxed-claude-spawn.js';
-import { loadMcpServersForSdk } from '../providers/mcp-config.js';
+import { assertStdioMcpServersStartForClaudeSdk, mountMcpForClaudeSdk, } from '../providers/mcp-runtime-mounting.js';
 import { buildClaudeSdkOptions, resolveClaudeCodeExecutable, } from './claude/sdk-options.js';
 import { projectSdkMessages } from './claude/sdk-message-projector.js';
 import { createAskUserBridge } from './claude/ask-user-bridge.js';
 import { createAskUserAnswerStore } from './claude/ask-user-answer-store.js';
 import { requireAskBusForLiveBatches } from '../sdk/ask-bus/bus.js';
+function createLinkedAbortController(signal) {
+    const controller = new AbortController();
+    if (!signal)
+        return controller;
+    if (signal.aborted) {
+        controller.abort();
+        return controller;
+    }
+    signal.addEventListener('abort', () => controller.abort(), { once: true });
+    return controller;
+}
+function getTurnAbortSignal(sessionOptions) {
+    return sessionOptions?.getAbortSignal?.() ?? sessionOptions?.abortSignal;
+}
 export class ClaudeAgent extends BaseAgent {
     deps;
     opts;
@@ -57,7 +71,13 @@ export class ClaudeAgent extends BaseAgent {
             agentOptionsExecutable: this.opts.claudeCodeExecutable,
             envExecutable,
         });
-        const mcpServers = await loadMcpServersForSdk(workspacePath);
+        const mcpMountOptions = {
+            workspacePath,
+            mcpConfigPath: sessionOptions?.mcpConfigPath,
+            runtimeEnv: getRuntimeEnv(runtime),
+        };
+        await assertStdioMcpServersStartForClaudeSdk(mcpMountOptions);
+        const mcpServers = await mountMcpForClaudeSdk(mcpMountOptions);
         let priorSessionId;
         let turnNumber = 0;
         // The live ask-user bridge resolves AskUserQuestion through the bus
@@ -87,6 +107,7 @@ export class ClaudeAgent extends BaseAgent {
                 claudeCodeExecutable,
                 resume: priorSessionId,
                 mcpServers,
+                abortController: createLinkedAbortController(getTurnAbortSignal(sessionOptions)),
             });
             const messages = [];
             const stream = queryFn({ prompt: message, options: sdkOptions });

package/dist/agents/codex-app-server/agent.js

@@ -1,10 +1,45 @@
 import { BaseAgent, getRuntimeEnv, getWorkspacePath, } from '../../types.js';
+import { mountMcpForCodexAppServer } from '../../providers/mcp-runtime-mounting.js';
+import { assertMcpSecretReferencesReady } from '../../providers/mcp-config.js';
 import { requireAskBusForLiveBatches, } from '../../sdk/ask-bus/bus.js';
 import { toAskUserToolEvent } from '../../sdk/ask-bus/projection.js';
+import { decideMcpToolCall, redactMcpSecrets, } from '../../sdk/mcp-safety.js';
 import { spawnAppServerTransport, } from './transport.js';
 import { normalizeUpstreamQuestion, toWireAnswerMap, } from './wire-translators.js';
 const DEFAULT_MODEL = 'gpt-5.3-codex';
 const TURN_COMPLETED_METHOD = 'turn/completed';
+function recordFromUnknown(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function isMcpToolCallApprovalRequest(params) {
+    const meta = recordFromUnknown(recordFromUnknown(params)._meta);
+    return meta.codex_approval_kind === 'mcp_tool_call';
+}
+function extractMcpToolApprovalRequest(params) {
+    if (!isMcpToolCallApprovalRequest(params))
+        return undefined;
+    const record = recordFromUnknown(params);
+    const meta = recordFromUnknown(record._meta);
+    const serverName = typeof record.serverName === 'string' ? record.serverName : undefined;
+    const toolName = typeof meta.toolName === 'string' ? meta.toolName
+        : typeof meta.tool_name === 'string' ? meta.tool_name
+            : typeof meta.name === 'string' ? meta.name
+                : typeof record.message === 'string' ? parseToolNameFromApprovalMessage(record.message)
+                    : undefined;
+    if (!serverName || !toolName)
+        return undefined;
+    return {
+        serverName,
+        toolName,
+        arguments: recordFromUnknown(meta.tool_params),
+    };
+}
+function parseToolNameFromApprovalMessage(message) {
+    return message.match(/tool\s+"([^"]+)"/i)?.[1];
+}
 function projectItemIntoTurn(item, turn) {
     if (item.type === 'agentMessage') {
         const msg = item;
@@ -43,6 +78,82 @@ function projectItemIntoTurn(item, turn) {
         }
         return;
     }
+    if (item.type === 'mcpToolCall') {
+        const call = item;
+        const args = recordFromUnknown(call.arguments);
+        const providerToolName = `${call.server}.${call.tool}`;
+        turn.nonAskToolEvents.push({
+            action: 'mcp_tool_call',
+            provider: 'codex',
+            providerToolName,
+            turnNumber: turn.turnNumber,
+            arguments: {
+                ...args,
+                server: call.server,
+                tool: call.tool,
+                status: call.status ?? 'unknown',
+            },
+            summary: `MCP tool ${providerToolName} ${call.status ?? 'unknown'}`,
+            confidence: 'high',
+            rawSnippet: JSON.stringify(call),
+        });
+        return;
+    }
+}
+function projectMcpStartupStatusIntoTurn(params, turn) {
+    const name = params.name ?? 'unknown';
+    const status = params.status ?? 'unknown';
+    const error = typeof params.error === 'string' ? params.error : undefined;
+    turn.nonAskToolEvents.push({
+        action: 'unknown',
+        provider: 'codex',
+        providerToolName: 'mcpServer/startupStatus/updated',
+        turnNumber: turn.turnNumber,
+        arguments: {
+            name,
+            status,
+            ...(error ? { error } : {}),
+        },
+        summary: `MCP server ${name} startup ${status}`,
+        confidence: 'high',
+        rawSnippet: JSON.stringify(params),
+    });
+    if (status === 'failed') {
+        const message = `MCP server ${name} failed to start${error ? `: ${error}` : ''}`;
+        turn.turnFailed = true;
+        turn.failureMessage = message;
+        turn.signalFailure?.(message);
+    }
+}
+function recordPolicyDeniedMcpToolCall(turn, request, decision, rawParams) {
+    if (!turn)
+        return;
+    const args = redactMcpSecrets(request.arguments);
+    const providerToolName = `${request.serverName}.${request.toolName}`;
+    turn.nonAskToolEvents.push({
+        action: 'mcp_tool_call',
+        provider: 'codex',
+        providerToolName,
+        turnNumber: turn.turnNumber,
+        arguments: {
+            ...args,
+            server: request.serverName,
+            tool: request.toolName,
+            status: 'policy_denied',
+            policyResult: {
+                action: 'deny',
+                reason: decision.reason,
+                message: decision.message,
+            },
+        },
+        summary: `MCP tool ${providerToolName} policy_denied`,
+        confidence: 'high',
+        rawSnippet: JSON.stringify(redactMcpSecrets(rawParams)),
+    });
+}
+function isLiveMcpSafetyMode(options) {
+    const runMode = options?.runMode ?? 'mock';
+    return runMode === 'live-readonly' || runMode === 'live-sandbox' || runMode === 'live';
 }
 export class CodexAppServerAgent extends BaseAgent {
     deps;
@@ -76,6 +187,7 @@ export class CodexAppServerAgent extends BaseAgent {
                 askBus,
                 activeTurn: () => activeTurn,
                 onPermissionGrant: this.deps.onPermissionGrant,
+                mcpSafety: options?.mcpSafety,
             }));
             transport.onClose((info) => {
                 closeInfo = info;
@@ -84,6 +196,13 @@ export class CodexAppServerAgent extends BaseAgent {
                 if (process.env.PATHGRADE_CODEX_DEBUG) {
                     console.error(`[codex app-server] notification method=${n.method} params=${JSON.stringify(n.params).slice(0, 300)}`);
                 }
+                if (n.method === 'mcpServer/startupStatus/updated') {
+                    const turn = activeTurn;
+                    if (turn) {
+                        projectMcpStartupStatusIntoTurn((n.params ?? {}), turn);
+                    }
+                    return;
+                }
                 if (n.method !== 'item/completed')
                     return;
                 const turn = activeTurn;
@@ -117,7 +236,20 @@ export class CodexAppServerAgent extends BaseAgent {
             activeTurn = turn;
             try {
                 if (threadId === null) {
-                    const resp = await t.sendRequest('thread/start', buildThreadStartParams({ cwd: workspacePath, model, sandboxMode }));
+                    if (options?.mcpConfigPath && isLiveMcpSafetyMode(options.mcpSafety)) {
+                        await assertMcpSecretReferencesReady({
+                            workspacePath,
+                            mcpConfigPath: options.mcpConfigPath,
+                            env: runtimeEnv,
+                        });
+                    }
+                    const mcpConfig = options?.mcpConfigPath
+                        ? await mountMcpForCodexAppServer({
+                            workspacePath,
+                            mcpConfigPath: options.mcpConfigPath,
+                        })
+                        : undefined;
+                    const resp = await t.sendRequest('thread/start', buildThreadStartParams({ cwd: workspacePath, model, sandboxMode, mcpConfig }));
                     threadId = resp.thread.id;
                 }
                 // Wait for TurnCompleted OR subprocess crash OR dispatcher failure.
@@ -155,6 +287,9 @@ export class CodexAppServerAgent extends BaseAgent {
                         turn.failureMessage = msg;
                         resolve();
                     };
+                    if (turn.turnFailed) {
+                        turn.signalFailure(turn.failureMessage ?? 'turn failed');
+                    }
                     // If already closed, settle immediately.
                     if (closeInfo) {
                         if (!settled) {
@@ -254,7 +389,7 @@ export class CodexAppServerAgent extends BaseAgent {
         };
     }
     dispatchServerRequest(req, ctx) {
-        const { transport, askBus, activeTurn, onPermissionGrant } = ctx;
+        const { transport, askBus, activeTurn, onPermissionGrant, mcpSafety } = ctx;
         switch (req.method) {
             case 'item/tool/requestUserInput':
                 void handleRequestUserInput(req, { transport, askBus, activeTurn });
@@ -288,7 +423,30 @@ export class CodexAppServerAgent extends BaseAgent {
                 transport.sendResponse(req.id, { status: 'declined' });
                 return;
             case 'mcpServer/elicitation/request':
-                transport.sendResponse(req.id, { action: 'decline' });
+                if (isMcpToolCallApprovalRequest(req.params)) {
+                    const toolRequest = extractMcpToolApprovalRequest(req.params);
+                    if (toolRequest) {
+                        const decision = decideMcpToolCall(mcpSafety, toolRequest);
+                        if (decision.action === 'deny') {
+                            recordPolicyDeniedMcpToolCall(activeTurn(), toolRequest, decision, req.params);
+                            transport.sendResponse(req.id, {
+                                action: 'decline',
+                                content: null,
+                                _meta: {
+                                    pathgrade_policy_denial: {
+                                        reason: decision.reason,
+                                        message: decision.message,
+                                    },
+                                },
+                            });
+                            return;
+                        }
+                    }
+                    transport.sendResponse(req.id, { action: 'accept', content: {}, _meta: null });
+                }
+                else {
+                    transport.sendResponse(req.id, { action: 'decline', content: null, _meta: null });
+                }
                 return;
             case 'account/chatgptAuthTokens/refresh': {
                 const message = 'codex app-server requires OPENAI_API_KEY for pathgrade and honors OPENAI_BASE_URL when set; ChatGPT/cached auth unsupported under transport=app-server';
@@ -347,6 +505,7 @@ function buildThreadStartParams(opts) {
         experimentalRawEvents: false,
         persistExtendedHistory: false,
         model: opts.model,
+        ...(opts.mcpConfig ? { config: opts.mcpConfig } : {}),
     };
 }
 function assembleTurnResult(args) {

package/dist/agents/codex.js

@@ -1,7 +1,11 @@
 import { TOOL_NAME_MAP, buildSummary, inferCodexExecAction, enrichSkillEvents } from '../tool-events.js';
 import { TranscriptAgent } from './transcript-agent.js';
+import { assertMcpRuntimeMountingSupportedForCodexExec } from '../providers/mcp-runtime-mounting.js';
 export class CodexAgent extends TranscriptAgent {
     async runTurn(instruction, runCommand, options) {
+        await assertMcpRuntimeMountingSupportedForCodexExec({
+            mcpConfigPath: options?.mcpConfigPath,
+        });
         const promptPath = await this.writePromptFile(instruction, runCommand);
         const command = buildCodexExecCommand(promptPath, options?.model);
         const result = await runCommand(command);

package/dist/agents/cursor.js

@@ -1,9 +1,8 @@
-import fs from 'fs-extra';
-import path from 'path';
 import { BaseAgent, getWorkspacePath } from '../types.js';
 import { TOOL_NAME_MAP, buildSummary, enrichSkillEvents } from '../tool-events.js';
 import { getVisibleAssistantMessage } from '../sdk/visible-turn.js';
 import { prependRuntimePolicies } from '../sdk/runtime-policy.js';
+import { mountMcpForCursor } from '../providers/mcp-runtime-mounting.js';
 /**
  * Cursor tool_call discriminants observed in the discovery spike. Probed in
  * order — first present key wins. Explicit probing (vs. `Object.keys(…)[0]`)
@@ -188,18 +187,12 @@ export class CursorAgent extends BaseAgent {
         const promptPath = '"${TMPDIR:-/tmp}/.pathgrade-cursor-prompt.md"';
         const b64 = Buffer.from(effectiveInstruction).toString('base64');
         await runCommand(`mkdir -p "\${TMPDIR:-/tmp}" && echo '${b64}' | base64 -d > ${promptPath}`);
-        // Materialize .cursor/mcp.json from pathgrade's MCP config so the
-        // CLI's native loader picks it up. Idempotent per turn.
-        if (options?.mcpConfigPath) {
-            const srcMcp = path.join(workspacePath, options.mcpConfigPath);
-            if (await fs.pathExists(srcMcp)) {
-                const cursorDir = path.join(workspacePath, '.cursor');
-                await fs.ensureDir(cursorDir);
-                await fs.copy(srcMcp, path.join(cursorDir, 'mcp.json'), { overwrite: true });
-            }
-        }
+        const mcpMount = await mountMcpForCursor({
+            workspacePath,
+            mcpConfigPath: options?.mcpConfigPath,
+        });
         const modelFlag = options?.model ? ` --model ${options.model}` : '';
-        const mcpFlag = options?.mcpConfigPath ? ' --approve-mcps' : '';
+        const mcpFlag = mcpMount.approveMcps ? ' --approve-mcps' : '';
         const resumeFlag = sessionId ? ` --resume ${this.sanitizeSessionId(sessionId)}` : '';
         const command = `${CURSOR_EXECUTABLE} -p --output-format stream-json --trust --force --workspace "${workspacePath}"${resumeFlag}${modelFlag}${mcpFlag} "$(cat ${promptPath})" < /dev/null`;
         const result = await runCommand(command);

package/dist/providers/mcp-config.d.ts

@@ -3,32 +3,40 @@ import type { MockMcpServerDescriptor } from '../core/mcp-mock.types.js';
  * Stdio-server shape pathgrade writes to `.pathgrade-mcp.json`. Lines up
  * directly with the SDK's `McpStdioServerConfig` (`sdk.d.ts:1005`) — the
  * optional `type: 'stdio'` discriminator is omitted because the JSON
- * `writeMcpConfig` produces does not include it.
+ * `stageMcpConfig` produces does not include it.
  */
 export interface McpStdioEntry {
     command: string;
     args?: string[];
     env?: Record<string, string>;
+    startup_timeout_sec?: number;
+    tool_timeout_sec?: number;
 }
-/** Object form of MCP server entries the SDK driver passes to `Options.mcpServers`. */
-export type McpServersObject = Record<string, McpStdioEntry>;
-export type McpSpec = {
+export interface McpStreamableHttpEntry {
+    type?: 'streamable-http' | 'http';
+    url: string;
+    headers?: Record<string, string>;
+    http_headers?: Record<string, string>;
+    env_http_headers?: Record<string, string>;
+    bearer_token_env_var?: string;
+    startup_timeout_sec?: number;
+    tool_timeout_sec?: number;
+}
+export type McpConfigFileEntry = McpStdioEntry | McpStreamableHttpEntry;
+export type McpDeclaration = {
     configFile: string;
 } | {
     mock: MockMcpServerDescriptor | MockMcpServerDescriptor[];
 };
+export declare const MCP_CONFIG_FILENAME = ".pathgrade-mcp.json";
+export declare function readStagedMcpServers(workspacePath: string, mcpConfigPath?: string): Promise<Record<string, McpConfigFileEntry> | undefined>;
+export declare function missingMcpSecretReferences(mcpServers: Record<string, McpConfigFileEntry> | undefined, env: Record<string, string | undefined>): string[];
+export declare function assertMcpSecretReferencesReady(opts: {
+    workspacePath: string;
+    mcpConfigPath?: string;
+    env: Record<string, string | undefined>;
+}): Promise<void>;
 export interface McpConfigResult {
     mcpConfigPath: string | undefined;
 }
-export declare function writeMcpConfig(workspacePath: string, mcp: McpSpec | undefined): Promise<McpConfigResult>;
-/**
- * Read the JSON `writeMcpConfig` writes into `<workspace>/.pathgrade-mcp.json`
- * and return the inner `mcpServers` object the Claude SDK driver hands to
- * `Options.mcpServers`. Returns `undefined` when the file is absent (the
- * "no MCP" path through the driver — the fixture didn't declare an `mcp` spec).
- *
- * The on-disk path is preserved because the Cursor agent driver still
- * consumes it via `mcpConfigPath` (`src/agents/cursor.ts`) — Claude moves to
- * the object form, Cursor stays on the file.
- */
-export declare function loadMcpServersForSdk(workspacePath: string): Promise<McpServersObject | undefined>;
+export declare function stageMcpConfig(workspacePath: string, mcp: McpDeclaration | undefined): Promise<McpConfigResult>;

package/dist/providers/mcp-config.js

@@ -1,7 +1,132 @@
 import fs from 'fs-extra';
 import * as path from 'path';
-const MCP_CONFIG_FILENAME = '.pathgrade-mcp.json';
-export async function writeMcpConfig(workspacePath, mcp) {
+export const MCP_CONFIG_FILENAME = '.pathgrade-mcp.json';
+const GENERATED_MOCK_SERVER_FILENAME = '.pathgrade-mcp-mock-server.cjs';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isStringRecord(value) {
+    return isRecord(value)
+        && Object.values(value).every((entry) => typeof entry === 'string');
+}
+function assertOptionalStringRecord(serverName, fieldName, value) {
+    if (value !== undefined && !isStringRecord(value)) {
+        throw new Error(`Invalid MCP server "${serverName}": ${fieldName} must be a string record`);
+    }
+}
+function assertOptionalStringArray(serverName, fieldName, value) {
+    if (value !== undefined && (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string'))) {
+        throw new Error(`Invalid MCP server "${serverName}": ${fieldName} must be a string array`);
+    }
+}
+function assertOptionalNumber(serverName, fieldName, value) {
+    if (value !== undefined && typeof value !== 'number') {
+        throw new Error(`Invalid MCP server "${serverName}": ${fieldName} must be a number`);
+    }
+}
+function validateMcpConfigFileEntry(serverName, entry) {
+    if (!isRecord(entry)) {
+        throw new Error(`Invalid MCP server "${serverName}": entry must be an object`);
+    }
+    const hasCommand = entry.command !== undefined;
+    const hasUrl = entry.url !== undefined;
+    if (hasCommand && hasUrl) {
+        throw new Error(`Invalid MCP server "${serverName}": must not define both command and url`);
+    }
+    if (hasCommand) {
+        if (typeof entry.command !== 'string') {
+            throw new Error(`Invalid MCP server "${serverName}": command must be a string`);
+        }
+        assertOptionalStringArray(serverName, 'args', entry.args);
+        assertOptionalStringRecord(serverName, 'env', entry.env);
+        assertOptionalNumber(serverName, 'startup_timeout_sec', entry.startup_timeout_sec);
+        assertOptionalNumber(serverName, 'tool_timeout_sec', entry.tool_timeout_sec);
+        return entry;
+    }
+    if (!hasUrl) {
+        throw new Error(`Invalid MCP server "${serverName}": expected command or url`);
+    }
+    if (entry.type !== undefined && entry.type !== 'streamable-http' && entry.type !== 'http') {
+        throw new Error(`Unsupported MCP server type for "${serverName}": ${String(entry.type)}`);
+    }
+    if (typeof entry.url !== 'string') {
+        throw new Error(`Invalid MCP server "${serverName}": url must be a string`);
+    }
+    assertOptionalStringRecord(serverName, 'headers', entry.headers);
+    assertOptionalStringRecord(serverName, 'http_headers', entry.http_headers);
+    assertOptionalStringRecord(serverName, 'env_http_headers', entry.env_http_headers);
+    if (entry.bearer_token_env_var !== undefined && typeof entry.bearer_token_env_var !== 'string') {
+        throw new Error(`Invalid MCP server "${serverName}": bearer_token_env_var must be a string`);
+    }
+    assertOptionalNumber(serverName, 'startup_timeout_sec', entry.startup_timeout_sec);
+    assertOptionalNumber(serverName, 'tool_timeout_sec', entry.tool_timeout_sec);
+    return entry;
+}
+function readMcpServers(parsed) {
+    if (!isRecord(parsed) || !isRecord(parsed.mcpServers))
+        return undefined;
+    return Object.fromEntries(Object.entries(parsed.mcpServers).map(([name, entry]) => [
+        name,
+        validateMcpConfigFileEntry(name, entry),
+    ]));
+}
+export async function readStagedMcpServers(workspacePath, mcpConfigPath = MCP_CONFIG_FILENAME) {
+    const configPath = path.join(workspacePath, mcpConfigPath);
+    if (!(await fs.pathExists(configPath)))
+        return undefined;
+    return readMcpServers(await fs.readJson(configPath));
+}
+export function missingMcpSecretReferences(mcpServers, env) {
+    if (!mcpServers)
+        return [];
+    const missing = [];
+    for (const [serverName, entry] of Object.entries(mcpServers)) {
+        if ('env_http_headers' in entry) {
+            for (const envVar of Object.values(entry.env_http_headers ?? {})) {
+                if (!env[envVar])
+                    missing.push(`${serverName}: env_http_headers references ${envVar}`);
+            }
+        }
+        if ('bearer_token_env_var' in entry && entry.bearer_token_env_var && !env[entry.bearer_token_env_var]) {
+            missing.push(`${serverName}: bearer_token_env_var references ${entry.bearer_token_env_var}`);
+        }
+    }
+    return missing;
+}
+export async function assertMcpSecretReferencesReady(opts) {
+    const mcpServers = await readStagedMcpServers(opts.workspacePath, opts.mcpConfigPath);
+    const missing = missingMcpSecretReferences(mcpServers, opts.env);
+    if (missing.length > 0) {
+        throw new Error(`Missing MCP secret references: ${missing.join('; ')}`);
+    }
+}
+async function resolveMockServerScript(workspacePath) {
+    const compiledScript = path.resolve(import.meta.dirname, '../mcp-mock-server.js');
+    if (await fs.pathExists(compiledScript))
+        return compiledScript;
+    const sourceScript = path.resolve(import.meta.dirname, '../mcp-mock-server.ts');
+    if (!await fs.pathExists(sourceScript)) {
+        throw new Error(`Mock MCP server source not found: ${sourceScript}`);
+    }
+    const ts = await import('typescript');
+    const source = await fs.readFile(sourceScript, 'utf-8');
+    const transpiled = ts.transpileModule(source, {
+        compilerOptions: {
+            target: ts.ScriptTarget.ES2022,
+            module: ts.ModuleKind.CommonJS,
+            esModuleInterop: true,
+        },
+        fileName: sourceScript,
+    });
+    const generatedScript = path.join(workspacePath, GENERATED_MOCK_SERVER_FILENAME);
+    await fs.writeFile(generatedScript, [
+        '// Generated by PathGrade from src/mcp-mock-server.ts.',
+        '// This trial-local file lets external agent runtimes spawn the mock server with plain node.',
+        transpiled.outputText,
+    ].join('\n'));
+    return generatedScript;
+}
+export async function stageMcpConfig(workspacePath, mcp) {
     if (!mcp)
         return { mcpConfigPath: undefined };
     const mcpConfigPath = MCP_CONFIG_FILENAME;
@@ -21,12 +146,12 @@ export async function writeMcpConfig(workspacePath, mcp) {
             }
             seen.add(mock.config.name);
         }
+        const mockServerScript = await resolveMockServerScript(workspacePath);
         const mcpServers = {};
         for (const mock of mocks) {
             const sanitizedName = mock.config.name.replace(/[^a-zA-Z0-9-]/g, '-');
             const fixturePath = path.join(workspacePath, `.pathgrade-mcp-mock-${sanitizedName}.json`);
             await fs.writeJson(fixturePath, mock.config, { spaces: 2 });
-            const mockServerScript = path.resolve(import.meta.dirname, '../mcp-mock-server.js');
             mcpServers[mock.config.name] = {
                 command: 'node',
                 args: [mockServerScript, fixturePath],
@@ -36,20 +161,3 @@ export async function writeMcpConfig(workspacePath, mcp) {
     }
     return { mcpConfigPath };
 }
-/**
- * Read the JSON `writeMcpConfig` writes into `<workspace>/.pathgrade-mcp.json`
- * and return the inner `mcpServers` object the Claude SDK driver hands to
- * `Options.mcpServers`. Returns `undefined` when the file is absent (the
- * "no MCP" path through the driver — the fixture didn't declare an `mcp` spec).
- *
- * The on-disk path is preserved because the Cursor agent driver still
- * consumes it via `mcpConfigPath` (`src/agents/cursor.ts`) — Claude moves to
- * the object form, Cursor stays on the file.
- */
-export async function loadMcpServersForSdk(workspacePath) {
-    const configPath = path.join(workspacePath, MCP_CONFIG_FILENAME);
-    if (!(await fs.pathExists(configPath)))
-        return undefined;
-    const parsed = (await fs.readJson(configPath));
-    return parsed.mcpServers;
-}