@wix/pathgrade 1.0.24 → 1.0.26

package/dist/internal/direct-mcp-v2/public-scenario-runtime.js

@@ -0,0 +1,353 @@
+import { randomBytes } from 'node:crypto';
+import { createSdkMcpServer, query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
+import { scanBearerSurfaces, TrialExecutionError } from './cleanup.js';
+import { PrivateReplayVault, replayPrivateEvidence } from './evidence.js';
+import { ScenarioHostReducer } from './host-reducer.js';
+import { materializeProjection } from './materialize.js';
+import { projectEndpoints } from './projection.js';
+import { admitRuntimeLock } from './runtime-lock.js';
+import { startScenarioHttpHost } from './scenario-http-host.js';
+import { createClaudeParentBridges } from './claude-direct-mcp.js';
+import { CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK, CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE, resolveClaudeScenarioExecutable } from './claude-profile.js';
+const defaultCoordinatorDependencies = {
+    startHost: startScenarioHttpHost,
+    scanBearerSurfaces,
+};
+export async function startScenarioCoordinator(options, dependencies = {}) {
+    const deps = { ...defaultCoordinatorDependencies, ...dependencies };
+    const scanRoots = scenarioScanRoots(options.workspacePath, options.environment);
+    const macKey = randomBytes(32);
+    const replayVault = new PrivateReplayVault(randomBytes(32));
+    const reducer = new ScenarioHostReducer(`${options.provider}-${randomBytes(12).toString('hex')}`, options.artifact, macKey, replayVault);
+    reducer.markCompiled();
+    let host;
+    let providerAttachment;
+    let activeTurn;
+    let removeAbortListener;
+    let cancellationRequest;
+    let cancellation;
+    let cancellationError;
+    let disposePromise;
+    const publishEvidence = () => {
+        options.onEvidence?.(structuredClone(reducer.ledger.events()));
+    };
+    const assertReplay = () => {
+        const replay = replayPrivateEvidence({
+            artifact: options.artifact,
+            evidence: reducer.ledger.events(),
+            vault: replayVault,
+            macKey,
+        });
+        if (!replay.ok || replay.finalState !== reducer.state || replay.poisoned) {
+            throw new Error(`Private scenario replay failed: ${!replay.ok ? replay.reason : replay.poisoned ? 'scenario poisoned' : 'state mismatch'}`);
+        }
+    };
+    const fence = (reason) => {
+        const turn = activeTurn;
+        if (!turn)
+            return undefined;
+        if (reducer.phase === 'ACTIVE')
+            reducer.fence();
+        if (reducer.phase === 'FENCING')
+            reducer.abortUncommitted(reason);
+        return turn;
+    };
+    const requestCancellation = (reason, status) => {
+        if (cancellationRequest)
+            return;
+        const turn = fence(reason);
+        if (!turn)
+            return;
+        cancellationRequest = {
+            turn,
+            reason,
+            status,
+            interruptFailures: (async () => {
+                try {
+                    await providerAttachment?.interrupt(turn, reason);
+                    return [];
+                }
+                catch (error) {
+                    return [error];
+                }
+            })(),
+        };
+    };
+    const finishCancellation = (reason, status) => {
+        requestCancellation(reason, status);
+        if (cancellation)
+            return cancellation;
+        const requested = cancellationRequest;
+        if (!requested)
+            return Promise.resolve();
+        cancellation = (async () => {
+            const failures = await requested.interruptFailures;
+            try {
+                await providerAttachment?.waitForTerminal(requested.turn);
+                reducer.observeProviderTerminal();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            try {
+                await host?.waitForQuiescence(30_000);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            if (failures.length > 0)
+                throw new AggregateError(failures, 'Scenario turn settlement failed');
+            reducer.finalize(requested.status, requested.status === 'poisoned' ? requested.reason : undefined);
+            assertReplay();
+            publishEvidence();
+            activeTurn = undefined;
+        })().catch((error) => {
+            cancellationError = error;
+            publishEvidence();
+            throw error;
+        });
+        void cancellation.catch(() => undefined);
+        return cancellation;
+    };
+    try {
+        host = await deps.startHost({ artifact: options.artifact, reducer, secretRef: 'public-scenario-v2-bearer' });
+        providerAttachment = await options.attach({
+            artifact: options.artifact,
+            endpoints: host.endpoints,
+            resolveSecret(secretRef) {
+                if (secretRef !== host?.secretRef)
+                    throw new Error(`Unknown secret reference: ${secretRef}`);
+                return `Bearer ${host.bearer.toString()}`;
+            },
+        });
+        reducer.markAdmitted();
+        reducer.markReady();
+    }
+    catch (error) {
+        const cleanupErrors = [];
+        const bearer = host?.bearer.toString() ?? '';
+        try {
+            await providerAttachment?.close();
+        }
+        catch (cleanupError) {
+            cleanupErrors.push(cleanupError);
+        }
+        try {
+            await host?.dispose();
+        }
+        catch (cleanupError) {
+            cleanupErrors.push(cleanupError);
+        }
+        if (bearer.length > 0) {
+            try {
+                const scans = await deps.scanBearerSurfaces(scanRoots, bearer);
+                if (scans.some((entry) => entry.status !== 'clean')) {
+                    cleanupErrors.push(new Error('Scenario bearer reached or could not be excluded from a writable surface'));
+                }
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+        }
+        try {
+            host?.bearer.fill(0);
+            macKey.fill(0);
+            replayVault.dispose();
+            reducer.dispose();
+        }
+        catch (cleanupError) {
+            cleanupErrors.push(cleanupError);
+        }
+        if (cleanupErrors.length > 0) {
+            throw new TrialExecutionError('Scenario coordinator setup failed and cleanup also failed', {
+                primary: error,
+                secondary: cleanupErrors,
+            });
+        }
+        throw error;
+    }
+    return {
+        attachment: providerAttachment.value,
+        beginTurn(turnId, signal) {
+            if (activeTurn)
+                throw new Error('A scenario coordinator turn is already active');
+            const turn = { turnId, provider: options.provider };
+            reducer.beginTurn(turnId, options.provider);
+            activeTurn = turn;
+            cancellationRequest = undefined;
+            cancellation = undefined;
+            cancellationError = undefined;
+            const onAbort = () => { requestCancellation('provider-cancelled', 'cancelled-clean'); };
+            signal.addEventListener('abort', onAbort, { once: true });
+            removeAbortListener = () => signal.removeEventListener('abort', onAbort);
+            if (signal.aborted)
+                onAbort();
+        },
+        async settleTurn() {
+            removeAbortListener?.();
+            removeAbortListener = undefined;
+            try {
+                if (cancellationRequest)
+                    return await finishCancellation('provider-cancelled', 'cancelled-clean');
+                const turn = activeTurn;
+                if (!turn)
+                    throw new Error('No scenario coordinator turn is active');
+                await providerAttachment.waitForTerminal(turn);
+                reducer.observeProviderTerminal();
+                await host?.waitForQuiescence(30_000);
+                if (reducer.phase === 'ACTIVE')
+                    reducer.finalize('settled');
+                else if (reducer.phase === 'POISONED')
+                    reducer.finalize('poisoned', 'scenario-host-poisoned');
+                else
+                    await finishCancellation('provider-cancelled', 'cancelled-clean');
+                assertReplay();
+                publishEvidence();
+                activeTurn = undefined;
+            }
+            catch (error) {
+                publishEvidence();
+                throw error;
+            }
+        },
+        async failTurn(error) {
+            removeAbortListener?.();
+            removeAbortListener = undefined;
+            try {
+                await finishCancellation('provider-failed', 'poisoned');
+            }
+            catch (lifecycleError) {
+                throw new TrialExecutionError('Provider turn failed and scenario settlement also failed', {
+                    primary: error,
+                    secondary: lifecycleError instanceof AggregateError
+                        ? lifecycleError.errors
+                        : [lifecycleError],
+                });
+            }
+        },
+        evidence: () => structuredClone(reducer.ledger.events()),
+        dispose() {
+            disposePromise ??= (async () => {
+                const failures = [];
+                const bearer = host?.bearer.toString() ?? '';
+                try {
+                    if (activeTurn)
+                        await finishCancellation('disposed', 'cancelled-clean');
+                    else if (cancellationError !== undefined)
+                        failures.push(cancellationError);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                publishEvidence();
+                try {
+                    await providerAttachment?.close();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                try {
+                    await host?.dispose();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                try {
+                    const scans = await deps.scanBearerSurfaces(scanRoots, bearer);
+                    if (scans.some((entry) => entry.status !== 'clean')) {
+                        failures.push(new Error('Scenario bearer reached or could not be excluded from a writable surface'));
+                    }
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+                finally {
+                    host?.bearer.fill(0);
+                    macKey.fill(0);
+                    replayVault.dispose();
+                    reducer.dispose();
+                    publishEvidence();
+                }
+                if (failures.length > 0)
+                    throw new AggregateError(failures, 'Scenario coordinator cleanup failed');
+            })();
+            return disposePromise;
+        },
+    };
+}
+function scenarioScanRoots(workspacePath, environment) {
+    return [...new Set([
+            workspacePath,
+            environment.HOME,
+            environment.TMPDIR,
+            environment.TMP,
+            environment.TEMP,
+            environment.CLAUDE_CONFIG_DIR,
+        ].filter((path) => typeof path === 'string' && path.length > 0))];
+}
+export async function startPublicClaudeScenarioRuntime(options, dependencies = {}) {
+    const lock = dependencies.lock ?? CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK;
+    const resolveExecutable = dependencies.resolveExecutable ?? resolveClaudeScenarioExecutable;
+    const coordinator = await startScenarioCoordinator({
+        ...options,
+        provider: 'claude',
+        async attach(context) {
+            const bearer = context.resolveSecret('public-scenario-v2-bearer');
+            const admission = await admitRuntimeLock(lock, {
+                provider: 'claude',
+                platform: process.platform,
+                architecture: process.arch,
+                resolvedExecutable: await resolveExecutable(options.environment),
+                environment: options.environment,
+                forbiddenSecrets: [bearer.slice('Bearer '.length), bearer],
+                ...(dependencies.commandVersion ? { commandVersion: dependencies.commandVersion } : {}),
+                initializeControlPlane: async () => {
+                    if (typeof createSdkMcpServer !== 'function' || typeof sdkQuery !== 'function') {
+                        throw new Error('Claude SDK parent bridge methods unavailable');
+                    }
+                    return {
+                        normalizedHandshake: CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE,
+                        capabilities: lock.capabilities,
+                        close: async () => undefined,
+                    };
+                },
+            });
+            const projected = projectEndpoints(context.endpoints, admission.profile);
+            if (!Array.isArray(projected))
+                throw new Error(`RUNTIME_NOT_ADMITTED: ${projected.reason}`);
+            const materialized = projected.map((plan) => materializeProjection(plan, {
+                resolve: context.resolveSecret,
+            }));
+            const bridges = createClaudeParentBridges({ artifact: options.artifact, projections: materialized });
+            return {
+                value: bridges,
+                async interrupt() { },
+                async waitForTerminal() { },
+                async close() {
+                    const failures = [];
+                    for (const bridge of Object.values(bridges)) {
+                        try {
+                            await bridge.instance.close();
+                        }
+                        catch (error) {
+                            failures.push(error);
+                        }
+                    }
+                    if (failures.length > 0)
+                        throw new AggregateError(failures, 'Claude scenario bridges failed to close');
+                },
+            };
+        },
+    });
+    return {
+        claudeServers: coordinator.attachment,
+        configureSession(sessionOptions) {
+            sessionOptions.scenarioMcpServers = coordinator.attachment;
+        },
+        beginTurn: coordinator.beginTurn,
+        settleTurn: coordinator.settleTurn,
+        failTurn: coordinator.failTurn,
+        evidence: coordinator.evidence,
+        dispose: coordinator.dispose,
+    };
+}

package/dist/internal/direct-mcp-v2/runtime-lock.d.ts

@@ -0,0 +1,51 @@
+import type { AdmittedRuntimeProfile, JsonObject, RuntimeCapabilityProfile } from './types.js';
+export type RuntimeLock = {
+    format: 'pathgrade-direct-mcp-runtime-lock-v1';
+    provider: 'claude' | 'codex' | 'cursor' | 'opencode';
+    platform: string;
+    architecture: string;
+    controlPlane: 'native-sdk-parent-bridge' | 'app-server' | 'acp-v1';
+    version: string;
+    commandArtifact: string;
+    args: readonly string[];
+    versionArgs: readonly string[];
+    artifacts: readonly {
+        id: string;
+        relativePath: string;
+        sha256: string;
+    }[];
+    capabilities: RuntimeCapabilityProfile['requiredCapabilities'];
+    normalizedHandshakeSha256: string;
+};
+export type RuntimeLockControlPlane = {
+    normalizedHandshake: JsonObject;
+    capabilities: RuntimeCapabilityProfile['requiredCapabilities'];
+    close(): Promise<void>;
+};
+export type RuntimeLockAdmissionContext<TControlPlane extends RuntimeLockControlPlane> = {
+    provider: RuntimeLock['provider'];
+    platform: string;
+    architecture: string;
+    resolvedExecutable: string;
+    environment?: Readonly<Record<string, string | undefined>>;
+    forbiddenSecrets?: readonly string[];
+    commandVersion?: (commandPath: string, args: readonly string[]) => Promise<string>;
+    initializeControlPlane(commandPath: string, args: readonly string[]): Promise<TControlPlane>;
+};
+export type RuntimeLockIdentity = {
+    provider: RuntimeLock['provider'];
+    platform: string;
+    architecture: string;
+    version: string;
+    artifactHashes: Readonly<Record<string, string>>;
+    capabilities: RuntimeCapabilityProfile['requiredCapabilities'];
+    normalizedHandshakeSha256: string;
+    lockFingerprint: string;
+};
+export type RuntimeLockAdmission<TControlPlane extends RuntimeLockControlPlane = RuntimeLockControlPlane> = {
+    commandPath: string;
+    identity: RuntimeLockIdentity;
+    profile: AdmittedRuntimeProfile;
+    controlPlane: TControlPlane;
+};
+export declare function admitRuntimeLock<TControlPlane extends RuntimeLockControlPlane>(rawLock: RuntimeLock, context: RuntimeLockAdmissionContext<TControlPlane>): Promise<RuntimeLockAdmission<TControlPlane>>;

package/dist/internal/direct-mcp-v2/runtime-lock.js

@@ -0,0 +1,203 @@
+/* oxlint-disable anti-slop/no-unknown-parameters -- Runtime observations cross the provider process trust boundary. */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { canonicalJson, sha256Canonical } from './json.js';
+const execFileAsync = promisify(execFile);
+const SHA256 = /^[a-f0-9]{64}$/;
+export async function admitRuntimeLock(rawLock, context) {
+    let controlPlane;
+    try {
+        const lock = validateRuntimeLock(rawLock);
+        if (lock.provider !== context.provider)
+            throw new Error('provider mismatch');
+        if (lock.platform !== context.platform || lock.architecture !== context.architecture)
+            throw new Error('platform or architecture mismatch');
+        const commandArtifact = lock.artifacts.find((artifact) => artifact.id === lock.commandArtifact);
+        if (!commandArtifact)
+            throw new Error('command artifact missing');
+        const commandPath = await realpath(context.resolvedExecutable);
+        const installationRoot = installationRootForCommand(commandPath, commandArtifact.relativePath);
+        const artifactPaths = new Map();
+        const artifactIdentities = new Map();
+        const artifactHashes = {};
+        for (const artifact of lock.artifacts) {
+            const path = resolveArtifactPath(installationRoot, artifact.relativePath);
+            const identity = await verifyRegularResolvedFile(path);
+            const digest = createHash('sha256').update(await readFile(path)).digest('hex');
+            if (digest !== artifact.sha256)
+                throw new Error(`artifact digest mismatch: ${artifact.id}`);
+            artifactPaths.set(artifact.id, path);
+            artifactIdentities.set(artifact.id, identity);
+            artifactHashes[artifact.id] = digest;
+        }
+        if (artifactPaths.get(lock.commandArtifact) !== commandPath)
+            throw new Error('resolved executable does not match command artifact');
+        const forbidden = forbiddenSurface([...lock.args, ...lock.versionArgs], context.environment ?? {}, context.forbiddenSecrets ?? []);
+        if (forbidden)
+            throw new Error(forbidden);
+        await verifyArtifactsUnchanged(lock, artifactPaths, artifactIdentities);
+        const version = context.commandVersion
+            ? await context.commandVersion(commandPath, lock.versionArgs)
+            : `${(await execFileAsync(commandPath, [...lock.versionArgs], {
+                timeout: 15_000,
+                maxBuffer: 1024 * 1024,
+                env: versionProbeEnvironment(context.environment ?? process.env),
+            })).stdout}`.trim();
+        if (version !== lock.version)
+            throw new Error('version mismatch');
+        await verifyArtifactsUnchanged(lock, artifactPaths, artifactIdentities);
+        controlPlane = await context.initializeControlPlane(commandPath, lock.args);
+        if (canonicalJson(controlPlane.capabilities) !== canonicalJson(lock.capabilities))
+            throw new Error('capability mismatch');
+        if (sha256Canonical(controlPlane.normalizedHandshake) !== lock.normalizedHandshakeSha256)
+            throw new Error('normalized handshake mismatch');
+        await verifyArtifactsUnchanged(lock, artifactPaths, artifactIdentities);
+        const lockFingerprint = sha256Canonical(lock);
+        const profile = {
+            format: 'pathgrade-direct-mcp-runtime-profile-v1',
+            provider: lock.provider,
+            platform: lock.platform,
+            architecture: lock.architecture,
+            controlPlane: lock.controlPlane,
+            command: { absolutePath: commandPath, args: [...lock.args], versionArgs: [...lock.versionArgs] },
+            expectedVersion: lock.version,
+            artifacts: lock.artifacts.map((artifact) => ({
+                label: artifact.id,
+                absolutePath: artifactPaths.get(artifact.id),
+                sha256: artifact.sha256,
+            })),
+            requiredCapabilities: lock.capabilities,
+            profileFingerprint: lockFingerprint,
+            runtimeCapabilityFingerprint: lock.normalizedHandshakeSha256,
+            admitted: true,
+        };
+        return {
+            commandPath,
+            identity: {
+                provider: lock.provider,
+                platform: lock.platform,
+                architecture: lock.architecture,
+                version: lock.version,
+                artifactHashes,
+                capabilities: lock.capabilities,
+                normalizedHandshakeSha256: lock.normalizedHandshakeSha256,
+                lockFingerprint,
+            },
+            profile,
+            controlPlane,
+        };
+    }
+    catch (error) {
+        await controlPlane?.close().catch(() => undefined);
+        throw new Error(`RUNTIME_NOT_ADMITTED: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function validateRuntimeLock(lock) {
+    canonicalJson(lock);
+    exactKeys(lock, [
+        'format', 'provider', 'platform', 'architecture', 'controlPlane', 'version',
+        'commandArtifact', 'args', 'versionArgs', 'artifacts', 'capabilities',
+        'normalizedHandshakeSha256',
+    ], '$');
+    if (lock.format !== 'pathgrade-direct-mcp-runtime-lock-v1')
+        throw new Error('unsupported runtime lock');
+    if (lock.provider !== 'claude' && lock.provider !== 'codex' && lock.provider !== 'cursor' && lock.provider !== 'opencode')
+        throw new Error('unsupported runtime-lock provider');
+    if ((lock.provider === 'claude' && lock.controlPlane !== 'native-sdk-parent-bridge')
+        || (lock.provider === 'codex' && lock.controlPlane !== 'app-server')
+        || ((lock.provider === 'cursor' || lock.provider === 'opencode') && lock.controlPlane !== 'acp-v1'))
+        throw new Error('provider/control-plane mismatch');
+    if (!lock.platform || !lock.architecture || !lock.version)
+        throw new Error('runtime-lock identity is incomplete');
+    if (!Array.isArray(lock.args) || lock.args.some((entry) => typeof entry !== 'string')
+        || !Array.isArray(lock.versionArgs) || lock.versionArgs.some((entry) => typeof entry !== 'string'))
+        throw new Error('runtime-lock arguments are invalid');
+    if (!Array.isArray(lock.artifacts) || lock.artifacts.length === 0)
+        throw new Error('runtime-lock artifacts are empty');
+    const ids = new Set();
+    for (const artifact of lock.artifacts) {
+        exactKeys(artifact, ['id', 'relativePath', 'sha256'], `artifact:${artifact.id || '<missing>'}`);
+        if (!artifact.id || ids.has(artifact.id))
+            throw new Error('runtime-lock artifact IDs must be unique');
+        ids.add(artifact.id);
+        validateRelativeArtifactPath(artifact.relativePath);
+        if (!SHA256.test(artifact.sha256))
+            throw new Error(`invalid artifact digest: ${artifact.id}`);
+    }
+    exactKeys(lock.capabilities, ['streamableHttp', 'controlPlaneHeaders', 'parentOwnedSdkMcp', 'cancellation'], '$/capabilities');
+    if (lock.capabilities.streamableHttp !== true || lock.capabilities.controlPlaneHeaders !== true)
+        throw new Error('required capabilities are incomplete');
+    const expectedCancellation = lock.provider === 'claude' ? 'abort-controller' : lock.provider === 'codex' ? 'turn-interrupt' : 'session-cancel';
+    if (lock.capabilities.cancellation !== expectedCancellation)
+        throw new Error('provider/cancellation mismatch');
+    if ((lock.provider === 'claude') !== (lock.capabilities.parentOwnedSdkMcp === true))
+        throw new Error('provider/parent-owned SDK bridge mismatch');
+    if (!SHA256.test(lock.normalizedHandshakeSha256))
+        throw new Error('invalid normalized handshake digest');
+    return lock;
+}
+function exactKeys(value, allowed, path) {
+    const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0)
+        throw new Error(`${path}: unknown runtime-lock fields ${unknown.sort().join(', ')}`);
+}
+function validateRelativeArtifactPath(path) {
+    if (!path || isAbsolute(path) || path.includes('\\') || path.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+        throw new Error(`unsafe artifact-relative path: ${path}`);
+    }
+}
+function installationRootForCommand(commandPath, relativeCommandPath) {
+    validateRelativeArtifactPath(relativeCommandPath);
+    let root = commandPath;
+    for (const _part of relativeCommandPath.split('/'))
+        root = dirname(root);
+    if (resolveArtifactPath(root, relativeCommandPath) !== commandPath)
+        throw new Error('resolved executable escaped its runtime root');
+    return root;
+}
+function resolveArtifactPath(root, relativePath) {
+    validateRelativeArtifactPath(relativePath);
+    const path = resolve(root, ...relativePath.split('/'));
+    const difference = relative(root, path);
+    if (difference === '' || difference.startsWith('..') || isAbsolute(difference))
+        throw new Error(`artifact escaped runtime root: ${relativePath}`);
+    return path;
+}
+async function verifyRegularResolvedFile(path) {
+    const stat = await lstat(path, { bigint: true });
+    if (!stat.isFile() || stat.isSymbolicLink() || await realpath(path) !== path)
+        throw new Error(`artifact is not a regular resolved file: ${path}`);
+    return { device: stat.dev, inode: stat.ino, size: stat.size, modifiedNs: stat.mtimeNs };
+}
+async function verifyUnchanged(path, before) {
+    const after = await verifyRegularResolvedFile(path);
+    if (after.device !== before.device || after.inode !== before.inode || after.size !== before.size || after.modifiedNs !== before.modifiedNs) {
+        throw new Error(`artifact changed during admission: ${path}`);
+    }
+}
+async function verifyArtifactsUnchanged(lock, paths, identities) {
+    for (const artifact of lock.artifacts) {
+        await verifyUnchanged(paths.get(artifact.id), identities.get(artifact.id));
+    }
+}
+function versionProbeEnvironment(environment) {
+    const allowed = ['HOME', 'PATH', 'PATHEXT', 'SystemRoot', 'TEMP', 'TMP', 'TMPDIR', 'WINDIR'];
+    return Object.fromEntries(allowed.flatMap((name) => {
+        const value = environment[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+}
+function forbiddenSurface(arguments_, environment, secrets) {
+    for (const argument of arguments_) {
+        if (secrets.some((secret) => secret.length > 0 && argument.includes(secret)))
+            return 'protected value reached runtime arguments';
+    }
+    for (const [name, value] of Object.entries(environment)) {
+        if (value !== undefined && secrets.some((secret) => secret.length > 0 && value.includes(secret)))
+            return `protected value reached runtime environment entry: ${name}`;
+    }
+    return undefined;
+}

package/dist/internal/direct-mcp-v2/runtime-profile.d.ts

@@ -0,0 +1,28 @@
+import type { AdmittedRuntimeProfile, JsonObject, RuntimeCapabilityProfile } from './types.js';
+export type RuntimeAdmissionContext = {
+    provider: RuntimeCapabilityProfile['provider'];
+    platform: string;
+    architecture: string;
+    environment?: Readonly<Record<string, string | undefined>>;
+    forbiddenSecrets?: readonly string[];
+    commandVersion?: (path: string, args: readonly string[]) => Promise<string>;
+    initializeControlPlane: () => Promise<{
+        normalizedHandshake: JsonObject;
+        capabilities: RuntimeCapabilityProfile['requiredCapabilities'];
+        close(): Promise<void>;
+    }>;
+};
+export type RuntimeAdmissionResult = {
+    ok: true;
+    profile: AdmittedRuntimeProfile;
+    normalizedHandshake: JsonObject;
+    controlPlane: Awaited<ReturnType<RuntimeAdmissionContext['initializeControlPlane']>>;
+} | {
+    ok: false;
+    code: 'RUNTIME_NOT_ADMITTED';
+    reason: string;
+};
+export declare function profileFingerprint(profile: Omit<RuntimeCapabilityProfile, 'profileFingerprint' | 'runtimeCapabilityFingerprint'>): string;
+export declare function runtimeCapabilityFingerprint(normalizedHandshake: JsonObject): string;
+export declare function parseRuntimeProfile(input: string | unknown): RuntimeCapabilityProfile;
+export declare function admitRuntimeProfile(rawProfile: string | unknown, context: RuntimeAdmissionContext): Promise<RuntimeAdmissionResult>;