@wix/pathgrade 0.32.0 → 0.34.0

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 { assertUnsupportedLiveMcpSafetyRuntime, 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]`)
@@ -171,6 +170,12 @@ export class CursorAgent extends BaseAgent {
         return getVisibleAssistantMessage(result);
     }
     async runTurn(instruction, workspacePath, runCommand, sessionId, options) {
+        await assertUnsupportedLiveMcpSafetyRuntime({
+            runtimeName: 'Cursor',
+            workspacePath,
+            mcpConfigPath: options?.mcpConfigPath,
+            mcpSafety: options?.mcpSafety,
+        });
         // Runtime policies are injected into the first-turn prompt only.
         // On resumed turns (sessionId set) the policy was already delivered,
         // so we skip re-prepending. The Claude SDK driver does not prepend
@@ -188,18 +193,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;
-}

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

@@ -0,0 +1,46 @@
+import type { McpStdioEntry } from './mcp-config.js';
+import type { McpSafetyOptions } from '../sdk/mcp-safety.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>;
+}
+interface ClaudeLiveMcpSafetyPreflightOptions extends WorkspaceMcpRuntimeMountingOptions {
+    mcpSafety?: McpSafetyOptions;
+}
+interface UnsupportedLiveMcpSafetyRuntimeOptions extends WorkspaceMcpRuntimeMountingOptions {
+    runtimeName: string;
+    mcpSafety?: McpSafetyOptions;
+}
+export interface CursorMcpRuntimeMount {
+    approveMcps: boolean;
+}
+export declare function assertClaudeLiveMcpSafetyPreflight(options: ClaudeLiveMcpSafetyPreflightOptions): Promise<void>;
+export declare function assertUnsupportedLiveMcpSafetyRuntime(options: UnsupportedLiveMcpSafetyRuntimeOptions): Promise<void>;
+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,155 @@
+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 isLiveMcpSafetyMode(options) {
+    const runMode = options?.runMode ?? 'mock';
+    return runMode === 'live-readonly' || runMode === 'live-sandbox' || runMode === 'live';
+}
+function describeClaudeIncompatibleFields(serverName, entry) {
+    if (isStdioEntry(entry))
+        return [];
+    const fields = [];
+    if (entry.env_http_headers !== undefined)
+        fields.push('env_http_headers');
+    if (entry.bearer_token_env_var !== undefined)
+        fields.push('bearer_token_env_var');
+    if (entry.headers !== undefined && entry.http_headers !== undefined) {
+        fields.push('headers and http_headers');
+    }
+    return fields.map((field) => `${serverName}: ${field}`);
+}
+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 assertClaudeLiveMcpSafetyPreflight(options) {
+    if (!options.mcpConfigPath || !isLiveMcpSafetyMode(options.mcpSafety))
+        return;
+    const mcpServers = await readStagedMcpServers(options.workspacePath, options.mcpConfigPath);
+    if (!mcpServers)
+        return;
+    if (options.mcpSafety?.liveOptIn !== true) {
+        throw new Error('Claude live MCP safety requires mcpSafety.liveOptIn: true before MCP runtime mounting.');
+    }
+    const unsupported = Object.entries(mcpServers).flatMap(([serverName, entry]) => describeClaudeIncompatibleFields(serverName, entry));
+    if (unsupported.length > 0) {
+        throw new Error(`Claude live MCP safety does not support runtime-incompatible MCP config fields: ${unsupported.join('; ')}`);
+    }
+}
+export async function assertUnsupportedLiveMcpSafetyRuntime(options) {
+    if (!options.mcpConfigPath || !isLiveMcpSafetyMode(options.mcpSafety))
+        return;
+    const mcpServers = await readStagedMcpServers(options.workspacePath, options.mcpConfigPath);
+    if (!mcpServers)
+        return;
+    throw new Error(`${options.runtimeName} live MCP safety enforcement is not supported. Use mock mode or a runtime that enforces mcpSafety before live MCP mounting.`);
+}
+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/sandbox.js

@@ -29,7 +29,8 @@ export async function createSandbox(spec) {
         const skillName = path.basename(skillPath);
         const skillFilter = (src) => {
             const rel = path.relative(skillPath, src);
-            if (rel === 'test' || rel.startsWith(`test${path.sep}`)) {
+            const [topLevelDir] = rel.split(path.sep);
+            if (topLevelDir === 'test' || topLevelDir === 'tests') {
                 return false;
             }
             return copyFilter(src);

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,7 +18,7 @@ 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, 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';
@@ -24,6 +26,9 @@ 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;