@wix/pathgrade 1.0.24 → 1.0.26

package/dist/internal/direct-mcp-v2/acp-direct-mcp.js

@@ -0,0 +1,326 @@
+/* oxlint-disable anti-slop/no-unknown-parameters -- Provider promise rejections are normalized at the ACP boundary. */
+import { randomBytes } from 'node:crypto';
+import { mkdir, mkdtemp, realpath, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { SAFE_HOST_VARS } from '../../providers/sandbox.js';
+import { spawnAcpClient } from './acp-client.js';
+import { IdempotentTrialCleaner, persistTrialArtifact, TrialExecutionError, TrialResourceRegistry, scanBearerSurfaces } from './cleanup.js';
+import { compileScenario } from './compiler.js';
+import { PrivateReplayVault, replayPrivateEvidence, verifyEvidenceChain } from './evidence.js';
+import { ScenarioHostReducer } from './host-reducer.js';
+import { materializeProjection } from './materialize.js';
+import { projectEndpoints } from './projection.js';
+import { admitRuntimeProfile } from './runtime-profile.js';
+import { createInvocationBarrier, startScenarioHttpHost } from './scenario-http-host.js';
+export function curateAcpProcessEnvironment(environment) {
+    const result = {};
+    for (const name of SAFE_HOST_VARS)
+        if (environment[name])
+            result[name] = environment[name];
+    return result;
+}
+export async function runAcpDirectMcpTrial(options) {
+    const compiled = compileScenario(options.scenario);
+    if (!compiled.ok)
+        throw new Error(`Scenario compilation failed: ${JSON.stringify(compiled.diagnostics)}`);
+    const cases = findContractCases(compiled.artifact);
+    const createdScratchParent = await mkdtemp(join(tmpdir(), `pathgrade-${options.provider}-direct-mcp-`));
+    let scratchParent;
+    try {
+        scratchParent = await realpath(createdScratchParent);
+    }
+    catch (error) {
+        await rm(createdScratchParent, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    const scratchPath = join(scratchParent, 'trial');
+    const workspacePath = join(scratchPath, 'workspace');
+    const homePath = join(scratchPath, 'home');
+    const dataPath = join(scratchPath, 'data');
+    const configPath = join(scratchPath, 'config');
+    const cachePath = join(scratchPath, 'cache');
+    const tempPath = join(scratchPath, 'tmp');
+    try {
+        await Promise.all([workspacePath, homePath, dataPath, configPath, cachePath, tempPath].map((path) => mkdir(path, { recursive: true })));
+        for (const link of options.localHomeLinks ?? []) {
+            const difference = relative(homePath, join(homePath, link.relativePath));
+            if (link.relativePath.length === 0 || isAbsolute(link.relativePath) || difference.startsWith('..'))
+                throw new Error(`unsafe local HOME link: ${link.relativePath}`);
+            const source = await realpath(link.hostPath);
+            const destination = join(homePath, link.relativePath);
+            await mkdir(dirname(destination), { recursive: true });
+            await symlink(source, destination, 'dir');
+        }
+    }
+    catch (error) {
+        await rm(scratchParent, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    const runtimeEnvironment = {
+        ...options.environment,
+        HOME: homePath,
+        TMPDIR: tempPath,
+        TMP: tempPath,
+        TEMP: tempPath,
+        XDG_DATA_HOME: dataPath,
+        XDG_CONFIG_HOME: configPath,
+        XDG_CACHE_HOME: cachePath,
+    };
+    delete runtimeEnvironment.OPENCODE_CONFIG_CONTENT;
+    const trialId = `${options.provider}-${randomBytes(12).toString('hex')}`;
+    const macKey = randomBytes(32);
+    const replayVault = new PrivateReplayVault(randomBytes(32));
+    const reducer = new ScenarioHostReducer(trialId, compiled.artifact, macKey, replayVault);
+    reducer.markCompiled();
+    const barrier = createInvocationBarrier(cases.effectfulCaseId);
+    const host = await startScenarioHttpHost({ artifact: compiled.artifact, reducer, barrier, secretRef: `${options.provider}-direct-mcp-trial-bearer` }).catch(async (error) => {
+        macKey.fill(0);
+        replayVault.dispose();
+        reducer.dispose();
+        await rm(scratchParent, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    });
+    const registry = new TrialResourceRegistry();
+    let hostOpen = true;
+    let client;
+    let hostQuiescent = false;
+    let persisted = false;
+    registry.register({ opaqueId: 'scenario-host', kind: 'listener', close: async () => { await host.dispose(); hostOpen = false; }, isOpen: () => hostOpen });
+    registry.register({ opaqueId: 'scenario-transports', kind: 'transport', close: () => host.dispose(), isOpen: () => host.activeTransportCount() !== 0 });
+    const cleaner = new IdempotentTrialCleaner({
+        registry,
+        scanRoots: [scratchPath],
+        scratchPath,
+        approvedScratchParent: scratchParent,
+        bearer: host.bearer.toString(),
+        persistRedacted: async (report, phase) => {
+            if (!options.artifactDirectory) {
+                if (phase === 'final')
+                    persisted = true;
+                return;
+            }
+            const path = join(options.artifactDirectory, 'trial-evidence.json');
+            await mkdir(dirname(path), { recursive: true });
+            const value = {
+                artifactDigest: compiled.artifact.artifactDigest,
+                scenarioArtifact: compiled.artifact,
+                evidence: reducer.ledger.events(),
+                replayVaultReference: {
+                    format: 'pathgrade-private-replay-vault-reference-v1',
+                    trialId,
+                    artifactDigest: compiled.artifact.artifactDigest,
+                },
+                admissionProfile: options.profile,
+                cleanup: { ...report, scans: report.scans.map((entry) => ({ ...entry, path: entry.path.replace(scratchParent, '<scratch>') })) },
+            };
+            await persistTrialArtifact(path, `${JSON.stringify(value)}\n`, phase);
+            if (phase === 'final')
+                persisted = true;
+        },
+        zeroBearer: () => { host.bearer.fill(0); macKey.fill(0); replayVault.dispose(); },
+    });
+    try {
+        const protectedValues = [host.bearer.toString(), `Bearer ${host.bearer.toString()}`];
+        const createClient = options.createClient ?? spawnAcpClient;
+        const admission = await admitRuntimeProfile(options.profile, {
+            provider: options.provider,
+            platform: process.platform,
+            architecture: process.arch,
+            environment: runtimeEnvironment,
+            forbiddenSecrets: protectedValues,
+            initializeControlPlane: async () => {
+                const initializedClient = createClient({
+                    provider: options.provider,
+                    command: options.profile.command.absolutePath,
+                    args: options.profile.command.args,
+                    cwd: workspacePath,
+                    environment: runtimeEnvironment,
+                    protectedValues,
+                });
+                client = initializedClient;
+                registry.register({ opaqueId: `${options.provider}-acp`, kind: 'process', close: () => initializedClient.close(), isOpen: () => initializedClient.isOpen() });
+                const normalizedHandshake = await initializedClient.initialize();
+                return { normalizedHandshake, capabilities: options.profile.requiredCapabilities, close: () => initializedClient.close() };
+            },
+        });
+        if (!admission.ok || !client)
+            throw new Error(`RUNTIME_NOT_ADMITTED: ${admission.ok ? 'ACP client unavailable' : admission.reason}`);
+        const admittedClient = client;
+        const projected = projectEndpoints(host.endpoints, admission.profile);
+        if (!Array.isArray(projected))
+            throw new Error(`RUNTIME_NOT_ADMITTED: ${projected.reason}`);
+        const mcpServers = projected.flatMap((plan) => {
+            const materialized = materializeProjection(plan, {
+                resolve(secretRef) {
+                    if (secretRef !== host.secretRef)
+                        throw new Error(`Unknown secret reference: ${secretRef}`);
+                    return `Bearer ${host.bearer.toString()}`;
+                },
+            });
+            if (materialized.kind !== 'acp-session' || materialized.provider !== options.provider)
+                throw new Error('ACP projection materialized for another provider');
+            return materialized.mcpServers.map((server) => ({
+                type: server.type,
+                name: server.name,
+                url: server.url,
+                headers: server.headers.map((header) => ({ name: header.name, value: header.value })),
+            }));
+        });
+        const protectedSurfaces = [...protectedValues, ...host.endpoints.map((endpoint) => endpoint.url)];
+        const sessionId = await admittedClient.newSession(mcpServers);
+        if (admittedClient.controlPlaneSecretFrames() !== 1 || admittedClient.inboundSecretSeen())
+            throw new Error('RUNTIME_NOT_ADMITTED: ACP secret isolation failed during session admission');
+        await assertProtectedSurfacesClean([scratchPath], protectedSurfaces, 'RUNTIME_NOT_ADMITTED: ACP protected projection reached a writable or unreadable surface');
+        reducer.markAdmitted();
+        reducer.markReady();
+        reducer.beginTurn('direct-call', options.provider);
+        await admittedClient.prompt(sessionId, normalPrompt(options.provider, cases));
+        await host.waitForQuiescence(30_000);
+        reducer.finalize('settled');
+        const normalEvidence = reducer.ledger.events();
+        if (!hasDecision(normalEvidence, cases.pureCaseId) || !hasDecision(normalEvidence, cases.errorCaseId))
+            throw new Error(`${options.provider} did not exercise direct success and structured tool error`);
+        reducer.beginTurn('cancelled-turn', options.provider);
+        const cancelled = admittedClient.prompt(sessionId, cancellationPrompt(cases)).then((result) => ({ kind: 'result', result }), (error) => ({ kind: 'error', error }));
+        const entered = await withTimeout(Promise.race([barrier.reached().then(() => 'barrier'), cancelled.then((result) => `terminal:${result.kind}`)]), 90_000, `${options.provider} blocking invocation`);
+        if (entered !== 'barrier')
+            throw new Error(`${options.provider} reached ${entered} before the blocking MCP transition`);
+        reducer.fence();
+        admittedClient.setCancelling(true);
+        admittedClient.cancel(sessionId);
+        reducer.abortUncommitted('provider-cancelled');
+        barrier.release();
+        const cancellation = await withTimeout(cancelled, 45_000, `${options.provider} cancelled prompt`);
+        admittedClient.setCancelling(false);
+        if (cancellation.kind === 'error')
+            throw cancellation.error;
+        await host.waitForQuiescence(30_000);
+        hostQuiescent = host.activeTransportCount() === 0;
+        if (!hostQuiescent)
+            throw new Error(`Scenario host was not quiescent after ${options.provider} cancellation`);
+        if (cancellation.result.stopReason !== 'cancelled')
+            throw new Error(`${options.provider} cancellation terminal was ${cancellation.result.stopReason}`);
+        reducer.observeProviderTerminal();
+        reducer.finalize('cancelled-clean');
+        reducer.beginTurn('post-cancel-reuse', options.provider);
+        await admittedClient.prompt(sessionId, reusePrompt(cases));
+        await host.waitForQuiescence(30_000);
+        reducer.finalize('settled');
+        if (!hasDecision(reducer.ledger.events(), cases.effectfulCaseId))
+            throw new Error(`${options.provider} post-cancel reuse did not reach the scenario host`);
+        const replay = replayPrivateEvidence({ artifact: compiled.artifact, evidence: reducer.ledger.events(), vault: replayVault, macKey });
+        if (!replay.ok || replay.poisoned || replay.finalState !== reducer.state)
+            throw new Error(`Private replay failed: ${replay.ok ? 'state mismatch' : replay.reason}`);
+        const chain = verifyEvidenceChain(reducer.ledger.events(), compiled.artifact.artifactDigest);
+        if (!chain.ok)
+            throw new Error(`Evidence chain failed: ${chain.reason}`);
+        await assertProtectedSurfacesClean([scratchPath], protectedSurfaces, 'ACP protected projection reached a writable or unreadable surface');
+        reducer.dispose();
+        const cleanup = await cleaner.dispose();
+        await rm(scratchParent, { recursive: true, force: true });
+        if (!persisted || cleanup.failures.length > 0 || cleanup.bearerFound || !cleanup.scratchDeleted)
+            throw new Error(`CLEANUP_FAILED: ${JSON.stringify(cleanup.failures)}`);
+        return {
+            selected: true,
+            profileFingerprint: options.profile.profileFingerprint,
+            artifact: compiled.artifact,
+            evidence: reducer.ledger.events(),
+            checks: { runtimeAdmitted: true, secretFreeProject: true, directCall: true, structuredToolError: true, fencedCancellation: true, providerTerminal: true, hostQuiescent, postCancelReuse: true, privateReplay: true, cleanup: true },
+            cleanup,
+            cancellationStatus: cancellation.result.stopReason,
+        };
+    }
+    catch (error) {
+        barrier.release();
+        client?.setCancelling(true);
+        try {
+            if (reducer.phase === 'ACTIVE')
+                reducer.fence();
+            if (reducer.phase === 'FENCING')
+                reducer.abortUncommitted('trial-failed');
+            if (!['DISPOSED', 'NEW', 'COMPILED', 'ADMITTED'].includes(reducer.phase))
+                reducer.finalize('poisoned', 'trial-failed');
+        }
+        catch (lifecycleFailure) {
+            void lifecycleFailure;
+        }
+        reducer.dispose();
+        let cleanupError;
+        try {
+            const report = await cleaner.dispose();
+            if (report.failures.length > 0 || report.bearerFound || !report.scratchDeleted)
+                cleanupError = new Error(`CLEANUP_FAILED: ${JSON.stringify(report.failures)}`);
+        }
+        catch (failure) {
+            cleanupError = failure instanceof Error ? failure : new Error(String(failure));
+        }
+        await rm(scratchParent, { recursive: true, force: true }).catch(() => undefined);
+        if (cleanupError)
+            throw new TrialExecutionError(error instanceof Error ? error.message : `${options.provider} direct MCP trial failed`, { primary: error, secondary: [cleanupError] });
+        throw error;
+    }
+}
+async function assertProtectedSurfacesClean(roots, protectedValues, message) {
+    for (const value of protectedValues) {
+        const scans = await scanBearerSurfaces(roots, value);
+        if (scans.some((entry) => entry.status !== 'clean'))
+            throw new Error(message);
+    }
+}
+function findContractCases(artifact) {
+    const state = artifact.canonicalIr.states[artifact.canonicalIr.initialState];
+    const entries = Object.entries(state.tools);
+    const effectful = entries.find(([, tool]) => tool.effectful && tool.cases.some((entry) => entry.transition && entry.outcome.kind === 'success' && 'exactArgs' in entry.when));
+    const error = entries.find(([, tool]) => tool.cases.some((entry) => entry.outcome.kind === 'tool-error' && 'exactArgs' in entry.when));
+    const pure = entries.find(([, tool]) => !tool.effectful && tool.cases.some((entry) => entry.outcome.kind === 'success'));
+    if (!effectful || !error || !pure)
+        throw new Error('ACP vertical requires an effectful success, structured error, and pure success in the initial state');
+    const successCase = effectful[1].cases.find((entry) => entry.transition && entry.outcome.kind === 'success' && 'exactArgs' in entry.when);
+    const errorCase = error[1].cases.find((entry) => entry.outcome.kind === 'tool-error' && 'exactArgs' in entry.when);
+    const pureCase = pure[1].cases.find((entry) => entry.outcome.kind === 'success');
+    const [serverId, effectfulToolId] = effectful[0].split('/');
+    return {
+        serverId,
+        effectfulToolId,
+        effectfulCaseId: successCase.id,
+        successArgs: exactArgs(successCase),
+        errorCaseId: errorCase.id,
+        errorArgs: exactArgs(errorCase),
+        pureToolId: pure[0].split('/')[1],
+        pureCaseId: pureCase.id,
+        pureArgs: 'exactArgs' in pureCase.when ? pureCase.when.exactArgs : deriveArgs(pureCase.when.all),
+    };
+}
+function exactArgs(scenarioCase) {
+    if (!('exactArgs' in scenarioCase.when))
+        throw new Error('ACP contract case requires exact arguments');
+    return scenarioCase.when.exactArgs;
+}
+function deriveArgs(predicates) {
+    const result = {};
+    for (const predicate of predicates)
+        if (predicate.pointer.startsWith('/') && 'equals' in predicate)
+            result[predicate.pointer.slice(1)] = predicate.equals;
+    return result;
+}
+function normalPrompt(provider, cases) {
+    return `Use only MCP server ${cases.serverId}. Invoke ${cases.pureToolId} exactly once with ${JSON.stringify(cases.pureArgs)}, then invoke ${cases.effectfulToolId} exactly once with ${JSON.stringify(cases.errorArgs)}. The second result is an expected tool error; do not retry it. Do not use shell or any other tool. Then answer ${provider.toUpperCase()}_DIRECT_DONE.`;
+}
+function cancellationPrompt(cases) {
+    return `Use only MCP server ${cases.serverId}. Invoke ${cases.effectfulToolId} exactly once with ${JSON.stringify(cases.successArgs)}. Wait for its result and do not use any other tool.`;
+}
+function reusePrompt(cases) {
+    return `Use only MCP server ${cases.serverId}. Invoke ${cases.effectfulToolId} exactly once with ${JSON.stringify(cases.successArgs)}. Wait for its result and do not use any other tool.`;
+}
+function hasDecision(evidence, caseId) {
+    return evidence.some((event) => event.payload.type === 'mcp.decision' && event.payload.caseId === caseId && event.payload.authority === 'scenario-host');
+}
+async function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs); }),
+    ]).finally(() => { if (timer)
+        clearTimeout(timer); });
+}

package/dist/internal/direct-mcp-v2/claude-direct-mcp.d.ts

@@ -0,0 +1,68 @@
+import { type McpSdkServerConfigWithInstance, type Options as ClaudeSdkOptions, type Query } from '@anthropic-ai/claude-agent-sdk';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type CleanupReport } from './cleanup.js';
+import { type MaterializedProjection } from './materialize.js';
+import type { EvidenceEnvelope, ScenarioArtifact, ScenarioMachineV2 } from './types.js';
+export declare const CLAUDE_DIRECT_MCP_FLAG = "PATHGRADE_INTERNAL_CLAUDE_DIRECT_MCP_V2";
+export type ClaudeDirectMcpChecks = {
+    runtimeAdmitted: boolean;
+    secretFreeProject: boolean;
+    directCall: boolean;
+    structuredToolError: boolean;
+    fencedCancellation: boolean;
+    providerTerminal: boolean;
+    hostQuiescent: boolean;
+    postCancelReuse: boolean;
+    privateReplay: boolean;
+    cleanup: boolean;
+};
+export type ClaudeDirectMcpTrialResult = {
+    selected: true;
+    profileFingerprint: string;
+    artifact: ScenarioArtifact;
+    evidence: readonly EvidenceEnvelope[];
+    checks: ClaudeDirectMcpChecks;
+    cleanup: CleanupReport;
+    cancellationStatus: string;
+};
+export type ClaudeSdkQueryFn = (args: {
+    prompt: string;
+    options?: ClaudeSdkOptions;
+}) => Query;
+type BridgeObservation = {
+    serverId: string;
+    toolId: string;
+    result: CallToolResult;
+};
+type ChildProjectionRecord = {
+    args: readonly string[];
+    environment: Readonly<Record<string, string | undefined>>;
+};
+type ClaudeParentBridges = Record<string, McpSdkServerConfigWithInstance>;
+export declare function isClaudeDirectMcpSelected(environment?: NodeJS.ProcessEnv): boolean;
+export declare function claudeDirectMcpDisableReason(): string | undefined;
+/** Test-only reset for proving the fail-closed process latch. */
+export declare function __resetClaudeDirectMcpDisablementForTesting(): void;
+export declare function mapClaudeProviderEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function assertClaudeProjectionIsolation(options: {
+    records: readonly ChildProjectionRecord[];
+    scans: readonly {
+        path: string;
+        status: string;
+    }[];
+    protectedValues: readonly string[];
+}): void;
+export declare function createClaudeParentBridges(options: {
+    artifact: ScenarioArtifact;
+    projections: readonly MaterializedProjection[];
+    observe?(observation: BridgeObservation): void;
+}): ClaudeParentBridges;
+export declare function runClaudeDirectMcpTrial(options: {
+    scenario: ScenarioMachineV2;
+    environment?: NodeJS.ProcessEnv;
+    model?: string;
+    artifactDirectory?: string;
+    query?: ClaudeSdkQueryFn;
+    initializeControlPlane?: () => Promise<void>;
+}): Promise<ClaudeDirectMcpTrialResult>;
+export {};