@wix/pathgrade 0.31.0 → 0.33.0

package/dist/providers/mcp-runtime-mounting.d.ts

@@ -0,0 +1,36 @@
+import type { McpStdioEntry } from './mcp-config.js';
+export type ClaudeSdkMcpServerEntry = McpStdioEntry | {
+    type: 'http';
+    url: string;
+    headers?: Record<string, string>;
+};
+/** Object form of MCP server entries the SDK driver passes to `Options.mcpServers`. */
+export type McpServersObject = Record<string, ClaudeSdkMcpServerEntry>;
+export type CodexMcpServerEntry = McpStdioEntry | {
+    url: 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 interface CodexAppServerMcpConfig extends Record<string, unknown> {
+    mcp_servers: Record<string, unknown>;
+}
+export interface McpRuntimeMountingOptions {
+    workspacePath?: string;
+    mcpConfigPath?: string;
+}
+interface WorkspaceMcpRuntimeMountingOptions extends McpRuntimeMountingOptions {
+    workspacePath: string;
+    runtimeEnv?: Record<string, string>;
+}
+export interface CursorMcpRuntimeMount {
+    approveMcps: boolean;
+}
+export declare function assertStdioMcpServersStartForClaudeSdk(options: WorkspaceMcpRuntimeMountingOptions): Promise<void>;
+export declare function mountMcpForClaudeSdk(options: WorkspaceMcpRuntimeMountingOptions): Promise<McpServersObject | undefined>;
+export declare function mountMcpForCodexAppServer(options: WorkspaceMcpRuntimeMountingOptions): Promise<CodexAppServerMcpConfig | undefined>;
+export declare function mountMcpForCursor(options: WorkspaceMcpRuntimeMountingOptions): Promise<CursorMcpRuntimeMount>;
+export declare function assertMcpRuntimeMountingSupportedForCodexExec(options: McpRuntimeMountingOptions): Promise<void>;
+export {};

package/dist/providers/mcp-runtime-mounting.js

@@ -0,0 +1,116 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { readStagedMcpServers } from './mcp-config.js';
+function isStdioEntry(entry) {
+    return typeof entry.command === 'string';
+}
+function headersForRemote(entry) {
+    return entry.headers ?? entry.http_headers;
+}
+function compact(entry) {
+    return Object.fromEntries(Object.entries(entry).filter(([, value]) => value !== undefined));
+}
+function toClaudeSdkMcpServerEntry(entry) {
+    if (isStdioEntry(entry))
+        return entry;
+    return compact({
+        type: 'http',
+        url: entry.url,
+        headers: headersForRemote(entry),
+    });
+}
+function toCodexAppServerMcpServerEntry(entry) {
+    if (isStdioEntry(entry))
+        return entry;
+    return compact({
+        url: entry.url,
+        http_headers: headersForRemote(entry),
+        env_http_headers: entry.env_http_headers,
+        bearer_token_env_var: entry.bearer_token_env_var,
+        startup_timeout_sec: entry.startup_timeout_sec,
+        tool_timeout_sec: entry.tool_timeout_sec,
+    });
+}
+function formatMcpStartupError(serverName, error, stderr) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stderrSuffix = stderr.trim() ? `\nstderr:\n${stderr.trim()}` : '';
+    return new Error(`MCP server ${serverName} failed to start: ${message}${stderrSuffix}`);
+}
+async function assertStdioMcpServerStarts(workspacePath, serverName, entry, runtimeEnv) {
+    const timeoutMs = Math.max(1, entry.startup_timeout_sec ?? 15) * 1000;
+    const transport = new StdioClientTransport({
+        command: entry.command,
+        args: entry.args,
+        env: {
+            ...(runtimeEnv ?? {}),
+            ...(entry.env ?? {}),
+        },
+        cwd: workspacePath,
+        stderr: 'pipe',
+    });
+    let stderr = '';
+    transport.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString();
+    });
+    const client = new Client({ name: 'pathgrade-stdio-mcp-preflight', version: '0.5.0' }, { capabilities: {} });
+    try {
+        await client.connect(transport, { timeout: timeoutMs });
+        await client.listTools(undefined, { timeout: timeoutMs });
+    }
+    catch (error) {
+        throw formatMcpStartupError(serverName, error, stderr);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+        await transport.close().catch(() => undefined);
+    }
+}
+export async function assertStdioMcpServersStartForClaudeSdk(options) {
+    const mcpServers = await readStagedMcpServers(options.workspacePath, options.mcpConfigPath);
+    if (!mcpServers)
+        return;
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        if (!isStdioEntry(entry))
+            continue;
+        await assertStdioMcpServerStarts(options.workspacePath, name, entry, options.runtimeEnv);
+    }
+}
+export async function mountMcpForClaudeSdk(options) {
+    const mcpServers = await readStagedMcpServers(options.workspacePath, options.mcpConfigPath);
+    if (!mcpServers)
+        return undefined;
+    return Object.fromEntries(Object.entries(mcpServers).map(([name, entry]) => [
+        name,
+        toClaudeSdkMcpServerEntry(entry),
+    ]));
+}
+export async function mountMcpForCodexAppServer(options) {
+    const mcpServers = await readStagedMcpServers(options.workspacePath, options.mcpConfigPath);
+    if (!mcpServers)
+        return undefined;
+    return {
+        mcp_servers: Object.fromEntries(Object.entries(mcpServers).map(([name, entry]) => [
+            name,
+            toCodexAppServerMcpServerEntry(entry),
+        ])),
+    };
+}
+export async function mountMcpForCursor(options) {
+    if (!options.mcpConfigPath)
+        return { approveMcps: false };
+    await readStagedMcpServers(options.workspacePath, options.mcpConfigPath);
+    const srcMcp = path.join(options.workspacePath, options.mcpConfigPath);
+    if (!(await fs.pathExists(srcMcp)))
+        return { approveMcps: false };
+    const cursorDir = path.join(options.workspacePath, '.cursor');
+    await fs.ensureDir(cursorDir);
+    await fs.copy(srcMcp, path.join(cursorDir, 'mcp.json'), { overwrite: true });
+    return { approveMcps: true };
+}
+export async function assertMcpRuntimeMountingSupportedForCodexExec(options) {
+    if (!options.mcpConfigPath)
+        return;
+    throw new Error('Codex exec does not support MCP Runtime Mounting. Use the codex app-server transport for fixtures that stage MCP config.');
+}

package/dist/providers/sandbox.d.ts

@@ -4,7 +4,7 @@ export interface SandboxConfig {
     skillDir?: string;
     copyFromHome?: string[];
     env?: Record<string, string>;
-    mcp?: import('./mcp-config.js').McpSpec;
+    mcp?: import('./mcp-config.js').McpDeclaration;
     /**
      * Glob patterns to ignore when copying workspace and skill directories.
      * Replaces the default ignore list entirely. Pass `[]` to disable filtering.

package/dist/providers/workspace.d.ts

@@ -1,6 +1,6 @@
 import { type SandboxConfig } from './sandbox.js';
 import type { CommandResult } from '../types.js';
-export type { McpSpec } from './mcp-config.js';
+export type { McpDeclaration } from './mcp-config.js';
 export interface Workspace {
     readonly path: string;
     readonly mcpConfigPath: string | undefined;

package/dist/providers/workspace.js

@@ -2,7 +2,7 @@ import fs from 'fs-extra';
 import * as os from 'os';
 import * as path from 'path';
 import { createSandbox } from './sandbox.js';
-import { writeMcpConfig } from './mcp-config.js';
+import { stageMcpConfig } from './mcp-config.js';
 import { sandboxExec } from './sandbox-exec.js';
 import { resolveCredentials } from './credentials.js';
 async function copyPathsFromHostHome(pathsToCopy, sandboxHomePath) {
@@ -38,7 +38,7 @@ export async function prepareWorkspace(spec) {
         Object.assign(sandboxEnv, creds.env);
         await copyPathsFromHostHome(creds.copyFromHome, homePath);
         await linkPathsFromHostHome(creds.linkFromHome ?? [], homePath);
-        const { mcpConfigPath } = await writeMcpConfig(workspacePath, mcp);
+        const { mcpConfigPath } = await stageMcpConfig(workspacePath, mcp);
         let disposed = false;
         return {
             path: workspacePath,

package/dist/sdk/agent.js

@@ -39,7 +39,8 @@ class AgentImpl {
     lastConversationResult = null;
     verbose;
     transport;
-    constructor(ws, agentName, llm, timeoutSetting, conversationWindow, modelOpt, debugOpt, debugName, debugBaseDir, verbose, transport) {
+    mcpSafety;
+    constructor(ws, agentName, llm, timeoutSetting, conversationWindow, modelOpt, debugOpt, debugName, debugBaseDir, verbose, transport, mcpSafety) {
         this.ws = ws;
         this.agentName = agentName;
         this.llm = llm;
@@ -51,6 +52,7 @@ class AgentImpl {
         this.debugBaseDir = debugBaseDir;
         this.verbose = verbose;
         this.transport = transport;
+        this.mcpSafety = mcpSafety;
     }
     get messages() {
         return this._messages;
@@ -79,6 +81,7 @@ class AgentImpl {
             llm: this.llm,
             ...(askUserTimeoutMs !== undefined ? { askUserTimeoutMs } : {}),
             ...(this.transport !== undefined ? { transport: this.transport } : {}),
+            ...(this.mcpSafety !== undefined ? { mcpSafety: this.mcpSafety } : {}),
         });
     }
     resolveTimeoutSec(mode, maxTurns) {
@@ -345,11 +348,11 @@ export async function createAgent(opts) {
     const timeoutSetting = opts.timeout ?? 300;
     // Capture test context now, while vitest state is available
     const testCtx = opts.debug ? resolveTestContext() : { name: '', dir: '' };
-    const { timeout: _, mcpMock, agent: __, debug: ___, model: ____, transport: _____, ...rest } = opts;
+    const { timeout: _, mcpMock, mcpConfigFile, agent: __, debug: ___, model: ____, transport: _____, mcpSafety: ______, ...rest } = opts;
     const workspace = await prepareWorkspace({
         ...rest,
         agent: agentName,
-        mcp: mcpMock ? { mock: mcpMock } : undefined,
+        mcp: mcpConfigFile ? { configFile: mcpConfigFile } : mcpMock ? { mock: mcpMock } : undefined,
     });
     // Create agent LLM once, using the fully-resolved sandbox env (includes
     // keychain OAuth tokens, API keys, safe host vars).
@@ -363,7 +366,7 @@ export async function createAgent(opts) {
         sink: verboseSinkOverride ?? undefined,
         testName: testCtx.name || undefined,
     });
-    const agent = new AgentImpl(workspace, agentName, llm, timeoutSetting, opts.conversationWindow, opts.model, opts.debug, debugName, debugBaseDir, verbose, transport);
+    const agent = new AgentImpl(workspace, agentName, llm, timeoutSetting, opts.conversationWindow, opts.model, opts.debug, debugName, debugBaseDir, verbose, transport, opts.mcpSafety);
     lifecycle.trackAgent(agent);
     return agent;
 }

package/dist/sdk/index.d.ts

@@ -2,6 +2,8 @@ export { createAgent } from './agent.js';
 export { resolveAgentName, resolveCodexTransport, InvalidTransportEnvError, } from './agent-resolution.js';
 export { AgentCrashError } from './agent-crash.js';
 export { check, score, judge, toolUsage } from './scorers.js';
+export { getMcpToolCall, isMcpToolCall, findMcpToolCalls, getMcpStartupStatus, isMcpStartupStatus, } from './mcp-evidence.js';
+export { decideMcpToolCall, redactMcpSecrets, } from './mcp-safety.js';
 export { evaluate, EvalScorerError } from './evaluate.js';
 export { RUN_SNAPSHOT_VERSION, buildRunSnapshot, loadRunSnapshot, SnapshotParseError, SnapshotVersionError, WorkspaceMissingError, } from './snapshots.js';
 export { createPersona } from './persona.js';
@@ -16,14 +18,17 @@ export { toAskUserToolEvent } from './ask-bus/projection.js';
 export type { AskUserToolEvent, AskUserToolEventArguments, AskUserToolEventQuestionArgument, } from './ask-bus/projection.js';
 export { buildAskBatchLogEntries } from './agent-result-log.js';
 export { getAgentCapabilities } from './types.js';
-export type { AgentTransport, AgentCapabilities, AgentName } from './types.js';
+export type { AgentTransport, AgentCapabilities, AgentName, McpRunMode, McpSafetyOptions, McpToolPolicy, McpToolPolicyRule, } from './types.js';
 export type { AskBus, AskBatch, AskQuestion, AskOption, AskAnswer, AskResolution, AskBatchSnapshot, AskAnswerSnapshot, AskResolutionSnapshot, AskHandle, AskHandler, AskSource, AskLifecycle, AskAnswerSource, Unsubscribe as AskBusUnsubscribe, } from './ask-bus/types.js';
-export type { Agent, AgentOptions, Message, Scorer, CheckScorer, ScoreScorer, JudgeScorer, ToolUsageScorer, ScorerContext, EvalResult, ScorerResultEntry, ScorerStatus, ChatSession, ConversationResult, ConverseOptions, Reaction, TextReaction, AskUserReaction, AskUserQuestion, AskUserOption, ReactionPreviewEntry, TextReactionPreviewEntry, AskUserReactionPreviewEntry, ReactionPreviewResult, ReactionPreviewTurn, Persona, PersonaConfig, ConversationWindowConfig, PathgradePluginOptions, PathgradeMeta, TurnTiming, TokenUsage, EvaluateOptions, ReactionPreviewStatus, } from './types.js';
+export type { Agent, AgentOptions, Message, Scorer, CheckScorer, ScoreScorer, JudgeScorer, ToolUsageScorer, ScorerContext, EvalResult, ScorerResultEntry, ScorerStatus, ChatSession, ConversationResult, ConverseOptions, UntilPredicate, UntilContext, Reaction, TextReaction, AskUserReaction, AskUserQuestion, AskUserOption, ReactionPreviewEntry, TextReactionPreviewEntry, AskUserReactionPreviewEntry, ReactionPreviewResult, ReactionPreviewTurn, StepScorer, Persona, PersonaConfig, ConversationWindowConfig, TurnDetail, ReactionFiredEntry, PathgradePluginOptions, PathgradeMeta, TurnTiming, TokenUsage, EvaluateOptions, ReactionPreviewStatus, ScoreResult, JudgeInput, CodeJudgeToolName, ToolExpectation, SessionArtifactMatchOptions, SessionArtifactContent, SessionArtifacts, RecordedEvalResult, PathgradeTestMeta, } from './types.js';
 export type { ConversationWindow, ConversationWindowOptions } from './conversation-window.js';
 export type { JudgePipelineOptions } from './judge-pipeline.js';
 export type { RunScorerOptions } from './run-scorer.js';
 export type { OnScorerErrorMode } from './evaluate.js';
 export type { RunSnapshot } from './snapshots.js';
+export type { ExpectedMcpStartupStatus, ExpectedMcpToolCall, McpStartupStatusEvidence, McpToolCallEvidence, } from './mcp-evidence.js';
+export type { McpPolicyDenialReason, McpToolCallRequest, McpToolPolicyDecision, } from './mcp-safety.js';
+export type { ToolEvent } from '../tool-events.js';
 export type { LLMPort, EvalRuntime } from './eval-runtime.js';
 export { createLLMClient, ProviderNotSupportedError } from '../utils/llm.js';
 export type { CreateLLMClientOptions, LLMProviderAdapter, TokenUsage as LLMTokenUsage } from '../utils/llm.js';

package/dist/sdk/index.js

@@ -3,6 +3,8 @@ export { createAgent } from './agent.js';
 export { resolveAgentName, resolveCodexTransport, InvalidTransportEnvError, } from './agent-resolution.js';
 export { AgentCrashError } from './agent-crash.js';
 export { check, score, judge, toolUsage } from './scorers.js';
+export { getMcpToolCall, isMcpToolCall, findMcpToolCalls, getMcpStartupStatus, isMcpStartupStatus, } from './mcp-evidence.js';
+export { decideMcpToolCall, redactMcpSecrets, } from './mcp-safety.js';
 export { evaluate, EvalScorerError } from './evaluate.js';
 export { RUN_SNAPSHOT_VERSION, buildRunSnapshot, loadRunSnapshot, SnapshotParseError, SnapshotVersionError, WorkspaceMissingError, } from './snapshots.js';
 export { createPersona } from './persona.js';

package/dist/sdk/managed-session.d.ts

@@ -1,6 +1,7 @@
 import type { AgentTurnResult, LogEntry } from '../types.js';
 import type { Workspace } from '../providers/workspace.js';
 import type { AgentName, AgentTransport, Message } from './types.js';
+import type { McpSafetyOptions } from './mcp-safety.js';
 import type { LLMPort } from '../utils/llm-types.js';
 import type { AskBus } from './ask-bus/types.js';
 export interface ManagedSessionDeps {
@@ -28,6 +29,8 @@ export interface ManagedSessionDeps {
      * driver capabilities fall back to the default (`exec` semantics).
      */
     transport?: AgentTransport;
+    /** Live MCP Server Safety policy to enforce in supported harnesses. */
+    mcpSafety?: McpSafetyOptions;
 }
 export interface ManagedSession {
     /** Full lifecycle: log start/result, push messages, check exit code. */

package/dist/sdk/managed-session.js

@@ -23,6 +23,8 @@ export function createManagedSession(deps) {
         ...(llm ? { llm } : {}),
         askBus,
         ...(transport !== undefined ? { transport } : {}),
+        ...(deps.mcpSafety !== undefined ? { mcpSafety: deps.mcpSafety } : {}),
+        getAbortSignal: () => currentSignal,
     };
     let session = null;
     let setupDone = false;

package/dist/sdk/mcp-evidence.d.ts

@@ -0,0 +1,29 @@
+import type { ToolEvent } from '../tool-events.js';
+export interface McpToolCallEvidence {
+    serverName: string;
+    toolName: string;
+    status: string;
+    arguments: Record<string, unknown>;
+    event: ToolEvent;
+}
+export interface ExpectedMcpToolCall {
+    serverName?: string;
+    toolName?: string;
+    status?: string;
+    argumentsContaining?: Record<string, unknown>;
+}
+export interface McpStartupStatusEvidence {
+    serverName: string;
+    status: string;
+    error?: string;
+    event: ToolEvent;
+}
+export interface ExpectedMcpStartupStatus {
+    serverName?: string;
+    status?: string;
+}
+export declare function getMcpToolCall(event: ToolEvent): McpToolCallEvidence | undefined;
+export declare function isMcpToolCall(event: ToolEvent, expected?: ExpectedMcpToolCall): boolean;
+export declare function findMcpToolCalls(events: readonly ToolEvent[], expected?: ExpectedMcpToolCall): McpToolCallEvidence[];
+export declare function getMcpStartupStatus(event: ToolEvent): McpStartupStatusEvidence | undefined;
+export declare function isMcpStartupStatus(event: ToolEvent, expected?: ExpectedMcpStartupStatus): boolean;

package/dist/sdk/mcp-evidence.js

@@ -0,0 +1,96 @@
+export function getMcpToolCall(event) {
+    if (event.action !== 'mcp_tool_call')
+        return undefined;
+    const args = event.arguments ?? {};
+    const serverName = typeof args.server === 'string' ? args.server : undefined;
+    const toolName = typeof args.tool === 'string' ? args.tool : undefined;
+    const status = typeof args.status === 'string' ? args.status : undefined;
+    if (!serverName || !toolName || !status)
+        return undefined;
+    return {
+        serverName,
+        toolName,
+        status,
+        arguments: args,
+        event,
+    };
+}
+export function isMcpToolCall(event, expected = {}) {
+    const call = getMcpToolCall(event);
+    if (!call)
+        return false;
+    if (expected.serverName !== undefined && call.serverName !== expected.serverName)
+        return false;
+    if (expected.toolName !== undefined && call.toolName !== expected.toolName)
+        return false;
+    if (expected.status !== undefined && call.status !== expected.status)
+        return false;
+    if (expected.argumentsContaining && !containsArguments(call.arguments, expected.argumentsContaining)) {
+        return false;
+    }
+    return true;
+}
+export function findMcpToolCalls(events, expected = {}) {
+    return events
+        .map((event) => getMcpToolCall(event))
+        .filter((call) => call !== undefined && matchesMcpToolCall(call, expected));
+}
+export function getMcpStartupStatus(event) {
+    if (event.providerToolName !== 'mcpServer/startupStatus/updated')
+        return undefined;
+    const args = event.arguments ?? {};
+    const serverName = typeof args.name === 'string' ? args.name : undefined;
+    const status = typeof args.status === 'string' ? args.status : undefined;
+    if (!serverName || !status)
+        return undefined;
+    const error = typeof args.error === 'string' ? args.error : undefined;
+    return {
+        serverName,
+        status,
+        ...(error ? { error } : {}),
+        event,
+    };
+}
+export function isMcpStartupStatus(event, expected = {}) {
+    const startup = getMcpStartupStatus(event);
+    if (!startup)
+        return false;
+    if (expected.serverName !== undefined && startup.serverName !== expected.serverName)
+        return false;
+    if (expected.status !== undefined && startup.status !== expected.status)
+        return false;
+    return true;
+}
+function matchesMcpToolCall(call, expected) {
+    if (expected.serverName !== undefined && call.serverName !== expected.serverName)
+        return false;
+    if (expected.toolName !== undefined && call.toolName !== expected.toolName)
+        return false;
+    if (expected.status !== undefined && call.status !== expected.status)
+        return false;
+    if (expected.argumentsContaining && !containsArguments(call.arguments, expected.argumentsContaining)) {
+        return false;
+    }
+    return true;
+}
+function containsArguments(actual, expected) {
+    return Object.entries(expected).every(([key, expectedValue]) => valuesEqual(actual[key], expectedValue));
+}
+function valuesEqual(actual, expected) {
+    if (Object.is(actual, expected))
+        return true;
+    if (Array.isArray(actual) || Array.isArray(expected)) {
+        if (!Array.isArray(actual) || !Array.isArray(expected))
+            return false;
+        if (actual.length !== expected.length)
+            return false;
+        return actual.every((value, index) => valuesEqual(value, expected[index]));
+    }
+    if (isRecord(actual) && isRecord(expected)) {
+        return Object.entries(expected).every(([key, value]) => valuesEqual(actual[key], value));
+    }
+    return false;
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/sdk/mcp-safety.d.ts

@@ -0,0 +1,30 @@
+export type McpRunMode = 'mock' | 'live-readonly' | 'live-sandbox' | 'live';
+export interface McpToolPolicyRule {
+    serverName?: string;
+    toolName?: string;
+    readonly?: boolean;
+}
+export interface McpToolPolicy {
+    allow?: McpToolPolicyRule[];
+    deny?: McpToolPolicyRule[];
+}
+export interface McpSafetyOptions {
+    runMode?: McpRunMode;
+    liveOptIn?: boolean;
+    mcpToolPolicy?: McpToolPolicy;
+}
+export interface McpToolCallRequest {
+    serverName: string;
+    toolName: string;
+    arguments?: Record<string, unknown>;
+}
+export type McpPolicyDenialReason = 'missing_live_opt_in' | 'missing_mcp_tool_policy' | 'denylisted' | 'not_allowlisted' | 'not_marked_readonly';
+export type McpToolPolicyDecision = {
+    action: 'allow';
+} | {
+    action: 'deny';
+    reason: McpPolicyDenialReason;
+    message: string;
+};
+export declare function decideMcpToolCall(options: McpSafetyOptions | undefined, request: McpToolCallRequest): McpToolPolicyDecision;
+export declare function redactMcpSecrets<T>(value: T): T;

package/dist/sdk/mcp-safety.js

@@ -0,0 +1,61 @@
+const SECRET_KEY_PATTERN = /(^|[_-])(api[_-]?key|token|secret|password|authorization|auth|bearer)([_-]|$)|authorization/i;
+export function decideMcpToolCall(options, request) {
+    const runMode = options?.runMode ?? 'mock';
+    if (runMode === 'mock')
+        return { action: 'allow' };
+    if (!options?.liveOptIn) {
+        return deny('missing_live_opt_in', 'Live MCP tool calls require explicit mcpSafety.liveOptIn.');
+    }
+    const policy = options.mcpToolPolicy;
+    if (runMode === 'live-readonly' && !policy) {
+        return deny('missing_mcp_tool_policy', 'live-readonly MCP runs require an explicit mcpToolPolicy.');
+    }
+    const denyRule = policy?.deny?.find((rule) => ruleMatches(rule, request));
+    if (denyRule) {
+        return deny('denylisted', `MCP tool ${request.serverName}.${request.toolName} is denied by policy.`);
+    }
+    const allowRules = policy?.allow ?? [];
+    if (allowRules.length > 0) {
+        const allowRule = allowRules.find((rule) => ruleMatches(rule, request));
+        if (!allowRule) {
+            return deny('not_allowlisted', `MCP tool ${request.serverName}.${request.toolName} is not allowlisted.`);
+        }
+        if (runMode === 'live-readonly' && allowRule.readonly !== true) {
+            return deny('not_marked_readonly', `MCP tool ${request.serverName}.${request.toolName} is not marked readonly.`);
+        }
+        return { action: 'allow' };
+    }
+    if (runMode === 'live-readonly') {
+        return deny('not_allowlisted', `MCP tool ${request.serverName}.${request.toolName} is not allowlisted.`);
+    }
+    return { action: 'allow' };
+}
+export function redactMcpSecrets(value) {
+    return redactValue(value, '');
+}
+function ruleMatches(rule, request) {
+    if (rule.serverName !== undefined && rule.serverName !== request.serverName)
+        return false;
+    if (rule.toolName !== undefined && rule.toolName !== request.toolName)
+        return false;
+    return true;
+}
+function deny(reason, message) {
+    return { action: 'deny', reason, message };
+}
+function redactValue(value, key) {
+    if (SECRET_KEY_PATTERN.test(key))
+        return '<redacted>';
+    if (Array.isArray(value))
+        return value.map((entry) => redactValue(entry, key));
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [
+            entryKey,
+            redactValue(entryValue, entryKey),
+        ]));
+    }
+    return value;
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/sdk/types.d.ts

@@ -4,6 +4,7 @@ import type { MockMcpServerDescriptor } from '../core/mcp-mock.types.js';
 import type { TrialResult } from '../types.js';
 import type { DiagnosticsReport } from '../reporters/diagnostics.js';
 import type { LLMPort } from '../utils/llm-types.js';
+import type { McpSafetyOptions } from './mcp-safety.js';
 export type AgentName = 'claude' | 'codex' | 'cursor';
 export interface AgentOptions {
     agent?: AgentName;
@@ -14,6 +15,7 @@ export interface AgentOptions {
     copyFromHome?: string[];
     env?: Record<string, string>;
     mcpMock?: MockMcpServerDescriptor | MockMcpServerDescriptor[];
+    mcpConfigFile?: string;
     /** Configure the conversation window for transcript-based agents. Set false to disable. */
     conversationWindow?: ConversationWindowConfig | false;
     /** Copy workspace to a persistent location before cleanup. true = ./pathgrade-debug/{test-name}/, string = custom path. */
@@ -31,7 +33,14 @@ export interface AgentOptions {
      * in v1 (documented but not enforced).
      */
     transport?: AgentTransport;
+    /**
+     * Live MCP Server Safety policy. `live-readonly` requires explicit
+     * `liveOptIn` plus an inspectable allow/deny policy before tools are
+     * approved by supported live harnesses.
+     */
+    mcpSafety?: McpSafetyOptions;
 }
+export type { McpRunMode, McpSafetyOptions, McpToolPolicy, McpToolPolicyRule, } from './mcp-safety.js';
 export interface ConversationWindowConfig {
     /** Number of recent messages to keep verbatim. Default: 4 */
     windowSize?: number;
@@ -350,8 +359,9 @@ export interface AgentCapabilities {
 }
 /**
  * Codex-specific transport. Claude and Cursor ignore this.
- * `app-server` unlocks `interactiveQuestionTransport: 'reliable'` for Codex;
- * `exec` (the default) keeps the `'noninteractive'` channel.
+ * `app-server` unlocks MCP Runtime Mounting and
+ * `interactiveQuestionTransport: 'reliable'` for Codex; `exec` keeps the
+ * `'noninteractive'` channel and has no MCP Runtime Mounting support.
  */
 export type AgentTransport = 'exec' | 'app-server';
 export declare function getAgentCapabilities(agent: AgentName, transport?: AgentTransport): AgentCapabilities;

package/dist/sdk/types.js

@@ -5,8 +5,8 @@ const BASE_CAPABILITIES = {
 };
 export function getAgentCapabilities(agent, transport) {
     const base = BASE_CAPABILITIES[agent];
-    if (agent === 'codex' && transport === 'app-server') {
-        return { ...base, interactiveQuestionTransport: 'reliable' };
+    if (agent === 'codex' && (transport ?? 'app-server') === 'app-server') {
+        return { ...base, mcp: true, interactiveQuestionTransport: 'reliable' };
     }
     return base;
 }

package/dist/tool-events.d.ts

@@ -1,4 +1,4 @@
-export type ToolAction = 'run_shell' | 'read_file' | 'write_file' | 'edit_file' | 'search_code' | 'list_files' | 'ask_user' | 'web_fetch' | 'use_skill' | 'update_todos' | 'unknown';
+export type ToolAction = 'run_shell' | 'read_file' | 'write_file' | 'edit_file' | 'search_code' | 'list_files' | 'ask_user' | 'web_fetch' | 'use_skill' | 'update_todos' | 'mcp_tool_call' | 'unknown';
 export interface ToolEvent {
     action: ToolAction;
     provider: 'claude' | 'codex' | 'cursor';

package/dist/types.d.ts

@@ -364,6 +364,12 @@ export interface AgentSessionOptions {
      * only `lifecycle: 'post-hoc'` no-op when absent.
      */
     askBus?: import('./sdk/ask-bus/types.js').AskBus;
+    /** Public live MCP safety policy threaded from createAgent(). */
+    mcpSafety?: import('./sdk/mcp-safety.js').McpSafetyOptions;
+    /** Per-turn timeout/cancellation signal owned by the managed session. */
+    abortSignal?: AbortSignal;
+    /** Supplies the current timeout/cancellation signal for reused sessions. */
+    getAbortSignal?: () => AbortSignal | undefined;
 }
 export declare abstract class BaseAgent {
     createSession(runtime: EnvironmentHandle, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;

package/dist/utils/timeout.js

@@ -8,24 +8,25 @@
 export function withAbortTimeout(run, timeoutMs, label) {
     return new Promise((resolve, reject) => {
         const controller = new AbortController();
-        let timedOut = false;
+        let settled = false;
         const timer = setTimeout(() => {
-            timedOut = true;
+            if (settled)
+                return;
+            settled = true;
             controller.abort();
+            reject(new Error(`${label} timed out after ${timeoutMs / 1000}s`));
         }, timeoutMs);
         run(controller.signal).then((val) => {
-            clearTimeout(timer);
-            if (timedOut || controller.signal.aborted) {
-                reject(new Error(`${label} timed out after ${timeoutMs / 1000}s`));
+            if (settled)
                 return;
-            }
+            settled = true;
+            clearTimeout(timer);
             resolve(val);
         }, (err) => {
-            clearTimeout(timer);
-            if (timedOut || controller.signal.aborted) {
-                reject(new Error(`${label} timed out after ${timeoutMs / 1000}s`));
+            if (settled)
                 return;
-            }
+            settled = true;
+            clearTimeout(timer);
             reject(err);
         });
     });