@wix/pathgrade 0.32.0 → 0.34.0

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' | 'unrecognized_mcp_tool_name';
+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);
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/pathgrade",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Evaluate whether AI agents discover and use your skills correctly",
   "main": "./dist/sdk/index.js",
   "types": "./dist/sdk/index.d.ts",
@@ -89,6 +89,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.85",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "@types/node": "^25.3.1",
     "fs-extra": "^11.3.3",
     "jiti": "^2.6.1",
@@ -96,5 +97,5 @@
     "typescript": "^5.9.3",
     "zod": "4.3.6"
   },
-  "falconPackageHash": "2eac6cd3615471de5203991805252e0bd5555626a7e922a3ac009150"
+  "falconPackageHash": "77ac8633dc5bff7dea81e34b2bad4228699443f0788ce2eb56a2bc36"
 }