@straiffi/archon 1.8.15 → 1.8.17

package/dist/server/lib/dockerSandboxExecutionEnvironment.js

@@ -0,0 +1,725 @@
+import { execFile as execFileCallback, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { requireExecutionCapabilities } from './executionEnvironmentLifecycle.js';
+export const DOCKER_SANDBOX_PROVIDER = 'docker_sandbox';
+export const QUALIFIED_SBX_VERSION = '0.38.0';
+export const QUALIFIED_SBX_BUILD = 'c022b14634c4bea846ca12870d1d5e97d5868b54';
+export const DOCKER_SANDBOX_ADAPTER_CONTRACT_VERSION = '4';
+export const DOCKER_SANDBOX_MAX_NAME_BYTES = 63;
+export const QUALIFIED_DOCKER_SANDBOX_TEMPLATES = {
+    opencode: 'docker.io/docker/sandbox-templates:opencode',
+    claude: 'docker.io/docker/sandbox-templates:claude-code',
+};
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_OUTPUT_LIMIT_BYTES = 256 * 1024;
+const SANDBOX_NAME_HASH_LENGTH = 16;
+const MINIMUM_MACOS_MAJOR = 14;
+const KVM_DEVICE_PATH = '/dev/kvm';
+const execFile = promisify(execFileCallback);
+const QUALIFIED_DOCKER_SANDBOX_HOSTS = [
+    { platform: 'linux', architecture: 'x64' },
+    { platform: 'darwin', architecture: 'arm64' },
+];
+export const isQualifiedDockerSandboxHost = (platform, architecture) => QUALIFIED_DOCKER_SANDBOX_HOSTS.some(host => host.platform === platform && host.architecture === architecture);
+export const dockerSandboxExecutionEnvironmentCapabilities = {
+    isolation: 'microvm',
+    directWritableWorkspace: 'supported',
+    transparentHeadlessStreams: 'supported',
+    credentialBrokering: 'supported',
+    enforcedNetworkAllowlist: 'unknown',
+    persistentEnvironments: 'supported',
+    resourceIsolation: 'unknown',
+    nestedContainers: 'unsupported',
+    publishedPorts: 'unsupported',
+    resourceControls: 'unsupported',
+};
+export const dockerSandboxExecutionEnvironmentObservation = {
+    providerVersion: QUALIFIED_SBX_VERSION,
+    capabilities: dockerSandboxExecutionEnvironmentCapabilities,
+    degradationReasons: ['The selected direct workspace remains writable from the sandbox.'],
+    agentTemplates: {
+        opencode: { support: 'unknown', templateId: null, reason: 'Template output has not been qualified.' },
+        claude: { support: 'unknown', templateId: null, reason: 'Template output has not been qualified.' },
+    },
+};
+export class SbxCommandFailure extends Error {
+    kind;
+    args;
+    constructor(kind, args, message, options = {}) {
+        super(message, options);
+        this.name = 'SbxCommandFailure';
+        this.kind = kind;
+        this.args = [...args];
+    }
+}
+export class SbxContractFailure extends Error {
+    command;
+    constructor(command, message, options = {}) {
+        super(message, options);
+        this.name = 'SbxContractFailure';
+        this.command = command;
+    }
+}
+export class DockerSandboxStopVerificationFailure extends SbxContractFailure {
+    constructor(message) {
+        super('stop', message);
+        this.name = 'DockerSandboxStopVerificationFailure';
+    }
+}
+export class DockerSandboxCollisionFailure extends Error {
+    sandboxName;
+    constructor(sandboxName, message) {
+        super(message);
+        this.name = 'DockerSandboxCollisionFailure';
+        this.sandboxName = sandboxName;
+    }
+}
+const validateCommandLimit = (name, value, maximum) => {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+        throw new Error(`${name} must be between 1 and ${maximum}`);
+    }
+};
+export const createSbxCommandRunner = (dependencies = {}) => {
+    const executable = dependencies.executable ?? 'sbx';
+    const spawnCommand = dependencies.spawn ?? spawn;
+    return {
+        run: (args, options = {}) => new Promise((resolve, reject) => {
+            const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;
+            validateCommandLimit('sbx timeoutMs', timeoutMs, 3_600_000);
+            validateCommandLimit('sbx maxOutputBytes', maxOutputBytes, 128 * 1024 * 1024);
+            if (options.signal?.aborted) {
+                reject(new SbxCommandFailure('cancelled', args, 'sbx command was cancelled before it started'));
+                return;
+            }
+            let child;
+            try {
+                child = spawnCommand(executable, args, {
+                    env: process.env,
+                    shell: false,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                    windowsHide: true,
+                });
+            }
+            catch (error) {
+                const kind = error.code === 'ENOENT' ? 'missing_cli' : 'spawn_failed';
+                reject(new SbxCommandFailure(kind, args, `Unable to start ${executable}`, { cause: error }));
+                return;
+            }
+            const stdout = [];
+            const stderr = [];
+            let outputBytes = 0;
+            let settled = false;
+            const cleanup = () => {
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', onAbort);
+            };
+            const fail = (kind, message, cause) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                child.kill('SIGKILL');
+                reject(new SbxCommandFailure(kind, args, message, cause === undefined ? {} : { cause }));
+            };
+            const collect = (destination, rawChunk) => {
+                const chunk = Buffer.from(rawChunk);
+                outputBytes += chunk.length;
+                if (outputBytes > maxOutputBytes) {
+                    fail('output_limit', `sbx output exceeded ${maxOutputBytes} bytes`);
+                    return;
+                }
+                destination.push(chunk);
+            };
+            const onAbort = () => fail('cancelled', 'sbx command was cancelled');
+            const timer = setTimeout(() => fail('timeout', `sbx command exceeded ${timeoutMs}ms`), timeoutMs);
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            if (options.signal?.aborted) {
+                onAbort();
+                return;
+            }
+            child.stdout.on('data', chunk => collect(stdout, chunk));
+            child.stderr.on('data', chunk => collect(stderr, chunk));
+            child.once('error', error => {
+                const kind = error.code === 'ENOENT' ? 'missing_cli' : 'spawn_failed';
+                fail(kind, `Unable to run ${executable}`, error);
+            });
+            child.stdin.once('error', error => {
+                if (settled) {
+                    return;
+                }
+                fail('spawn_failed', `Unable to write stdin to ${executable}`, error);
+            });
+            child.once('close', code => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                resolve({
+                    args: [...args],
+                    exitCode: code ?? 1,
+                    stdout: Buffer.concat(stdout).toString('utf8'),
+                    stderr: Buffer.concat(stderr).toString('utf8'),
+                });
+            });
+            try {
+                if (options.stdin === undefined) {
+                    child.stdin.end();
+                }
+                else {
+                    child.stdin.end(options.stdin);
+                }
+            }
+            catch (error) {
+                fail('spawn_failed', `Unable to write stdin to ${executable}`, error);
+            }
+        }),
+    };
+};
+const asRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null);
+const parseJsonObject = (command, output) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch (error) {
+        throw new SbxContractFailure(command, `sbx ${command} returned invalid JSON`, { cause: error });
+    }
+    const record = asRecord(parsed);
+    if (!record) {
+        throw new SbxContractFailure(command, `sbx ${command} returned an unrecognized JSON document`);
+    }
+    return record;
+};
+export const parseQualifiedSbxVersion = (output) => {
+    const match = /^sbx version: v(\d+\.\d+\.\d+) ([0-9a-f]{40})\r?\n?$/.exec(output);
+    if (!match) {
+        throw new SbxContractFailure('version', 'sbx version output did not match the qualified contract');
+    }
+    if (match[1] !== QUALIFIED_SBX_VERSION) {
+        throw new SbxContractFailure('version', `Unsupported sbx version ${match[1]}; Archon requires exactly ${QUALIFIED_SBX_VERSION}`);
+    }
+    if (match[2] !== QUALIFIED_SBX_BUILD) {
+        throw new SbxContractFailure('version', `Unsupported sbx build ${match[2]}; Archon requires exactly ${QUALIFIED_SBX_BUILD}`);
+    }
+    return match[1];
+};
+export const parseSbxDiagnostics = (output) => {
+    const record = parseJsonObject('diagnose', output);
+    if (record.version !== '1.0' || !Array.isArray(record.checks)) {
+        throw new SbxContractFailure('diagnose', 'sbx diagnose returned an unsupported schema');
+    }
+    return record.checks.map((value, index) => {
+        const check = asRecord(value);
+        if (!check
+            || typeof check.name !== 'string'
+            || typeof check.status !== 'string'
+            || !['fail', 'pass', 'skip', 'warn'].includes(check.status)
+            || typeof check.message !== 'string'
+            || typeof check.hint !== 'string') {
+            throw new SbxContractFailure('diagnose', `sbx diagnose check ${index} was unrecognized`);
+        }
+        return {
+            name: check.name,
+            status: check.status,
+            message: check.message,
+            hint: check.hint,
+        };
+    });
+};
+const diagnosticObservation = (checks, code, names, fallback) => {
+    const check = checks.find(candidate => names.includes(candidate.name.toLowerCase()));
+    if (!check) {
+        return { code, state: 'unknown', summary: fallback, remediation: 'Run sbx diagnose and review this check.' };
+    }
+    const state = check.status === 'pass' ? 'ready' : check.status === 'skip' ? 'unknown' : 'not_ready';
+    return {
+        code,
+        state,
+        summary: check.message.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim(),
+        remediation: state === 'ready'
+            ? null
+            : check.hint.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim() || 'Review sbx diagnostics.',
+    };
+};
+const nodeErrorCode = (error) => {
+    if (error instanceof Error && 'code' in error && typeof error.code === 'string') {
+        return error.code;
+    }
+    return null;
+};
+const readMacOsVersion = async () => {
+    try {
+        const result = await execFile('sw_vers', ['-productVersion'], { timeout: 5_000, maxBuffer: 4096 });
+        const version = result.stdout.trim();
+        return version.length > 0 ? version : null;
+    }
+    catch {
+        return null;
+    }
+};
+const macOsMajorVersion = (version) => {
+    const match = /^(\d+)(?:\.|$)/.exec(version);
+    return match ? Number(match[1]) : null;
+};
+const probeDockerSandboxPlatformReadiness = async (platform, architecture, options) => {
+    if (!isQualifiedDockerSandboxHost(platform, architecture)) {
+        return {
+            code: 'platform',
+            state: 'unsupported',
+            summary: `${platform}/${architecture} is not qualified.`,
+            remediation: 'Use Linux x64 or macOS Sonoma 14+ on Apple silicon for Docker Sandboxes.',
+        };
+    }
+    if (platform !== 'darwin') {
+        return {
+            code: 'platform',
+            state: 'ready',
+            summary: `${platform}/${architecture} is supported.`,
+            remediation: null,
+        };
+    }
+    const version = options.macOsVersion !== undefined
+        ? options.macOsVersion
+        : await (options.macOsVersionProbe ?? readMacOsVersion)();
+    const majorVersion = version ? macOsMajorVersion(version) : null;
+    if (majorVersion === null) {
+        return {
+            code: 'platform',
+            state: 'unknown',
+            summary: 'The macOS version could not be verified.',
+            remediation: 'Run macOS Sonoma 14 or later on Apple silicon, then recheck.',
+        };
+    }
+    if (majorVersion < MINIMUM_MACOS_MAJOR) {
+        return {
+            code: 'platform',
+            state: 'unsupported',
+            summary: `macOS ${version} is not qualified; Docker Sandboxes requires Sonoma 14 or later.`,
+            remediation: 'Upgrade to macOS Sonoma 14 or later on Apple silicon, then recheck.',
+        };
+    }
+    return {
+        code: 'platform',
+        state: 'ready',
+        summary: `darwin/${architecture} is supported on macOS ${version}.`,
+        remediation: null,
+    };
+};
+export const probeLinuxKvmReadiness = async (platform, architecture, kvmAccess = access) => {
+    if (platform !== 'linux' || architecture !== 'x64') {
+        return {
+            code: 'virtualization',
+            state: 'unsupported',
+            summary: 'Virtualization probing is only qualified on Linux x64.',
+            remediation: 'Use a Linux x64 host supported by Docker Sandboxes.',
+        };
+    }
+    try {
+        await kvmAccess(KVM_DEVICE_PATH, fsConstants.R_OK | fsConstants.W_OK);
+        return {
+            code: 'virtualization',
+            state: 'ready',
+            summary: 'KVM device /dev/kvm is available.',
+            remediation: null,
+        };
+    }
+    catch (error) {
+        const code = nodeErrorCode(error);
+        if (code === 'ENOENT') {
+            return {
+                code: 'virtualization',
+                state: 'not_ready',
+                summary: 'KVM device /dev/kvm was not found.',
+                remediation: 'Enable CPU virtualization and KVM on this host, then recheck.',
+            };
+        }
+        if (code === 'EACCES' || code === 'EPERM') {
+            return {
+                code: 'virtualization',
+                state: 'not_ready',
+                summary: 'KVM device /dev/kvm is not accessible to the Archon process.',
+                remediation: 'Grant the Archon user access to /dev/kvm, typically through the kvm group, then recheck.',
+            };
+        }
+        return {
+            code: 'virtualization',
+            state: 'unknown',
+            summary: 'KVM availability could not be verified.',
+            remediation: 'Review host KVM diagnostics, then recheck.',
+        };
+    }
+};
+const probeDockerSandboxVirtualizationReadiness = async (platform, architecture, platformObservation, kvmAccess) => {
+    if (platform === 'linux') {
+        return probeLinuxKvmReadiness(platform, architecture, kvmAccess);
+    }
+    if (platform === 'darwin' && architecture === 'arm64') {
+        if (platformObservation.state === 'ready') {
+            return {
+                code: 'virtualization',
+                state: 'ready',
+                summary: 'Apple silicon virtualization is provided by the qualified macOS host.',
+                remediation: null,
+            };
+        }
+        if (platformObservation.state === 'unsupported') {
+            return {
+                code: 'virtualization',
+                state: 'unsupported',
+                summary: 'macOS virtualization is unavailable because this host is not qualified.',
+                remediation: 'Use macOS Sonoma 14 or later on Apple silicon, then recheck.',
+            };
+        }
+        return {
+            code: 'virtualization',
+            state: 'unknown',
+            summary: 'macOS virtualization could not be verified because the host platform is unknown.',
+            remediation: 'Run macOS Sonoma 14 or later on Apple silicon, then recheck.',
+        };
+    }
+    return {
+        code: 'virtualization',
+        state: 'unsupported',
+        summary: 'Virtualization is not qualified on this host.',
+        remediation: 'Use Linux x64 or macOS Sonoma 14+ on Apple silicon for Docker Sandboxes.',
+    };
+};
+export const probeDockerSandboxReadiness = async (runner, options = {}) => {
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    const observations = [];
+    let providerVersion = null;
+    let versionResult;
+    try {
+        versionResult = await runner.run(['version'], options);
+        observations.push({ code: 'cli', state: 'ready', summary: 'sbx CLI is installed.', remediation: null });
+    }
+    catch (error) {
+        if (error instanceof SbxCommandFailure && error.kind === 'missing_cli') {
+            return {
+                providerVersion: null,
+                observations: [
+                    { code: 'cli', state: 'not_ready', summary: 'sbx CLI is not installed.', remediation: 'Install the qualified sbx release from Docker.' },
+                    ...['version', 'platform', 'virtualization', 'daemon', 'docker_login', 'network_policy', 'opencode_template', 'claude_template']
+                        .map(code => ({ code, state: 'unknown', summary: 'Not checked because sbx is unavailable.', remediation: null })),
+                ],
+            };
+        }
+        throw error;
+    }
+    try {
+        if (versionResult.exitCode !== 0) {
+            throw new SbxContractFailure('version', `sbx version exited with code ${versionResult.exitCode}`);
+        }
+        providerVersion = parseQualifiedSbxVersion(versionResult.stdout);
+        observations.push({ code: 'version', state: 'ready', summary: `sbx ${providerVersion} is qualified.`, remediation: null });
+    }
+    catch (error) {
+        observations.push({
+            code: 'version',
+            state: 'unsupported',
+            summary: error instanceof Error ? error.message : 'sbx version is unsupported.',
+            remediation: `Install sbx ${QUALIFIED_SBX_VERSION}.`,
+        });
+    }
+    const platformObservation = await probeDockerSandboxPlatformReadiness(platform, architecture, options);
+    observations.push(platformObservation);
+    observations.push(await probeDockerSandboxVirtualizationReadiness(platform, architecture, platformObservation, options.kvmAccess));
+    const diagnose = await runner.run(['diagnose', '--output', 'json'], options);
+    if (diagnose.exitCode !== 0 && diagnose.stdout.trim().length === 0) {
+        throw new SbxContractFailure('diagnose', 'sbx diagnose failed without structured output');
+    }
+    const checks = parseSbxDiagnostics(diagnose.stdout);
+    observations.push(diagnosticObservation(checks, 'daemon', ['daemon'], 'Daemon readiness was not reported.'));
+    observations.push(diagnosticObservation(checks, 'docker_login', ['authentication'], 'Docker login readiness was not reported.'));
+    const daemonReady = observations.some(observation => observation.code === 'daemon' && observation.state === 'ready');
+    const loginReady = observations.some(observation => observation.code === 'docker_login' && observation.state === 'ready');
+    if (options.includeDeferredObservations !== false && daemonReady && loginReady) {
+        const policy = await runner.run(['policy', 'ls', '--json'], options);
+        observations.push({
+            code: 'network_policy',
+            state: policy.exitCode === 0 ? 'unknown' : 'not_ready',
+            summary: policy.exitCode === 0
+                ? 'Sandbox network policy output has not been qualified.'
+                : 'Sandbox network policy is not ready.',
+            remediation: policy.exitCode === 0
+                ? 'Review sbx policy output before enabling this capability.'
+                : 'Initialize network policy interactively with sbx before retrying.',
+        });
+    }
+    else {
+        observations.push({
+            code: 'network_policy',
+            state: 'unknown',
+            summary: options.includeDeferredObservations === false
+                ? 'Network policy is deferred until environment preparation and validation.'
+                : 'Network policy was not queried because the runtime is not ready.',
+            remediation: null,
+        });
+    }
+    for (const [code, agent] of [['opencode_template', 'OpenCode'], ['claude_template', 'Claude']]) {
+        observations.push({
+            code,
+            state: 'unknown',
+            summary: `${agent} template output has not been qualified.`,
+            remediation: 'Review qualified template output before enabling this capability.',
+        });
+    }
+    return { providerVersion, observations };
+};
+const slug = (value, maximum) => {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9.-]+/g, '-').replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '');
+    return (normalized || 'target').slice(0, maximum).replace(/[^a-z0-9]+$/g, '') || 'target';
+};
+export const createDockerSandboxName = (identity) => {
+    if (!Number.isSafeInteger(identity.environmentRevision) || identity.environmentRevision < 1) {
+        throw new Error('Docker Sandbox environment revision must be a positive integer');
+    }
+    if (!/^[0-9a-f]{64}$/.test(identity.validationFingerprint)) {
+        throw new Error('Docker Sandbox validation fingerprint must be a SHA-256 digest');
+    }
+    const hash = createHash('sha256')
+        .update(`${identity.projectId}\0${identity.targetKey}\0${identity.environmentRevision}\0${identity.validationFingerprint}`, 'utf8')
+        .digest('hex')
+        .slice(0, SANDBOX_NAME_HASH_LENGTH);
+    const revision = String(identity.environmentRevision);
+    const fixedBytes = Buffer.byteLength(`archon---r${revision}-${hash}`, 'utf8');
+    const available = DOCKER_SANDBOX_MAX_NAME_BYTES - fixedBytes;
+    const projectLength = Math.max(4, Math.floor(available * 0.4));
+    const targetLength = Math.max(4, available - projectLength);
+    return `archon-${slug(identity.projectId, projectLength)}-${slug(identity.targetKey, targetLength)}-r${revision}-${hash}`;
+};
+const QUALIFIED_INSPECTION_FIELDS = new Set([
+    'agent',
+    'auth_mode',
+    'daemon_uptime',
+    'daemon_version',
+    'image',
+    'image_digest',
+    'kits',
+    'mcp_gateway',
+    'name',
+    'network',
+    'network_policy',
+    'proxy',
+    'secrets',
+    'sessions',
+    'state',
+    'uptime',
+    'workspace',
+]);
+const jsonValueKind = (value) => (value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value);
+const describeInspectionShape = (record) => {
+    const fields = Object.keys(record).sort();
+    const description = fields.map(field => `${field}:${jsonValueKind(record[field])}`).join(', ');
+    return description.slice(0, 500);
+};
+export const parseDockerSandboxInspection = (output) => {
+    const record = parseJsonObject('inspect', output);
+    const fields = Object.keys(record).sort();
+    const workspace = record.workspace;
+    if (fields.some(field => !QUALIFIED_INSPECTION_FIELDS.has(field))
+        || typeof record.name !== 'string'
+        || record.name.length === 0
+        || (record.agent !== 'opencode' && record.agent !== 'claude')
+        || (record.state !== 'running' && record.state !== 'stopped')
+        || typeof workspace !== 'string'
+        || workspace.length === 0
+        || typeof record.image !== 'string'
+        || record.image.length === 0) {
+        throw new SbxContractFailure('inspect', `sbx inspect returned an unrecognized sandbox identity (fields: ${describeInspectionShape(record)})`);
+    }
+    return {
+        name: record.name,
+        agent: record.agent,
+        state: record.state,
+        workspacePath: workspace,
+        template: record.image,
+    };
+};
+const assertInspectionMatches = (expected, observed) => {
+    if (observed.name !== expected.name
+        || observed.agent !== expected.agent
+        || observed.workspacePath !== expected.workspacePath
+        || observed.template !== expected.template) {
+        throw new DockerSandboxCollisionFailure(expected.name, `Sandbox ${expected.name} does not match Archon's persisted external identity`);
+    }
+};
+const exitCodeFailureMessage = (command, result) => {
+    const stderr = result.stderr.trim().slice(0, 500);
+    return `sbx ${command} exited with code ${result.exitCode}${stderr ? `: ${stderr}` : ''}`;
+};
+const requireSuccessfulCommand = (command, result) => {
+    if (result.exitCode !== 0) {
+        throw new SbxContractFailure(command, exitCodeFailureMessage(command, result));
+    }
+};
+const isQualifiedMissingSandboxResult = (result) => (result.args[0] === 'inspect'
+    && typeof result.args[1] === 'string'
+    && result.args[1].length > 0
+    && result.exitCode === 1
+    && result.stdout === ''
+    && result.stderr === `ERROR: sandbox '${result.args[1]}' not found\n`);
+export const createDockerSandboxAdapter = (runner, qualificationOptions = {}) => {
+    let qualification = null;
+    const waitForQualification = (operation, signal) => {
+        if (!signal) {
+            return operation;
+        }
+        if (signal.aborted) {
+            return Promise.reject(new SbxCommandFailure('cancelled', ['version'], 'sbx version qualification was cancelled'));
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                reject(new SbxCommandFailure('cancelled', ['version'], 'sbx version qualification was cancelled'));
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            operation.then(() => {
+                signal.removeEventListener('abort', onAbort);
+                resolve();
+            }, error => {
+                signal.removeEventListener('abort', onAbort);
+                reject(error);
+            });
+        });
+    };
+    const ensureQualified = (options) => {
+        const platform = qualificationOptions.platform ?? process.platform;
+        const architecture = qualificationOptions.architecture ?? process.arch;
+        if (!isQualifiedDockerSandboxHost(platform, architecture)) {
+            throw new SbxContractFailure('platform', `Unsupported sbx platform ${platform}/${architecture}; Archon requires linux/x64 or darwin/arm64`);
+        }
+        if (!qualification) {
+            const qualificationCommandOptions = {
+                timeoutMs: options.timeoutMs,
+                maxOutputBytes: options.maxOutputBytes,
+                stdin: options.stdin,
+            };
+            const attempt = runner.run(['version'], qualificationCommandOptions).then(result => {
+                requireSuccessfulCommand('version', result);
+                parseQualifiedSbxVersion(result.stdout);
+            });
+            qualification = attempt.catch(error => {
+                qualification = null;
+                throw error;
+            });
+        }
+        return waitForQualification(qualification, options.signal);
+    };
+    const inspect = async (name, options = {}) => {
+        await ensureQualified(options);
+        const result = await runner.run(['inspect', name, '--json'], options);
+        if (result.exitCode !== 0) {
+            if (isQualifiedMissingSandboxResult(result)) {
+                return null;
+            }
+            throw new SbxContractFailure('inspect', exitCodeFailureMessage('inspect', result));
+        }
+        return parseDockerSandboxInspection(result.stdout);
+    };
+    const requireExpected = async (expected, options) => {
+        const observed = await inspect(expected.name, options);
+        if (!observed) {
+            throw new SbxContractFailure('inspect', `Sandbox ${expected.name} does not exist`);
+        }
+        assertInspectionMatches(expected, observed);
+        return observed;
+    };
+    const reconnect = async (expected, options = {}) => {
+        let observed = await requireExpected(expected, options);
+        if (observed.state === 'stopped') {
+            const result = await runner.run(['exec', observed.name, '--', 'true'], options);
+            requireSuccessfulCommand('exec', result);
+            observed = await requireExpected(expected, options);
+        }
+        return observed;
+    };
+    return {
+        create: async (request, options = {}) => {
+            const name = createDockerSandboxName(request.identity);
+            const existing = await inspect(name, options);
+            const expected = { name, agent: request.agent, workspacePath: request.workspacePath, template: request.template };
+            if (existing) {
+                assertInspectionMatches(expected, existing);
+                return existing.state === 'running' ? existing : reconnect(expected, options);
+            }
+            const result = await runner.run([
+                'create', '--quiet', '--name', name, '--template', request.template, request.agent, request.workspacePath,
+            ], options);
+            requireSuccessfulCommand('create', result);
+            return requireExpected(expected, options);
+        },
+        inspect,
+        reconnect,
+        exec: async (expected, command, args, options = {}) => {
+            await requireExpected(expected, options);
+            const workdir = options.cwd === undefined ? [] : ['--workdir', options.cwd];
+            return runner.run(['exec', ...workdir, expected.name, '--', command, ...args], options);
+        },
+        stop: async (expected, options = {}) => {
+            let observed = await requireExpected(expected, options);
+            if (observed.state === 'running') {
+                requireSuccessfulCommand('stop', await runner.run(['stop', expected.name], options));
+                observed = await requireExpected(expected, options);
+            }
+            if (observed.state !== 'stopped') {
+                throw new DockerSandboxStopVerificationFailure(`Sandbox ${expected.name} did not reach the stopped state`);
+            }
+        },
+        remove: async (expected, options = {}) => {
+            await requireExpected(expected, options);
+            requireSuccessfulCommand('rm', await runner.run(['rm', '--force', expected.name], options));
+        },
+    };
+};
+export const createDockerSandboxExecutionEnvironmentLifecycle = (dependencies) => {
+    const inspect = async (environment, options = {}) => {
+        const expected = dependencies.resolveExpected(environment);
+        const observed = await dependencies.adapter.inspect(expected.name, options);
+        if (observed) {
+            assertInspectionMatches(expected, observed);
+        }
+        return observed;
+    };
+    const reconnect = async (environment, options = {}) => {
+        await dependencies.adapter.reconnect(dependencies.resolveExpected(environment), options);
+        return { ...environment, state: 'ready' };
+    };
+    return {
+        prepare: async (request) => {
+            requireExecutionCapabilities(DOCKER_SANDBOX_PROVIDER, dockerSandboxExecutionEnvironmentObservation, request.requiredCapabilities);
+            if (!request.persistent) {
+                throw new SbxContractFailure('create', 'Docker Sandbox lifecycle requires persistent environments');
+            }
+            const preparation = dependencies.resolvePreparation(request);
+            const sandbox = await dependencies.adapter.create(preparation.createRequest);
+            return {
+                id: preparation.id,
+                provider: DOCKER_SANDBOX_PROVIDER,
+                providerVersion: QUALIFIED_SBX_VERSION,
+                externalId: sandbox.name,
+                target: request.target,
+                state: 'ready',
+            };
+        },
+        validate: async (environment) => {
+            if (!await dependencies.validatePrepared(environment)) {
+                throw new SbxContractFailure('exec', `Sandbox ${environment.externalId ?? environment.id} did not pass validation`);
+            }
+            return { ...environment, state: 'ready' };
+        },
+        inspect,
+        reconnect,
+        stop: async (environment) => dependencies.adapter.stop(dependencies.resolveExpected(environment)),
+        destroy: async (environment) => dependencies.adapter.remove(dependencies.resolveExpected(environment)),
+    };
+};
+//# sourceMappingURL=dockerSandboxExecutionEnvironment.js.map