@wix/pathgrade 1.0.14 → 1.0.15

package/README.md

@@ -334,6 +334,7 @@ const mock = mockMcpServer({
     tools: [{
         name: 'get_weather',
         description: 'Get weather for a city',
+        annotations: { readOnlyHint: true },
         when: 'weather',
         response: { temp: 72, unit: 'F' },
     }],
@@ -342,6 +343,33 @@ const mock = mockMcpServer({
 const agent = await createAgent({ agent: 'claude', mcpMock: mock });
 ```
 
+Read-only metadata is explicit: add `annotations.readOnlyHint: true` only when
+the operation being modeled is read-only. Unannotated and explicitly mutating
+mock tools retain the runtime's normal approval behavior.
+
+To evaluate mutation approval behavior with Claude or Codex app-server, pass a
+non-empty ordered `mcpMockApprovalRules` array. The first matching rule wins:
+
+```ts
+const agent = await createAgent({
+  agent: 'codex',
+  transport: 'app-server',
+  mcpMock: mock,
+  mcpMockApprovalRules: [
+    { serverName: 'sessions', toolName: 'remove_session',
+      argumentsContaining: { mode: 'delete' }, decision: 'deny' },
+    { serverName: 'sessions', toolName: 'remove_session',
+      argumentsContaining: { mode: 'archive' }, decision: 'approve' },
+  ],
+});
+```
+
+Use `getMcpApproval()` for the simulated-user decision and
+`wasMcpToolInvoked()` for receipt-backed execution (`true`, `false`, or
+`undefined`). An `mcp_tool_call` event by itself proves only that an attempt was
+observed. Mock responses are fixed fixtures; this mode does not model stateful
+mutation or make later reads observe earlier writes.
+
 ## CLI
 
 ```bash

package/dist/adapters/jest/results.js

@@ -58,7 +58,7 @@ function runCase(input) {
     const evaluations = input.evaluations.map((entry, index) => ({
         id: `${attemptId}:evaluation-${index + 1}`,
         attemptId,
-        score: entry.score,
+        ...(entry.score !== undefined ? { score: entry.score } : {}),
         ...(entry.trial ? { trial: entry.trial } : {}),
         ...(entry.diagnostics ? { diagnostics: entry.diagnostics } : {}),
         ...(entry.resultKind ? { resultKind: entry.resultKind } : {}),

package/dist/adapters/node-test/index.js

@@ -67,7 +67,7 @@ function toReportEvaluations(evaluations) {
     if (evaluations.length === 0)
         return undefined;
     return evaluations.map(entry => ({
-        score: entry.score,
+        ...(entry.score !== undefined ? { score: entry.score } : {}),
         trial: entry.trial,
         diagnostics: entry.diagnostics,
         resultKind: entry.resultKind,

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

@@ -22,6 +22,7 @@ const SDK_ERROR_SUBTYPES = [
     'error_max_structured_output_retries',
 ];
 import { TOOL_NAME_MAP, buildSummary, enrichSkillEvents } from '../../tool-events.js';
+import { attachOriginalMcpInput } from '../../sdk/mcp-event-input.js';
 import { parseClaudeSdkMcpToolName } from './mcp-tool-name.js';
 import { applyObservedToolResult, extractObservedToolResults, } from './tool-results.js';
 export function projectSdkMessages(input) {
@@ -202,7 +203,7 @@ function buildToolEvent(block, turnNumber, answerStore, mcpServerNames, deniedMc
             tool: mcpTool.tool,
             status: 'incomplete',
         };
-        return {
+        return attachOriginalMcpInput({
             action: 'mcp_tool_call',
             provider: 'claude',
             providerToolName: normalizedProviderToolName,
@@ -214,7 +215,7 @@ function buildToolEvent(block, turnNumber, answerStore, mcpServerNames, deniedMc
             summary: `MCP tool ${normalizedProviderToolName}`,
             confidence: 'high',
             rawSnippet: JSON.stringify(block).slice(0, 200),
-        };
+        }, rawInput ?? {});
     }
     const action = TOOL_NAME_MAP[providerToolName] ?? 'unknown';
     const args = action === 'ask_user'

package/dist/agents/claude/tool-permission-bridge.d.ts

@@ -3,6 +3,8 @@ import type { AskBus } from '../../sdk/ask-bus/types.js';
 import { type McpSafetyOptions } from '../../sdk/mcp-safety.js';
 import type { AskUserAnswerStore } from './ask-user-answer-store.js';
 import type { ClaudeDeniedMcpEventStore } from './denied-mcp-event-store.js';
+import type { ScriptedMcpMockHost } from '../../providers/scripted-mcp-mock-host.js';
+import type { ToolEvent } from '../../tool-events.js';
 export interface ClaudeToolPermissionBridgeDeps {
     askBus: AskBus;
     getTurnNumber: () => number;
@@ -10,6 +12,8 @@ export interface ClaudeToolPermissionBridgeDeps {
     mcpServerNames: readonly string[];
     mcpSafety?: McpSafetyOptions;
     deniedMcpEvents?: ClaudeDeniedMcpEventStore;
+    scriptedMcpHost?: ScriptedMcpMockHost;
+    recordScriptedEvent?: (event: ToolEvent) => void;
 }
 export type ClaudeToolPermissionBridge = CanUseTool & {
     lastError(): Error | null;

package/dist/agents/claude/tool-permission-bridge.js

@@ -1,12 +1,15 @@
 import { decideMcpToolCall, redactMcpSecrets, } from '../../sdk/mcp-safety.js';
 import { createAskUserBridge, } from './ask-user-bridge.js';
 import { parseClaudeSdkMcpToolName } from './mcp-tool-name.js';
+import { canonicalizeJson } from '../../core/canonical-json.js';
+import { buildScriptedMcpApprovalEvent, buildScriptedMcpDeniedCallEvent, } from '../../sdk/scripted-mcp-events.js';
 export function createClaudeToolPermissionBridge(deps) {
     const askUserBridge = createAskUserBridge({
         askBus: deps.askBus,
         getTurnNumber: deps.getTurnNumber,
         answerStore: deps.answerStore,
     });
+    const scriptedMemo = new Map();
     const canUseTool = async (toolName, input, options) => {
         if (toolName === 'AskUserQuestion') {
             return askUserBridge(toolName, input, options);
@@ -16,6 +19,56 @@ export function createClaudeToolPermissionBridge(deps) {
         if (parsed.kind === 'non_mcp') {
             return allow(input);
         }
+        if (runMode === 'mock' && deps.scriptedMcpHost && parsed.kind === 'mcp') {
+            const args = asRecord(input);
+            const host = deps.scriptedMcpHost;
+            if (host.isReadOnly(parsed.server, parsed.tool))
+                return allow(input);
+            const memoKey = `${deps.getTurnNumber()}\0${options.toolUseID}`;
+            let fingerprint;
+            try {
+                fingerprint = canonicalizeJson({ toolName, input: args });
+            }
+            catch {
+                host.failProtocol('invalid Claude MCP approval authority fields');
+                recordClaudeProtocolFailure(deps, options.toolUseID, parsed.server, parsed.tool, args, 'malformed_request');
+                return { behavior: 'deny', message: 'The MCP approval request failed validation.' };
+            }
+            const prior = scriptedMemo.get(memoKey);
+            if (prior) {
+                if (prior.fingerprint === fingerprint)
+                    return prior.result;
+                host.failProtocol('conflicting duplicate Claude MCP approval callback');
+                recordClaudeProtocolFailure(deps, options.toolUseID, parsed.server, parsed.tool, args);
+                return { behavior: 'deny', message: 'The MCP approval request failed validation.' };
+            }
+            const result = Promise.resolve().then(() => {
+                const decision = host.decide(parsed.server, parsed.tool, args);
+                deps.recordScriptedEvent?.(buildScriptedMcpApprovalEvent({
+                    provider: 'claude', toolUseId: options.toolUseID, turnNumber: deps.getTurnNumber(),
+                    serverName: parsed.server, toolName: parsed.tool, decision,
+                }));
+                if (decision.decision === 'approve')
+                    return allow(input);
+                const outcome = decision.outcome === 'matched' ? 'user_denied' : 'protocol_error';
+                deps.deniedMcpEvents?.record(options.toolUseID, buildScriptedMcpDeniedCallEvent({
+                    provider: 'claude', toolUseId: options.toolUseID, turnNumber: deps.getTurnNumber(),
+                    serverName: parsed.server, toolName: parsed.tool, args, outcome,
+                }));
+                return { behavior: 'deny', message: decision.outcome === 'matched'
+                        ? 'The user denied this MCP tool call.'
+                        : 'The MCP approval request failed validation.' };
+            });
+            scriptedMemo.set(memoKey, { fingerprint, result });
+            return result;
+        }
+        if (runMode === 'mock' && deps.scriptedMcpHost && parsed.kind === 'unrecognized') {
+            deps.scriptedMcpHost.failProtocol(`unrecognized Claude SDK MCP tool name: ${toolName}`);
+            return {
+                behavior: 'deny',
+                message: `unrecognized Claude SDK MCP tool name: ${toolName}`,
+            };
+        }
         if (runMode === 'mock') {
             return allow(input);
         }
@@ -44,9 +97,23 @@ export function createClaudeToolPermissionBridge(deps) {
     };
     const bridge = canUseTool;
     bridge.lastError = () => askUserBridge.lastError();
-    bridge.clearLastError = () => askUserBridge.clearLastError();
+    bridge.clearLastError = () => {
+        askUserBridge.clearLastError();
+        scriptedMemo.clear();
+    };
     return bridge;
 }
+function recordClaudeProtocolFailure(deps, toolUseId, serverName, toolName, args, reason = 'conflicting_duplicate') {
+    deps.recordScriptedEvent?.(buildScriptedMcpApprovalEvent({
+        provider: 'claude', toolUseId, turnNumber: deps.getTurnNumber(), serverName, toolName,
+        decision: { decision: 'deny', outcome: 'protocol_error', reason },
+        status: 'error',
+    }));
+    deps.deniedMcpEvents?.record(toolUseId, buildScriptedMcpDeniedCallEvent({
+        provider: 'claude', toolUseId, turnNumber: deps.getTurnNumber(),
+        serverName, toolName, args, outcome: 'protocol_error',
+    }));
+}
 function allow(input) {
     return { behavior: 'allow', updatedInput: asRecord(input) };
 }

package/dist/agents/claude.d.ts

@@ -43,6 +43,8 @@ export interface ClaudeAgentDeps {
     now?: () => Date;
     /** Monotonic clock seam for deterministic tool duration tests. */
     monotonicNow?: () => number;
+    /** Grace period before force-closing an unresponsive SDK query. */
+    queryAbortGraceMs?: number;
 }
 export interface ClaudeAgentOptions {
     /**

package/dist/agents/claude.js

@@ -47,6 +47,19 @@ function createLinkedAbortController(signal) {
 function getTurnAbortSignal(sessionOptions) {
     return sessionOptions?.getAbortSignal?.() ?? sessionOptions?.abortSignal;
 }
+async function settlesWithin(promise, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise.then(() => true),
+            new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeoutMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 export class ClaudeAgent extends BaseAgent {
     deps;
     opts;
@@ -65,6 +78,7 @@ export class ClaudeAgent extends BaseAgent {
         const platform = this.deps.platform ?? process.platform;
         const hostEnv = this.deps.hostEnv ?? process.env;
         const envExecutable = this.deps.envExecutable ?? process.env.PATHGRADE_CLAUDE_CODE_EXECUTABLE;
+        const queryAbortGraceMs = Math.max(0, this.deps.queryAbortGraceMs ?? 250);
         const runtimeEnv = getRuntimeEnv(runtime);
         const sensitiveValues = collectSensitiveEnvValues(runtimeEnv);
         const sandboxedSpawn = createSandboxedClaudeSpawn({
@@ -86,7 +100,8 @@ export class ClaudeAgent extends BaseAgent {
             mcpSafety: sessionOptions?.mcpSafety,
         });
         await assertStdioMcpServersStartForClaudeSdk(mcpMountOptions);
-        const mcpServers = await mountMcpForClaudeSdk(mcpMountOptions);
+        const mcpServers = sessionOptions?.scriptedMcpHost?.claudeServers
+            ?? await mountMcpForClaudeSdk(mcpMountOptions);
         let priorSessionId;
         let turnNumber = 0;
         // The live ask-user bridge resolves AskUserQuestion through the bus
@@ -97,12 +112,19 @@ export class ClaudeAgent extends BaseAgent {
         // collisions.
         let answerStore = createAskUserAnswerStore();
         let deniedMcpEvents = createClaudeDeniedMcpEventStore();
+        let scriptedEvents = [];
+        let activeQuery;
+        let activeController;
+        let quiescence = Promise.resolve();
+        let resolveQuiescence;
         const bridge = createClaudeToolPermissionBridge({
             askBus,
             getTurnNumber: () => turnNumber,
             answerStore: { record: (id, e) => answerStore.record(id, e), get: (id) => answerStore.get(id) },
             mcpServerNames: mcpServers ? Object.keys(mcpServers) : [],
             mcpSafety: sessionOptions?.mcpSafety,
+            scriptedMcpHost: sessionOptions?.scriptedMcpHost,
+            recordScriptedEvent: (event) => scriptedEvents.push(event),
             deniedMcpEvents: {
                 record: (id, event) => deniedMcpEvents.record(id, event),
                 get: (id) => deniedMcpEvents.get(id),
@@ -114,9 +136,11 @@ export class ClaudeAgent extends BaseAgent {
             turnNumber += 1;
             answerStore = createAskUserAnswerStore();
             deniedMcpEvents = createClaudeDeniedMcpEventStore();
+            scriptedEvents = [];
             // Clear any ask-bus rejection captured on a prior turn so a
             // stale error never causes a spurious result on this turn.
             bridge.clearLastError();
+            activeController = createLinkedAbortController(getTurnAbortSignal(sessionOptions));
             const sdkOptions = buildClaudeSdkOptions({
                 workspacePath,
                 spawnClaudeCodeProcess: sandboxedSpawn,
@@ -126,21 +150,31 @@ export class ClaudeAgent extends BaseAgent {
                 claudeCodeExecutable,
                 resume: priorSessionId,
                 mcpServers,
-                abortController: createLinkedAbortController(getTurnAbortSignal(sessionOptions)),
+                abortController: activeController,
             });
             const messages = [];
             const messageTimings = [];
             const now = this.deps.now ?? (() => new Date());
             const monotonicNow = this.deps.monotonicNow ?? (() => performance.now());
             const stream = queryFn({ prompt: message, options: sdkOptions });
-            for await (const msg of stream) {
-                messages.push(msg);
-                messageTimings.push(hasToolLifecycleBoundary(msg)
-                    ? {
-                        receivedAt: now().toISOString(),
-                        receivedMonotonicMs: monotonicNow(),
-                    }
-                    : undefined);
+            activeQuery = stream;
+            quiescence = new Promise((resolve) => { resolveQuiescence = resolve; });
+            try {
+                for await (const msg of stream) {
+                    messages.push(msg);
+                    messageTimings.push(hasToolLifecycleBoundary(msg)
+                        ? {
+                            receivedAt: now().toISOString(),
+                            receivedMonotonicMs: monotonicNow(),
+                        }
+                        : undefined);
+                }
+            }
+            finally {
+                activeQuery = undefined;
+                activeController = undefined;
+                resolveQuiescence?.();
+                resolveQuiescence = undefined;
             }
             // The legacy NDJSON parser only synthesized the slash-command
             // `use_skill` event from the *opening* user message. The Claude
@@ -161,6 +195,7 @@ export class ClaudeAgent extends BaseAgent {
                 deniedMcpEvents,
                 sensitiveValues,
             });
+            projected.result.toolEvents = [...scriptedEvents, ...projected.result.toolEvents];
             // Capture the SDK-reported session id BEFORE checking for a bus
             // rejection so the next turn's `Options.resume` points at this
             // turn's session even when the turn ended in an ask-bus error.
@@ -191,6 +226,16 @@ export class ClaudeAgent extends BaseAgent {
         return {
             start: ({ message }) => runTurn(message),
             reply: ({ message }) => runTurn(message),
+            async dispose() {
+                const query = activeQuery;
+                activeController?.abort();
+                if (!query)
+                    return;
+                if (await settlesWithin(quiescence, queryAbortGraceMs))
+                    return;
+                query.close();
+                await settlesWithin(quiescence, queryAbortGraceMs);
+            },
         };
     }
 }