@wix/pathgrade 1.0.13 → 1.0.15

package/dist/agents/codex-app-server/mcp-approval-correlator.js

@@ -0,0 +1,299 @@
+import { redactMcpSecrets, } from '../../sdk/mcp-safety.js';
+import { canonicalizeJson } from '../../core/canonical-json.js';
+import { buildScriptedMcpApprovalEvent, buildScriptedMcpDeniedCallEvent, } from '../../sdk/scripted-mcp-events.js';
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+export function isMcpToolCallApprovalRequest(params) {
+    const meta = isRecord(params) && isRecord(params._meta) ? params._meta : {};
+    return meta.codex_approval_kind === 'mcp_tool_call';
+}
+export function hasScriptedApprovalPolicy(response) {
+    const policy = isRecord(response.approvalPolicy) ? response.approvalPolicy : {};
+    const granular = isRecord(policy.granular) ? policy.granular : {};
+    return response.approvalsReviewer === 'user'
+        && granular.sandbox_approval === false && granular.rules === false
+        && granular.skill_approval === false && granular.request_permissions === false
+        && granular.mcp_elicitations === true
+        && Object.keys(granular).length === 5 && Object.keys(policy).length === 1;
+}
+export function extractMcpToolApprovalRequest(params) {
+    if (!isMcpToolCallApprovalRequest(params) || !isRecord(params))
+        return undefined;
+    const meta = isRecord(params._meta) ? params._meta : {};
+    const serverName = typeof params.serverName === 'string' ? params.serverName : undefined;
+    const messageTool = typeof params.message === 'string' ? params.message.match(/tool\s+"([^"]+)"/i)?.[1] : undefined;
+    const toolName = typeof meta.toolName === 'string' ? meta.toolName
+        : typeof meta.tool_name === 'string' ? meta.tool_name
+            : typeof meta.name === 'string' ? meta.name : messageTool;
+    if (!serverName || !toolName)
+        return undefined;
+    return { serverName, toolName, arguments: isRecord(meta.tool_params) ? meta.tool_params : {} };
+}
+export function recordPolicyDeniedMcpToolCall(turn, request, decision, rawParams) {
+    if (!turn)
+        return;
+    const args = redactMcpSecrets(request.arguments);
+    const providerToolName = `${request.serverName}.${request.toolName}`;
+    turn.nonAskToolEvents.push({
+        action: 'mcp_tool_call', provider: 'codex', providerToolName, turnNumber: turn.turnNumber,
+        arguments: { ...args, server: request.serverName, tool: request.toolName, status: 'policy_denied',
+            policyResult: { action: 'deny', reason: decision.reason, message: decision.message } },
+        summary: `MCP tool ${providerToolName} policy_denied`, confidence: 'high',
+        rawSnippet: JSON.stringify(redactMcpSecrets(rawParams)),
+    });
+}
+export class CodexMcpApprovalCorrelator {
+    host;
+    getTurnNumber;
+    getThreadId;
+    getRemainingMs;
+    live = new Map();
+    terminal = new Map();
+    decisions = new Map();
+    active = false;
+    authoritativeTurn;
+    authorityPromise = Promise.resolve(false);
+    resolveAuthority;
+    waitingRequests = 0;
+    poisoned = false;
+    constructor(host, getTurnNumber, getThreadId, getRemainingMs = () => 1_000) {
+        this.host = host;
+        this.getTurnNumber = getTurnNumber;
+        this.getThreadId = getThreadId;
+        this.getRemainingMs = getRemainingMs;
+    }
+    started(params) {
+        if (this.poisoned)
+            return;
+        if (!isRecord(params) || !isRecord(params.item) || params.item.type !== 'mcpToolCall')
+            return;
+        const record = this.parseLifecycleRecord(params);
+        if (!record)
+            return this.failLifecycle('malformed MCP lifecycle start');
+        if (!this.validateLifecycleTurn(record))
+            return this.failLifecycle('MCP lifecycle start belongs to a stale thread or turn');
+        if (this.terminal.has(record.item.id)) {
+            return this.failLifecycle(`MCP lifecycle start after completion ${record.item.id}`);
+        }
+        const prior = this.live.get(record.item.id);
+        if (prior && canonicalizeJson(prior) !== canonicalizeJson(record)) {
+            return this.failLifecycle(`conflicting MCP lifecycle start ${record.item.id}`);
+        }
+        this.live.set(record.item.id, record);
+    }
+    completed(params) {
+        if (this.poisoned)
+            return false;
+        if (!isRecord(params) || !isRecord(params.item) || params.item.type !== 'mcpToolCall')
+            return true;
+        const record = this.parseLifecycleRecord(params);
+        if (!record)
+            return this.failLifecycle('malformed MCP lifecycle completion');
+        if (!this.validateLifecycleTurn(record))
+            return this.failLifecycle('MCP lifecycle completion belongs to a stale thread or turn');
+        const fingerprint = canonicalizeJson(record);
+        const priorTerminal = this.terminal.get(record.item.id);
+        if (priorTerminal !== undefined) {
+            if (priorTerminal.fingerprint !== fingerprint) {
+                return this.failLifecycle(`conflicting MCP lifecycle completion ${record.item.id}`);
+            }
+            return false;
+        }
+        const started = this.live.get(record.item.id);
+        if (!started)
+            return this.failLifecycle(`MCP lifecycle completion before start ${record.item.id}`);
+        if (started.threadId !== record.threadId || started.turnId !== record.turnId
+            || started.item.server !== record.item.server || started.item.tool !== record.item.tool
+            || canonicalizeJson(started.item.arguments ?? {}) !== canonicalizeJson(record.item.arguments ?? {})) {
+            return this.failLifecycle(`conflicting MCP lifecycle completion ${record.item.id}`);
+        }
+        this.live.delete(record.item.id);
+        this.terminal.set(record.item.id, {
+            fingerprint, threadId: record.threadId, turnId: record.turnId,
+        });
+        return true;
+    }
+    async decide(requestId, rawParams) {
+        if (!this.active) {
+            this.host.failProtocol('MCP approval request received outside an active turn');
+            return { action: 'decline', events: [this.protocolEvent('outside_active_turn')] };
+        }
+        if (this.poisoned) {
+            return { action: 'decline', events: [this.protocolEvent('protocol_poisoned')] };
+        }
+        if (!this.authoritativeTurn) {
+            if (this.waitingRequests >= 64) {
+                this.poison('MCP approval pre-response quarantine overflow');
+                return { action: 'decline', events: [this.protocolEvent('quarantine_overflow')] };
+            }
+            this.waitingRequests += 1;
+            let ready;
+            try {
+                ready = await this.waitForAuthority();
+            }
+            finally {
+                this.waitingRequests -= 1;
+            }
+            if (!ready || !this.active || !this.authoritativeTurn || this.poisoned) {
+                this.poison('MCP approval pre-response quarantine expired');
+                return { action: 'decline', events: [this.protocolEvent('quarantine_expired')] };
+            }
+        }
+        const params = isRecord(rawParams) ? rawParams : {};
+        const key = `${typeof requestId}:${String(requestId)}`;
+        const meta = isRecord(params._meta) ? params._meta : {};
+        const threadId = this.getThreadId();
+        let fingerprint;
+        try {
+            fingerprint = canonicalizeJson({
+                mode: params.mode,
+                threadId: params.threadId,
+                turnId: params.turnId,
+                serverName: params.serverName,
+                kind: meta.codex_approval_kind,
+                tool_params: meta.tool_params,
+            });
+        }
+        catch {
+            this.poison('malformed MCP approval authority fields');
+            return { action: 'decline', events: [this.protocolEvent('malformed_request')] };
+        }
+        const existing = this.decisions.get(key);
+        if (existing) {
+            if (existing.fingerprint === fingerprint)
+                return { action: existing.action, events: [] };
+            this.poison('conflicting duplicate MCP approval request');
+            return { action: 'decline', events: [this.protocolEvent('conflicting_duplicate')] };
+        }
+        if (params.mode !== 'form' || meta.codex_approval_kind !== 'mcp_tool_call'
+            || typeof params.serverName !== 'string' || !isRecord(meta.tool_params)
+            || (threadId && params.threadId !== threadId)
+            || (this.authoritativeTurn && (params.threadId !== this.authoritativeTurn.threadId
+                || params.turnId !== this.authoritativeTurn.turnId))) {
+            this.poison('malformed or stale MCP approval request');
+            const response = { action: 'decline', events: [this.protocolEvent('malformed_request')], fingerprint };
+            this.decisions.set(key, response);
+            return response;
+        }
+        const argsFingerprint = canonicalizeJson(meta.tool_params);
+        const candidates = [...this.live.values()].filter((record) => record.item.server === params.serverName
+            && canonicalizeJson(record.item.arguments ?? {}) === argsFingerprint);
+        if (candidates.length !== 1) {
+            this.poison('MCP approval request did not correlate to exactly one lifecycle item');
+            const response = { action: 'decline', events: [this.protocolEvent('ambiguous_lifecycle')], fingerprint };
+            this.decisions.set(key, response);
+            return response;
+        }
+        const item = candidates[0].item;
+        const decision = this.host.decide(item.server, item.tool, meta.tool_params);
+        if (decision.outcome !== 'matched')
+            this.poisoned = true;
+        const approval = buildScriptedMcpApprovalEvent({
+            provider: 'codex', serverName: item.server, toolName: item.tool,
+            toolUseId: item.id, turnNumber: this.getTurnNumber(), decision,
+        });
+        const events = [approval];
+        if (decision.decision === 'deny') {
+            const outcome = decision.outcome === 'matched' ? 'user_denied' : 'protocol_error';
+            events.push(buildScriptedMcpDeniedCallEvent({
+                provider: 'codex', serverName: item.server, toolName: item.tool,
+                toolUseId: item.id, turnNumber: this.getTurnNumber(), args: meta.tool_params, outcome,
+            }));
+        }
+        const response = { action: decision.decision === 'approve' ? 'accept' : 'decline', events, fingerprint };
+        this.decisions.set(key, response);
+        return response;
+    }
+    beginTurn() {
+        this.active = true;
+        this.poisoned = false;
+        this.authoritativeTurn = undefined;
+        this.waitingRequests = 0;
+        this.authorityPromise = new Promise((resolve) => { this.resolveAuthority = resolve; });
+        this.live.clear();
+        this.terminal.clear();
+        this.decisions.clear();
+    }
+    setAuthoritativeTurn(threadId, turnId) {
+        if (!this.active || this.poisoned)
+            return false;
+        this.authoritativeTurn = { threadId, turnId };
+        const staleLifecycle = [...this.live.values(), ...this.terminal.values()]
+            .some((record) => record.threadId !== threadId || record.turnId !== turnId);
+        if (staleLifecycle) {
+            this.authoritativeTurn = undefined;
+            this.poison('MCP lifecycle item belongs to a stale thread or turn');
+            return false;
+        }
+        this.resolveAuthority?.(true);
+        this.resolveAuthority = undefined;
+        return true;
+    }
+    endTurn() {
+        this.active = false;
+        this.resolveAuthority?.(false);
+        this.resolveAuthority = undefined;
+        this.authoritativeTurn = undefined;
+        this.live.clear();
+        this.terminal.clear();
+        this.decisions.clear();
+    }
+    protocolEvent(reason) {
+        return {
+            action: 'mcp_approval', provider: 'codex', providerToolName: 'mcp.protocol_error',
+            turnNumber: this.getTurnNumber(), status: 'error',
+            arguments: { decision: 'deny', outcome: 'protocol_error', reason, decisionSource: 'scripted_user' },
+            summary: 'MCP approval protocol error', confidence: 'high',
+            rawSnippet: JSON.stringify({ outcome: 'protocol_error', reason }),
+        };
+    }
+    waitForAuthority() {
+        const remainingMs = this.getRemainingMs();
+        const timeoutMs = Number.isFinite(remainingMs)
+            ? Math.max(0, Math.min(1_000, remainingMs))
+            : 1_000;
+        if (timeoutMs === 0)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), timeoutMs);
+            this.authorityPromise.then((ready) => {
+                clearTimeout(timer);
+                resolve(ready);
+            });
+        });
+    }
+    parseLifecycleRecord(params) {
+        if (typeof params.threadId !== 'string' || typeof params.turnId !== 'string' || !isRecord(params.item)) {
+            return undefined;
+        }
+        const item = params.item;
+        if (item.type !== 'mcpToolCall' || typeof item.id !== 'string' || !item.id
+            || typeof item.server !== 'string' || !item.server || typeof item.tool !== 'string' || !item.tool
+            || !isRecord(item.arguments ?? {}))
+            return undefined;
+        try {
+            canonicalizeJson(item.arguments ?? {});
+        }
+        catch {
+            return undefined;
+        }
+        return { threadId: params.threadId, turnId: params.turnId, item: item };
+    }
+    validateLifecycleTurn(record) {
+        return this.authoritativeTurn === undefined
+            || (record.threadId === this.authoritativeTurn.threadId && record.turnId === this.authoritativeTurn.turnId);
+    }
+    failLifecycle(message) {
+        this.poison(message);
+        throw new Error(message);
+    }
+    poison(message) {
+        if (this.poisoned)
+            return;
+        this.poisoned = true;
+        this.host.failProtocol(message);
+        this.resolveAuthority?.(false);
+        this.resolveAuthority = undefined;
+    }
+}

package/dist/core/canonical-json.d.ts

@@ -0,0 +1,2 @@
+/** Deterministic serialization for JSON authority inputs. Rejects non-JSON shapes. */
+export declare function canonicalizeJson(value: unknown, ancestors?: Set<object>): string;

package/dist/core/canonical-json.js

@@ -0,0 +1,51 @@
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Deterministic serialization for JSON authority inputs. Rejects non-JSON shapes. */
+export function canonicalizeJson(value, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError('MCP authority values must contain only finite JSON numbers');
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        if (ancestors.has(value))
+            throw new TypeError('MCP authority values must be acyclic JSON');
+        if (Object.keys(value).some((key) => !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length)) {
+            throw new TypeError('MCP authority values must not contain non-index array properties');
+        }
+        ancestors.add(value);
+        const serialized = Array.from({ length: value.length }, (_, index) => {
+            if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                throw new TypeError('MCP authority values must not contain sparse arrays');
+            }
+            return canonicalizeJson(value[index], ancestors);
+        });
+        ancestors.delete(value);
+        return `[${serialized.join(',')}]`;
+    }
+    if (!isPlainObject(value))
+        throw new TypeError('MCP authority values must contain only plain JSON values');
+    if (ancestors.has(value))
+        throw new TypeError('MCP authority values must be acyclic JSON');
+    ancestors.add(value);
+    const entries = Reflect.ownKeys(value).map((key) => {
+        if (typeof key !== 'string')
+            throw new TypeError('MCP authority values must not contain symbol keys');
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor.enumerable || !('value' in descriptor)) {
+            throw new TypeError('MCP authority values must contain only enumerable data properties');
+        }
+        return [key, descriptor.value];
+    });
+    const serialized = entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalizeJson(entry, ancestors)}`);
+    ancestors.delete(value);
+    return `{${serialized.join(',')}}`;
+}

package/dist/core/generated-mcp-protocol.d.ts

@@ -0,0 +1,19 @@
+export declare const MCP_ANNOTATION_PROTOCOL_FLOOR = "2025-03-26";
+export declare const MCP_LATEST_ANNOTATION_PROTOCOL = "2025-11-25";
+export interface GeneratedMcpInitializeResult {
+    protocolVersion: string;
+    capabilities: {
+        tools: Record<string, never>;
+    };
+    serverInfo: {
+        name: string;
+        version: '1.0.0';
+    };
+    instructions?: string;
+}
+export declare function negotiateGeneratedMcpProtocol(requestedVersion: unknown): string;
+export declare function buildGeneratedMcpInitializeResult(opts: {
+    requestedVersion: unknown;
+    serverName: string;
+    instructions?: string;
+}): GeneratedMcpInitializeResult;

package/dist/core/generated-mcp-protocol.js

@@ -0,0 +1,26 @@
+export const MCP_ANNOTATION_PROTOCOL_FLOOR = '2025-03-26';
+export const MCP_LATEST_ANNOTATION_PROTOCOL = '2025-11-25';
+const SUPPORTED_ANNOTATION_PROTOCOLS = new Set([
+    MCP_ANNOTATION_PROTOCOL_FLOOR,
+    '2025-06-18',
+    MCP_LATEST_ANNOTATION_PROTOCOL,
+]);
+export function negotiateGeneratedMcpProtocol(requestedVersion) {
+    if (typeof requestedVersion !== 'string') {
+        throw new Error('MCP initialize requires a string protocolVersion');
+    }
+    if (requestedVersion < MCP_ANNOTATION_PROTOCOL_FLOOR) {
+        throw new Error(`MCP protocol ${requestedVersion} predates Tool Annotations`);
+    }
+    return SUPPORTED_ANNOTATION_PROTOCOLS.has(requestedVersion)
+        ? requestedVersion
+        : MCP_LATEST_ANNOTATION_PROTOCOL;
+}
+export function buildGeneratedMcpInitializeResult(opts) {
+    return {
+        protocolVersion: negotiateGeneratedMcpProtocol(opts.requestedVersion),
+        capabilities: { tools: {} },
+        serverInfo: { name: opts.serverName, version: '1.0.0' },
+        ...(opts.instructions !== undefined ? { instructions: opts.instructions } : {}),
+    };
+}

package/dist/core/mcp-mock.d.ts

@@ -1,3 +1,3 @@
 import { MockMcpServerConfig, MockMcpServerDescriptor } from './mcp-mock.types.js';
-export type { MockMcpTool, MockMcpServerConfig, MockMcpServerDescriptor } from './mcp-mock.types.js';
+export type { MockMcpTool, MockMcpToolAnnotations, MockMcpServerConfig, MockMcpServerDescriptor, } from './mcp-mock.types.js';
 export declare function mockMcpServer(config: MockMcpServerConfig): MockMcpServerDescriptor;

package/dist/core/mcp-mock.js

@@ -5,6 +5,15 @@ export function mockMcpServer(config) {
     if (!Array.isArray(config.tools) || config.tools.length === 0) {
         throw new Error('mockMcpServer: must have at least one tool');
     }
+    if (config.instructions !== undefined) {
+        if (typeof config.instructions !== 'string' || config.instructions.length === 0) {
+            throw new Error('mockMcpServer: instructions must be a non-empty string');
+        }
+        if (Buffer.byteLength(config.instructions, 'utf8') > 32 * 1024) {
+            throw new Error('mockMcpServer: instructions must be at most 32 KiB of UTF-8');
+        }
+    }
+    const readOnlyHints = new Map();
     for (let i = 0; i < config.tools.length; i++) {
         const tool = config.tools[i];
         if (!tool.name || typeof tool.name !== 'string') {
@@ -18,6 +27,21 @@ export function mockMcpServer(config) {
                 throw new Error(`mockMcpServer: tools[${i}].when is not a valid regex: ${e.message}`);
             }
         }
+        if (tool.annotations !== undefined) {
+            if (tool.annotations === null || typeof tool.annotations !== 'object' || Array.isArray(tool.annotations)) {
+                throw new Error(`mockMcpServer: tools[${i}].annotations must be an object`);
+            }
+            const hint = tool.annotations.readOnlyHint;
+            if (hint !== undefined && typeof hint !== 'boolean') {
+                throw new Error(`mockMcpServer: tools[${i}].annotations.readOnlyHint must be a boolean`);
+            }
+            const previous = readOnlyHints.get(tool.name);
+            if (hint !== undefined && previous !== undefined && previous !== hint) {
+                throw new Error(`mockMcpServer: conflicting readOnlyHint values for tool "${tool.name}"`);
+            }
+            if (hint !== undefined)
+                readOnlyHints.set(tool.name, hint);
+        }
     }
     return { __type: 'mock_mcp_server', config };
 }

package/dist/core/mcp-mock.types.d.ts

@@ -1,12 +1,18 @@
+export interface MockMcpToolAnnotations {
+    readOnlyHint?: boolean;
+}
 export interface MockMcpTool {
     name: string;
     description?: string;
     inputSchema?: Record<string, unknown>;
+    annotations?: MockMcpToolAnnotations;
     when?: string;
     response: unknown;
 }
 export interface MockMcpServerConfig {
     name: string;
+    /** Trusted eval-author guidance exposed by MCP initialize. Never an authorization control. */
+    instructions?: string;
     tools: MockMcpTool[];
 }
 export interface MockMcpServerDescriptor {

package/dist/core/mcp-schema-profile.d.ts

@@ -0,0 +1,10 @@
+export declare function assertScriptedMcpSchemaProfile(schema: Record<string, unknown>, identity: {
+    serverName: string;
+    toolName: string;
+}): void;
+/**
+ * Anthropic's tool API rejects composition at the input-schema root. Convert
+ * the common object-allOf form to its equivalent merged object shape while
+ * retaining nested schemas (including nested composition) unchanged.
+ */
+export declare function compileScriptedMcpSchemaForProvider(schema: Record<string, unknown>): Record<string, unknown>;

package/dist/core/mcp-schema-profile.js

@@ -0,0 +1,91 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+const DIALECT = 'https://json-schema.org/draft/2020-12/schema';
+const REFERENCE_KEYWORDS = new Set(['$ref', '$defs', '$recursiveRef', '$dynamicRef']);
+function isRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function walkSchema(value, path) {
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => walkSchema(entry, `${path}/${index}`));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        const childPath = `${path}/${key}`;
+        if (REFERENCE_KEYWORDS.has(key)) {
+            throw new Error(`unsupported keyword ${key} at ${childPath}`);
+        }
+        if ((key === 'exclusiveMinimum' || key === 'exclusiveMaximum') && typeof entry === 'boolean') {
+            throw new Error(`legacy boolean ${key} at ${childPath}`);
+        }
+        if (key === 'nullable')
+            throw new Error(`OpenAPI-only keyword nullable at ${childPath}`);
+        walkSchema(entry, childPath);
+    }
+}
+export function assertScriptedMcpSchemaProfile(schema, identity) {
+    const prefix = `Scripted MCP schema for ${identity.serverName}.${identity.toolName}`;
+    if (schema.type !== 'object') {
+        throw new Error(`${prefix} must have object root type at /type`);
+    }
+    if (schema.$schema !== undefined && schema.$schema !== DIALECT) {
+        throw new Error(`${prefix} uses unsupported dialect at /$schema`);
+    }
+    try {
+        walkSchema(schema, '');
+        const ajv = new Ajv2020({ strict: true, allErrors: true });
+        ajv.compile(schema);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${prefix} is not portable: ${message.slice(0, 500)}`);
+    }
+}
+/**
+ * Anthropic's tool API rejects composition at the input-schema root. Convert
+ * the common object-allOf form to its equivalent merged object shape while
+ * retaining nested schemas (including nested composition) unchanged.
+ */
+export function compileScriptedMcpSchemaForProvider(schema) {
+    if (!Array.isArray(schema.allOf))
+        return schema;
+    const branches = schema.allOf;
+    if (!branches.every(isMergeableObjectBranch))
+        return schema;
+    const root = { ...schema };
+    delete root.allOf;
+    const properties = isRecord(root.properties) ? { ...root.properties } : {};
+    const required = new Set(Array.isArray(root.required) ? root.required.filter((entry) => typeof entry === 'string') : []);
+    for (const branch of branches) {
+        if (isRecord(branch.properties)) {
+            for (const [name, propertySchema] of Object.entries(branch.properties)) {
+                const existing = properties[name];
+                properties[name] = existing === undefined
+                    ? propertySchema
+                    : { allOf: [existing, propertySchema] };
+            }
+        }
+        if (Array.isArray(branch.required)) {
+            for (const name of branch.required)
+                if (typeof name === 'string')
+                    required.add(name);
+        }
+    }
+    if (Object.keys(properties).length > 0)
+        root.properties = properties;
+    if (required.size > 0)
+        root.required = [...required];
+    return root;
+}
+function isMergeableObjectBranch(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.keys(value).every((key) => key === 'type' || key === 'properties' || key === 'required')
+        && (value.type === undefined || value.type === 'object')
+        && (value.properties === undefined || isRecord(value.properties))
+        && (value.required === undefined || Array.isArray(value.required));
+}

package/dist/mcp-mock-server.js

@@ -1,21 +1,32 @@
 import * as fs from 'fs';
 import * as readline from 'readline';
+import { buildGeneratedMcpInitializeResult } from './core/generated-mcp-protocol.js';
 function loadFixture(fixturePath) {
     const content = fs.readFileSync(fixturePath, 'utf-8');
     return JSON.parse(content);
 }
 function buildToolSchemas(fixture) {
-    const seen = new Set();
     const schemas = [];
+    const schemasByName = new Map();
     for (const tool of fixture.tools) {
-        if (seen.has(tool.name))
+        let schema = schemasByName.get(tool.name);
+        if (!schema) {
+            schema = {
+                name: tool.name,
+                description: tool.description || `Mock tool: ${tool.name}`,
+                inputSchema: tool.inputSchema || { type: 'object' },
+            };
+            schemasByName.set(tool.name, schema);
+            schemas.push(schema);
+        }
+        const hint = tool.annotations?.readOnlyHint;
+        if (hint === undefined)
             continue;
-        seen.add(tool.name);
-        schemas.push({
-            name: tool.name,
-            description: tool.description || `Mock tool: ${tool.name}`,
-            inputSchema: tool.inputSchema || { type: 'object' },
-        });
+        const previous = schema.annotations?.readOnlyHint;
+        if (previous !== undefined && previous !== hint) {
+            throw new Error(`Conflicting readOnlyHint values for tool "${tool.name}"`);
+        }
+        schema.annotations = { readOnlyHint: hint };
     }
     return schemas;
 }
@@ -80,11 +91,16 @@ function main() {
             return;
         switch (msg.method) {
             case 'initialize':
-                sendResponse(msg.id, {
-                    protocolVersion: '2024-11-05',
-                    capabilities: { tools: {} },
-                    serverInfo: { name: fixture.name, version: '1.0.0' },
-                });
+                try {
+                    sendResponse(msg.id, buildGeneratedMcpInitializeResult({
+                        requestedVersion: msg.params?.protocolVersion,
+                        serverName: fixture.name,
+                        instructions: fixture.instructions,
+                    }));
+                }
+                catch (error) {
+                    sendError(msg.id, -32602, error.message);
+                }
                 break;
             case 'tools/list':
                 sendResponse(msg.id, { tools: toolSchemas });

package/dist/providers/mcp-config.js

@@ -109,8 +109,10 @@ async function resolveMockServerScript(workspacePath) {
         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, {
+    const protocolSource = path.resolve(import.meta.dirname, '../core/generated-mcp-protocol.ts');
+    const protocol = (await fs.readFile(protocolSource, 'utf-8')).replaceAll('export ', '');
+    const source = (await fs.readFile(sourceScript, 'utf-8')).replace(/import \{ buildGeneratedMcpInitializeResult \} from '.\/core\/generated-mcp-protocol\.js';\n/, '');
+    const transpiled = ts.transpileModule(`${protocol}\n${source}`, {
         compilerOptions: {
             target: ts.ScriptTarget.ES2022,
             module: ts.ModuleKind.CommonJS,

package/dist/providers/sandbox.js

@@ -6,6 +6,9 @@ import { createSandboxRoot } from './sandbox-lifecycle.js';
 export const SAFE_HOST_VARS = [
     'PATH', 'SHELL', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM', 'USER', 'LOGNAME',
 ];
+function copiesEntireCodexHome(relPath) {
+    return path.posix.normalize(relPath.replace(/\\/g, '/')).replace(/\/+$/, '') === '.codex';
+}
 export async function createSandbox(spec) {
     const rootDir = await createSandboxRoot();
     const workspacePath = path.join(rootDir, 'workspace');
@@ -51,6 +54,9 @@ export async function createSandbox(spec) {
     }
     // Copy specified paths from real host HOME into sandbox HOME
     if (spec.copyFromHome) {
+        if (spec.copyFromHome.some(copiesEntireCodexHome)) {
+            console.warn('pathgrade: copyFromHome requests a copy of the entire ~/.codex directory, including config, MCP definitions, plugins, caches, sessions, and other potentially large or sensitive state. Pathgrade stages ~/.codex/auth.json automatically when cached Codex auth is needed; keep the full copy only when reproducing the host Codex environment intentionally.');
+        }
         const realHome = os.homedir();
         for (const relPath of spec.copyFromHome) {
             const srcPath = path.join(realHome, relPath);