@openai/agents-extensions 0.8.5 → 0.9.0

package/dist/sandbox/modal/sandbox.mjs

@@ -0,0 +1,1581 @@
+import { UserError } from '@openai/agents-core';
+import { SandboxProviderError, SandboxUnsupportedFeatureError, normalizeSandboxClientCreateArgs, isMount, } from '@openai/agents-core/sandbox';
+import { normalizePosixPath, relativePosixPathWithinRoot, } from '@openai/agents-core/sandbox/internal';
+import { posix as pathPosix } from 'node:path';
+import { assertCoreSnapshotUnsupported, imageOutputFromBytes, RemoteSandboxEditor, assertTarWorkspacePersistence, assertSandboxEntryMetadataSupported, assertSandboxManifestMetadataSupported, MOUNT_MANIFEST_METADATA_SUPPORT, closeRemoteSessionOnManifestError, createRunAsRemoteEditor, decodeNativeSnapshotRef, deserializeRemoteSandboxSessionStateValues, elapsedSeconds, encodeNativeSnapshotRef, formatExecResponse, hydrateRemoteWorkspaceTar, manifestMaterializationOptionsWithRunAs, materializeEnvironment, persistRemoteWorkspaceTar, assertConfiguredExposedPort, getCachedExposedPortEndpoint, recordResolvedExposedPortEndpoint, resolveSandboxAbsolutePath, resolveSandboxRelativePath, resolveSandboxWorkdir, cloneManifestWithoutMountEntries, readRunAsRemoteFile, runAsRemotePathExists, sandboxUserShellCommand, serializeRemoteSandboxSessionState, truncateOutput, validateRemoteSandboxPathForManifest, readOptionalNumber, readOptionalNumberArray, readOptionalString, readString, withProviderError, withSandboxSpan, } from "../shared/index.mjs";
+import { applyLocalSourceManifestEntryToState, applyLocalSourceManifestToState, } from "../shared/localSources.mjs";
+import { buildModalCloudBucketMountConfig, isModalCloudBucketMountEntry, } from "./mounts.mjs";
+const DEFAULT_MODAL_IMAGE_TAG = 'debian:bookworm-slim';
+const DEFAULT_EXEC_YIELD_TIME_MS = 10_000;
+const DEFAULT_WRITE_STDIN_YIELD_TIME_MS = 250;
+const MAX_ACTIVE_PROCESS_OUTPUT_CHARS = 1024 * 1024;
+const COMPLETED_ACTIVE_PROCESS_RETENTION_MS = 60_000;
+export class ModalImageSelector {
+    kind;
+    value;
+    constructor(kind, value) {
+        this.kind = kind;
+        this.value = value;
+    }
+    static fromImage(image) {
+        return new ModalImageSelector('image', image);
+    }
+    static fromId(imageId) {
+        return new ModalImageSelector('id', imageId);
+    }
+    static fromTag(imageTag) {
+        return new ModalImageSelector('tag', imageTag);
+    }
+}
+export class ModalSandboxSelector {
+    kind;
+    value;
+    constructor(kind, value) {
+        this.kind = kind;
+        this.value = value;
+    }
+    static fromSandbox(sandbox) {
+        return new ModalSandboxSelector('sandbox', sandbox);
+    }
+    static fromId(sandboxId) {
+        return new ModalSandboxSelector('id', sandboxId);
+    }
+}
+export class ModalSandboxSession {
+    state;
+    modal;
+    app;
+    cloudBucketMountsProvider;
+    cloudBucketMounts;
+    cloudBucketMountsResolved = false;
+    sandbox;
+    ownsSandbox;
+    closed = false;
+    closePromise;
+    activeProcesses = new Map();
+    remotePathResolver = async (path, options) => await this.resolveRemotePath(path, options);
+    concurrencyLimits;
+    nextProcessId = 1;
+    constructor(args) {
+        this.state = args.state;
+        this.modal = args.modal;
+        this.app = args.app;
+        this.sandbox = args.sandbox;
+        this.ownsSandbox = args.ownsSandbox ?? args.state.ownsSandbox ?? true;
+        this.state.ownsSandbox = this.ownsSandbox;
+        this.cloudBucketMounts = args.cloudBucketMounts;
+        this.cloudBucketMountsProvider = args.cloudBucketMountsProvider;
+        this.concurrencyLimits = args.concurrencyLimits;
+        this.cloudBucketMountsResolved =
+            args.cloudBucketMounts !== undefined || !args.cloudBucketMountsProvider;
+    }
+    createEditor(runAs) {
+        if (runAs) {
+            return createRunAsRemoteEditor({
+                providerName: 'ModalSandboxClient',
+                providerId: 'modal',
+                runAs,
+                resolvePath: this.remotePathResolver,
+                runCommand: this.runAsCommandRunner.bind(this),
+                writer: this.writer(),
+            });
+        }
+        return new RemoteSandboxEditor({
+            resolvePath: this.remotePathResolver,
+            pathExists: async (path) => await this.pathExists(path),
+            readText: async (path) => new TextDecoder().decode(await this.readSandboxFile(path)),
+            writeText: async (path, content) => {
+                await this.writeSandboxFile(path, content);
+            },
+            deletePath: async (path) => {
+                await this.removeSandboxPath(path);
+            },
+        });
+    }
+    supportsPty() {
+        return true;
+    }
+    async execCommand(args) {
+        const start = Date.now();
+        const command = buildShellCommand({
+            ...args,
+            cmd: sandboxUserShellCommand(args.cmd, args.runAs),
+        });
+        const process = await this.sandbox.exec(command, {
+            mode: 'text',
+            workdir: this.resolveWorkdir(args.workdir),
+            env: this.state.environment,
+            pty: args.tty ?? false,
+            stdout: 'pipe',
+            stderr: 'pipe',
+        });
+        const activeProcess = createActiveProcess(process);
+        await waitForProcessOrTimeout(activeProcess, args.yieldTimeMs ?? DEFAULT_EXEC_YIELD_TIME_MS);
+        if (activeProcess.done) {
+            const output = truncateOutput(consumeCommandOutput(activeProcess), args.maxOutputTokens);
+            return formatExecResponse({
+                output: output.text,
+                wallTimeSeconds: elapsedSeconds(start),
+                exitCode: activeProcess.exitCode ?? 1,
+                originalTokenCount: output.originalTokenCount,
+            });
+        }
+        const sessionId = this.nextProcessId++;
+        this.registerActiveProcess(sessionId, activeProcess);
+        const output = truncateOutput(consumeCommandOutput(activeProcess), args.maxOutputTokens);
+        return formatExecResponse({
+            output: output.text,
+            wallTimeSeconds: elapsedSeconds(start),
+            sessionId,
+            originalTokenCount: output.originalTokenCount,
+        });
+    }
+    async writeStdin(args) {
+        const activeProcess = this.activeProcesses.get(args.sessionId);
+        if (!activeProcess) {
+            return formatExecResponse({
+                output: `write_stdin failed: session not found: ${args.sessionId}`,
+                wallTimeSeconds: 0,
+                exitCode: 1,
+            });
+        }
+        const start = Date.now();
+        const chars = args.chars ?? '';
+        if (chars.length > 0) {
+            if (!activeProcess.process.stdin?.writeText) {
+                throw new UserError('Modal sandbox process does not expose stdin for write_stdin().');
+            }
+            await activeProcess.process.stdin.writeText(chars);
+        }
+        await waitForProcessOrTimeout(activeProcess, args.yieldTimeMs ?? DEFAULT_WRITE_STDIN_YIELD_TIME_MS);
+        const output = truncateOutput(consumeCommandOutput(activeProcess), args.maxOutputTokens);
+        if (activeProcess.done) {
+            this.deleteActiveProcess(args.sessionId, activeProcess);
+            return formatExecResponse({
+                output: output.text,
+                wallTimeSeconds: elapsedSeconds(start),
+                exitCode: activeProcess.exitCode ?? 1,
+            });
+        }
+        return formatExecResponse({
+            output: output.text,
+            wallTimeSeconds: elapsedSeconds(start),
+            sessionId: args.sessionId,
+            originalTokenCount: output.originalTokenCount,
+        });
+    }
+    async viewImage(args) {
+        const absolutePath = await this.resolveRemotePath(args.path);
+        const bytes = args.runAs
+            ? await readRunAsRemoteFile({
+                providerName: 'ModalSandboxClient',
+                providerId: 'modal',
+                path: absolutePath,
+                runAs: args.runAs,
+                runCommand: this.runAsCommandRunner.bind(this),
+            })
+            : await this.readSandboxFile(absolutePath);
+        return imageOutputFromBytes(args.path, bytes);
+    }
+    async readFile(args) {
+        const absolutePath = await this.resolveRemotePath(args.path);
+        const bytes = args.runAs
+            ? await readRunAsRemoteFile({
+                providerName: 'ModalSandboxClient',
+                providerId: 'modal',
+                path: absolutePath,
+                runAs: args.runAs,
+                runCommand: this.runAsCommandRunner.bind(this),
+            })
+            : await this.readSandboxFile(absolutePath);
+        if (typeof args.maxBytes === 'number' && bytes.byteLength > args.maxBytes) {
+            return bytes.subarray(0, args.maxBytes);
+        }
+        return bytes;
+    }
+    async pathExists(path, runAs) {
+        const absolutePath = await this.resolveRemotePath(path);
+        if (!runAs) {
+            const process = await this.sandbox.exec(['test', '-e', absolutePath], {
+                mode: 'text',
+                workdir: this.state.manifest.root,
+                stdout: 'ignore',
+                stderr: 'pipe',
+            });
+            return (await process.wait()) === 0;
+        }
+        return await runAsRemotePathExists(absolutePath, runAs, this.runAsCommandRunner.bind(this));
+    }
+    async running() {
+        try {
+            return (await this.sandbox.poll()) === null;
+        }
+        catch {
+            return false;
+        }
+    }
+    async resolveExposedPort(port) {
+        const requestedPort = assertConfiguredExposedPort({
+            providerName: 'ModalSandboxClient',
+            port,
+            configuredPorts: this.state.configuredExposedPorts,
+        });
+        const cached = getCachedExposedPortEndpoint(this.state, requestedPort);
+        if (cached) {
+            return cached;
+        }
+        if (!this.sandbox.tunnels) {
+            throw new SandboxProviderError('ModalSandboxClient exposed port resolution requires Modal sandbox tunnels support.', {
+                provider: 'modal',
+                port: requestedPort,
+            });
+        }
+        let tunnels;
+        try {
+            tunnels = await this.sandbox.tunnels(10_000);
+        }
+        catch (error) {
+            throw new SandboxProviderError(`ModalSandboxClient failed to look up tunnels for exposed port ${requestedPort}.`, {
+                provider: 'modal',
+                port: requestedPort,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const tunnel = tunnels[requestedPort];
+        if (typeof tunnel?.host !== 'string' ||
+            tunnel.host.length === 0 ||
+            typeof tunnel.port !== 'number') {
+            throw new SandboxProviderError(`ModalSandboxClient did not expose port ${requestedPort}.`, {
+                provider: 'modal',
+                port: requestedPort,
+            });
+        }
+        return recordResolvedExposedPortEndpoint(this.state, requestedPort, {
+            host: tunnel.host,
+            port: tunnel.port,
+            tls: true,
+            query: '',
+        });
+    }
+    async materializeEntry(args) {
+        assertSandboxEntryMetadataSupported('ModalSandboxClient', args.path, args.entry, MOUNT_MANIFEST_METADATA_SUPPORT);
+        assertModalLiveEntryMountsUnsupported(args.entry, args.path, this.state.manifest);
+        await applyLocalSourceManifestEntryToState(this.state, args.path, args.entry, 'modal', this.writer(), this.remotePathResolver, this.manifestMaterializationOptions(args.runAs));
+        this.invalidateCloudBucketMounts();
+    }
+    async applyManifest(manifest, runAs) {
+        assertSandboxManifestMetadataSupported('ModalSandboxClient', manifest, MOUNT_MANIFEST_METADATA_SUPPORT);
+        assertModalLiveManifestMountsUnsupported(manifest, this.state.manifest);
+        await applyLocalSourceManifestToState(this.state, manifest, 'modal', this.writer(), this.remotePathResolver, this.manifestMaterializationOptions(runAs));
+        this.invalidateCloudBucketMounts();
+    }
+    async persistWorkspace() {
+        if (this.state.workspacePersistence === 'snapshot_filesystem') {
+            const archive = await this.persistSnapshotFilesystem();
+            if (archive) {
+                return archive;
+            }
+        }
+        else if (this.state.workspacePersistence === 'snapshot_directory') {
+            const archive = await this.persistSnapshotDirectory();
+            if (archive) {
+                return archive;
+            }
+        }
+        else {
+            assertTarWorkspacePersistence('ModalSandboxClient', this.state.workspacePersistence);
+        }
+        return await persistRemoteWorkspaceTar({
+            providerName: 'ModalSandboxClient',
+            manifest: this.state.manifest,
+            io: this.archiveIo(),
+        });
+    }
+    async hydrateWorkspace(data) {
+        const snapshotRef = decodeNativeSnapshotRef(data);
+        if (snapshotRef?.provider === 'modal_snapshot_filesystem') {
+            this.assertExpectedSnapshotPersistence(snapshotRef.workspacePersistence ?? 'snapshot_filesystem', 'snapshot_filesystem');
+            await this.restoreSnapshotFilesystem(snapshotRef.snapshotId);
+            return;
+        }
+        if (snapshotRef?.provider === 'modal_snapshot_directory') {
+            this.assertExpectedSnapshotPersistence(snapshotRef.workspacePersistence ?? 'snapshot_directory', 'snapshot_directory');
+            await this.restoreSnapshotDirectory(snapshotRef.snapshotId);
+            return;
+        }
+        if (this.state.workspacePersistence === 'tar') {
+            assertTarWorkspacePersistence('ModalSandboxClient', this.state.workspacePersistence);
+        }
+        await hydrateRemoteWorkspaceTar({
+            providerName: 'ModalSandboxClient',
+            manifest: this.state.manifest,
+            io: this.archiveIo(),
+            data,
+        });
+    }
+    async persistSnapshotFilesystem() {
+        if (this.nativeSnapshotRequiresTarFallback()) {
+            return undefined;
+        }
+        if (!this.sandbox.snapshotFilesystem) {
+            return undefined;
+        }
+        const snapshotId = snapshotIdFromModalResult(await withProviderError('ModalSandboxClient', 'modal', 'capture snapshot_filesystem', async () => await this.sandbox.snapshotFilesystem(this.state.snapshotFilesystemTimeoutMs), { sandboxId: this.state.sandboxId }));
+        if (!snapshotId) {
+            throw new SandboxProviderError('Modal snapshot_filesystem persistence did not return a snapshot id.', {
+                provider: 'modal',
+                sandboxId: this.state.sandboxId,
+            });
+        }
+        return encodeNativeSnapshotRef({
+            provider: 'modal_snapshot_filesystem',
+            snapshotId,
+            workspacePersistence: 'snapshot_filesystem',
+        });
+    }
+    async persistSnapshotDirectory() {
+        if (this.nativeSnapshotRequiresTarFallback()) {
+            return undefined;
+        }
+        if (!this.sandbox.snapshotDirectory) {
+            return undefined;
+        }
+        const snapshotId = snapshotIdFromModalResult(await withProviderError('ModalSandboxClient', 'modal', 'capture snapshot_directory', async () => await withOptionalTimeoutMs(this.sandbox.snapshotDirectory(this.state.manifest.root), this.state.snapshotFilesystemTimeoutMs, 'Modal snapshot_directory persistence timed out.', async (snapshot) => {
+            await this.deleteSnapshotDirectoryImage(snapshot);
+        }), { sandboxId: this.state.sandboxId }));
+        if (!snapshotId) {
+            throw new SandboxProviderError('Modal snapshot_directory persistence did not return a snapshot id.', {
+                provider: 'modal',
+                sandboxId: this.state.sandboxId,
+            });
+        }
+        return encodeNativeSnapshotRef({
+            provider: 'modal_snapshot_directory',
+            snapshotId,
+            workspacePersistence: 'snapshot_directory',
+        });
+    }
+    nativeSnapshotRequiresTarFallback() {
+        return this.state.manifest.ephemeralPersistencePaths().size > 0;
+    }
+    assertExpectedSnapshotPersistence(actual, expected) {
+        if (actual !== expected || this.state.workspacePersistence !== expected) {
+            throw new SandboxProviderError(`Modal snapshot reference uses ${actual}, but this session expects ${this.state.workspacePersistence}.`, {
+                provider: 'modal',
+                workspacePersistence: this.state.workspacePersistence,
+                snapshotWorkspacePersistence: actual,
+            });
+        }
+    }
+    async restoreSnapshotFilesystem(snapshotId) {
+        const previousSandbox = this.sandbox;
+        const previousSandboxId = this.state.sandboxId;
+        const previousSandboxOwned = this.ownsSandbox;
+        const sandbox = await withProviderError('ModalSandboxClient', 'modal', 'restore snapshot_filesystem', async () => await withOptionalTimeoutMs((async () => {
+            const image = maybeSetModalSandboxCmd(await this.modalImageFromId(snapshotId), this.state.useSleepCmd);
+            return await this.modal.sandboxes.create(this.app, image, await this.sandboxCreateParams());
+        })(), this.state.snapshotFilesystemRestoreTimeoutMs, 'Modal snapshot_filesystem restore timed out.', terminateModalSandboxAfterTimeout), { sandboxId: previousSandboxId, snapshotId });
+        if (previousSandboxOwned) {
+            try {
+                await previousSandbox.terminate();
+            }
+            catch (error) {
+                let replacementTerminateCause;
+                try {
+                    await sandbox.terminate();
+                }
+                catch (replacementTerminateError) {
+                    replacementTerminateCause = errorMessage(replacementTerminateError);
+                }
+                throw new SandboxProviderError('Modal snapshot_filesystem restore created a replacement sandbox, but terminating the previous sandbox failed.', {
+                    provider: 'modal',
+                    sandboxId: previousSandboxId,
+                    replacementSandboxId: sandbox.sandboxId,
+                    cause: errorMessage(error),
+                    ...(replacementTerminateCause ? { replacementTerminateCause } : {}),
+                });
+            }
+        }
+        await this.resetActiveProcesses();
+        this.sandbox = sandbox;
+        this.ownsSandbox = true;
+        this.state.sandboxId = sandbox.sandboxId;
+        this.state.ownsSandbox = true;
+        delete this.state.exposedPorts;
+    }
+    async restoreSnapshotDirectory(snapshotId) {
+        if (!this.sandbox.mountImage) {
+            throw new SandboxProviderError('Modal snapshot_directory restore requires sandbox mountImage(path, image) support.', {
+                provider: 'modal',
+                sandboxId: this.state.sandboxId,
+                snapshotId,
+            });
+        }
+        const sandbox = this.sandbox;
+        const ownsSandbox = this.ownsSandbox;
+        await withProviderError('ModalSandboxClient', 'modal', 'restore snapshot_directory', async () => {
+            if (!ownsSandbox) {
+                const image = await withOptionalTimeoutMs(this.modalImageFromId(snapshotId), this.state.snapshotFilesystemRestoreTimeoutMs, 'Modal snapshot_directory restore timed out.');
+                await sandbox.mountImage(this.state.manifest.root, image);
+                return;
+            }
+            await withOptionalTimeoutMs((async () => {
+                const image = await this.modalImageFromId(snapshotId);
+                await sandbox.mountImage(this.state.manifest.root, image);
+            })(), this.state.snapshotFilesystemRestoreTimeoutMs, 'Modal snapshot_directory restore timed out.', async () => {
+                await terminateModalSandboxAfterTimeout(sandbox);
+            });
+        }, { sandboxId: this.state.sandboxId, snapshotId });
+    }
+    async deleteSnapshotDirectoryImage(snapshot) {
+        const snapshotId = snapshotIdFromModalResult(snapshot);
+        if (!snapshotId || !this.modal.images.delete) {
+            return;
+        }
+        await this.modal.images.delete(snapshotId).catch(() => { });
+    }
+    async modalImageFromId(snapshotId) {
+        return this.modal.images.fromId
+            ? await withProviderError('ModalSandboxClient', 'modal', 'look up image', async () => await this.modal.images.fromId(snapshotId), { imageId: snapshotId })
+            : { imageId: snapshotId };
+    }
+    async sandboxCreateParams() {
+        const cloudBucketMounts = await this.resolveCloudBucketMounts();
+        return {
+            workdir: this.state.manifest.root,
+            env: this.state.environment,
+            ...(typeof this.state.timeoutMs === 'number'
+                ? { timeoutMs: this.state.timeoutMs }
+                : {}),
+            ...(typeof this.state.idleTimeoutMs === 'number'
+                ? { idleTimeoutMs: this.state.idleTimeoutMs }
+                : {}),
+            ...(this.state.gpu ? { gpu: this.state.gpu } : {}),
+            ...(this.state.configuredExposedPorts
+                ? { encryptedPorts: this.state.configuredExposedPorts }
+                : {}),
+            ...(cloudBucketMounts ? { cloudBucketMounts } : {}),
+        };
+    }
+    async resolveCloudBucketMounts() {
+        if (this.cloudBucketMountsResolved) {
+            return this.cloudBucketMounts;
+        }
+        this.cloudBucketMounts = await this.cloudBucketMountsProvider?.();
+        this.cloudBucketMountsResolved = true;
+        return this.cloudBucketMounts;
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        if (this.closePromise) {
+            await this.closePromise;
+            return;
+        }
+        this.closePromise = this.closeOnce();
+        try {
+            await this.closePromise;
+            this.closed = true;
+        }
+        finally {
+            if (!this.closed) {
+                this.closePromise = undefined;
+            }
+        }
+    }
+    async closeOnce() {
+        const processes = [...this.activeProcesses.values()];
+        const activeProcesses = processes.filter((activeProcess) => !activeProcess.done);
+        await Promise.all(activeProcesses.map(async (activeProcess) => {
+            if (activeProcess.process.stdin?.close) {
+                await activeProcess.process.stdin.close().catch(() => { });
+            }
+        }));
+        if (this.ownsSandbox) {
+            await this.sandbox.terminate();
+            await Promise.all(activeProcesses.map(async (activeProcess) => {
+                await activeProcess.donePromise.catch(() => { });
+            }));
+        }
+        else {
+            await Promise.all(activeProcesses.map(async (activeProcess) => {
+                await activeProcess.stopOutputPumps?.().catch(() => { });
+            }));
+        }
+        for (const process of processes) {
+            clearActiveProcessCleanup(process);
+        }
+        this.activeProcesses.clear();
+    }
+    async resetActiveProcesses() {
+        const processes = [...this.activeProcesses.values()];
+        this.activeProcesses.clear();
+        await Promise.all(processes.map(async (activeProcess) => {
+            clearActiveProcessCleanup(activeProcess);
+            if (!activeProcess.done && activeProcess.process.stdin?.close) {
+                await activeProcess.process.stdin.close().catch(() => { });
+            }
+            if (!activeProcess.done) {
+                await activeProcess.stopOutputPumps?.().catch(() => { });
+            }
+        }));
+    }
+    manifestMaterializationOptions(runAs) {
+        return manifestMaterializationOptionsWithRunAs({
+            providerName: 'ModalSandboxClient',
+            providerId: 'modal',
+            runAs,
+            runCommand: this.runAsCommandRunner.bind(this),
+            options: {
+                materializeMount: async (absolutePath, _entry) => {
+                    throwModalLiveMountsUnsupported([absolutePath]);
+                },
+                concurrencyLimits: this.concurrencyLimits,
+            },
+            support: MOUNT_MANIFEST_METADATA_SUPPORT,
+        });
+    }
+    invalidateCloudBucketMounts() {
+        if (!this.cloudBucketMountsProvider) {
+            return;
+        }
+        this.cloudBucketMounts = undefined;
+        this.cloudBucketMountsResolved = false;
+    }
+    async shutdown() {
+        await this.close();
+    }
+    async delete() {
+        await this.close();
+    }
+    registerActiveProcess(sessionId, activeProcess) {
+        this.activeProcesses.set(sessionId, activeProcess);
+        activeProcess.donePromise
+            .finally(() => {
+            activeProcess.cleanupTimer = setTimeout(() => {
+                if (this.activeProcesses.get(sessionId) === activeProcess) {
+                    this.activeProcesses.delete(sessionId);
+                }
+            }, COMPLETED_ACTIVE_PROCESS_RETENTION_MS);
+            unrefTimer(activeProcess.cleanupTimer);
+        })
+            .catch(() => { });
+    }
+    deleteActiveProcess(sessionId, activeProcess) {
+        clearActiveProcessCleanup(activeProcess);
+        if (this.activeProcesses.get(sessionId) === activeProcess) {
+            this.activeProcesses.delete(sessionId);
+        }
+    }
+    resolveAbsolutePath(path) {
+        return resolveSandboxAbsolutePath(this.state.manifest.root, path);
+    }
+    async resolveRemotePath(path, options = {}) {
+        return await validateRemoteSandboxPathForManifest({
+            manifest: this.state.manifest,
+            path,
+            options,
+            runCommand: async (command) => {
+                const process = await this.sandbox.exec(['/bin/sh', '-c', command], {
+                    mode: 'text',
+                    workdir: this.state.manifest.root,
+                    stdout: 'pipe',
+                    stderr: 'pipe',
+                });
+                const [stdout, stderr, exitCode] = await Promise.all([
+                    readStreamText(process.stdout),
+                    readStreamText(process.stderr),
+                    process.wait(),
+                ]);
+                return { status: exitCode, stdout, stderr };
+            },
+        });
+    }
+    resolveWorkdir(path) {
+        return resolveSandboxWorkdir(this.state.manifest.root, path);
+    }
+    async ensureDirectory(path) {
+        await this.runDirectCommand(['mkdir', '-p', '--', path]);
+    }
+    async writeSandboxFile(path, content) {
+        await this.ensureDirectory(pathPosix.dirname(path));
+        const handle = await this.sandbox.open(path, 'w');
+        try {
+            await handle.write(typeof content === 'string'
+                ? new TextEncoder().encode(content)
+                : content);
+            if (handle.flush) {
+                await handle.flush();
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async readSandboxFile(path) {
+        const handle = await this.sandbox.open(path, 'r');
+        try {
+            return Uint8Array.from(await handle.read());
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async removeSandboxPath(path) {
+        await this.runDirectCommand(['rm', '-f', '--', path]);
+    }
+    async runAsCommandRunner(command, options = {}) {
+        const process = await this.sandbox.exec(['/bin/sh', '-lc', sandboxUserShellCommand(command, options.runAs)], {
+            mode: 'text',
+            workdir: this.state.manifest.root,
+            env: this.state.environment,
+            stdout: 'pipe',
+            stderr: 'pipe',
+        });
+        const [stdout, stderr, exitCode] = await Promise.all([
+            readStreamText(process.stdout),
+            readStreamText(process.stderr),
+            process.wait(),
+        ]);
+        return {
+            status: exitCode,
+            stdout,
+            stderr,
+        };
+    }
+    writer() {
+        return {
+            mkdir: async (path) => {
+                await this.ensureDirectory(path);
+            },
+            writeFile: async (path, content) => {
+                await this.writeSandboxFile(path, content);
+            },
+        };
+    }
+    archiveIo() {
+        return {
+            runCommand: async (command) => {
+                const process = await this.sandbox.exec(['/bin/sh', '-c', command], {
+                    mode: 'text',
+                    workdir: this.state.manifest.root,
+                    env: this.state.environment,
+                    stdout: 'pipe',
+                    stderr: 'pipe',
+                });
+                const [stdout, stderr, exitCode] = await Promise.all([
+                    readStreamText(process.stdout),
+                    readStreamText(process.stderr),
+                    process.wait(),
+                ]);
+                return { status: exitCode, stdout, stderr };
+            },
+            readFile: async (path) => await this.readSandboxFile(path),
+            writeFile: async (path, content) => {
+                await this.writeSandboxFile(path, content);
+            },
+            mkdir: async (path) => {
+                await this.ensureDirectory(path);
+            },
+        };
+    }
+    async runDirectCommand(command) {
+        const process = await this.sandbox.exec(command, {
+            mode: 'text',
+            workdir: this.state.manifest.root,
+            stdout: 'ignore',
+            stderr: 'pipe',
+        });
+        const stderr = await readStreamText(process.stderr);
+        const exitCode = await process.wait();
+        if (exitCode !== 0) {
+            throw new UserError(`Modal sandbox command failed (${command.join(' ')}): ${stderr || `exit ${exitCode}`}`);
+        }
+    }
+}
+/**
+ * @see {@link https://modal.com/docs/guide/sandboxes | Sandboxes guide}.
+ * @see {@link https://modal.com/docs/guide/sdk-javascript-go | JavaScript and Go SDK guide}.
+ * @see {@link https://modal.com/docs/reference/modal.Sandbox | Sandbox reference}.
+ */
+export class ModalSandboxClient {
+    backendId = 'modal';
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async create(args, manifestOptions) {
+        const createArgs = normalizeSandboxClientCreateArgs(args, manifestOptions);
+        assertCoreSnapshotUnsupported('ModalSandboxClient', createArgs.snapshot);
+        const manifest = createArgs.manifest;
+        const resolvedOptions = resolveOptions(this.options, createArgs.options);
+        validateOptions(resolvedOptions);
+        const useSleepCmd = resolvedOptions.useSleepCmd ?? true;
+        assertSandboxManifestMetadataSupported('ModalSandboxClient', manifest, MOUNT_MANIFEST_METADATA_SUPPORT);
+        assertModalManifestMountsSupported(manifest, resolvedOptions.nativeCloudBucketSecretName);
+        assertModalReusableSandboxMountsSupported(manifest, resolvedOptions.sandbox);
+        return await withSandboxSpan('sandbox.start', {
+            backend_id: this.backendId,
+        }, async () => {
+            const modalModule = await loadModalModule();
+            const modal = createModalClientFromModule(modalModule, resolvedOptions);
+            const workspacePersistence = resolvedOptions.workspacePersistence ?? 'tar';
+            const app = shouldResolveModalApp({
+                ownsSandbox: !resolvedOptions.sandbox,
+                workspacePersistence,
+            })
+                ? await lookupModalApp({
+                    modal,
+                    appName: resolvedOptions.appName,
+                    environment: resolvedOptions.environment,
+                    createIfMissing: !resolvedOptions.sandbox,
+                })
+                : {};
+            const environment = await materializeEnvironment(manifest, resolvedOptions.env);
+            const imageState = modalImageStateFromOptions(resolvedOptions);
+            let cloudBucketMounts;
+            let sandbox;
+            if (resolvedOptions.sandbox) {
+                sandbox = await withProviderError('ModalSandboxClient', 'modal', 'resolve sandbox selector', async () => await resolveSelectedModalSandbox(modal, resolvedOptions.sandbox));
+            }
+            else {
+                const { image, imageId, imageTag } = await resolveModalImage(modal, resolvedOptions);
+                imageState.imageId = imageId;
+                imageState.imageTag = imageTag;
+                const sandboxImage = maybeSetModalSandboxCmd(image, useSleepCmd);
+                cloudBucketMounts = await modalCloudBucketMountsForManifest({
+                    modalModule,
+                    manifest,
+                    defaultSecretName: resolvedOptions.nativeCloudBucketSecretName,
+                });
+                const createParams = {
+                    workdir: manifest.root,
+                    env: environment,
+                    ...(typeof resolvedOptions.timeoutMs === 'number'
+                        ? { timeoutMs: resolvedOptions.timeoutMs }
+                        : {}),
+                    ...(typeof resolvedOptions.idleTimeoutMs === 'number'
+                        ? { idleTimeoutMs: resolvedOptions.idleTimeoutMs }
+                        : {}),
+                    ...(resolvedOptions.gpu ? { gpu: resolvedOptions.gpu } : {}),
+                    ...(resolvedOptions.exposedPorts
+                        ? { encryptedPorts: resolvedOptions.exposedPorts }
+                        : {}),
+                    ...(cloudBucketMounts ? { cloudBucketMounts } : {}),
+                };
+                sandbox = await withOptionalTimeout(withProviderError('ModalSandboxClient', 'modal', 'create sandbox', async () => await modal.sandboxes.create(app, sandboxImage, createParams), { appName: resolvedOptions.appName }), resolvedOptions.sandboxCreateTimeoutS, 'Modal sandbox creation timed out.', terminateModalSandboxAfterTimeout);
+            }
+            const sessionState = {
+                manifest,
+                sandboxId: sandbox.sandboxId,
+                ownsSandbox: !resolvedOptions.sandbox,
+                appName: resolvedOptions.appName,
+                imageId: imageState.imageId,
+                imageTag: imageState.imageTag,
+                sandboxCreateTimeoutS: resolvedOptions.sandboxCreateTimeoutS,
+                workspacePersistence,
+                snapshotFilesystemTimeoutMs: resolvedOptions.snapshotFilesystemTimeoutMs,
+                snapshotFilesystemRestoreTimeoutMs: resolvedOptions.snapshotFilesystemRestoreTimeoutMs,
+                environment,
+                timeoutMs: resolvedOptions.timeoutMs,
+                idleTimeoutMs: resolvedOptions.idleTimeoutMs,
+                gpu: resolvedOptions.gpu,
+                configuredExposedPorts: resolvedOptions.exposedPorts,
+                modalEnvironment: resolvedOptions.environment,
+                endpoint: resolvedOptions.endpoint,
+                imageBuilderVersion: resolvedOptions.imageBuilderVersion,
+                nativeCloudBucketSecretName: resolvedOptions.nativeCloudBucketSecretName,
+                useSleepCmd,
+            };
+            const session = new ModalSandboxSession({
+                modal,
+                app,
+                sandbox,
+                ownsSandbox: !resolvedOptions.sandbox,
+                state: sessionState,
+                cloudBucketMounts,
+                concurrencyLimits: createArgs.concurrencyLimits,
+                cloudBucketMountsProvider: async () => await modalCloudBucketMountsForManifest({
+                    modalModule,
+                    manifest: sessionState.manifest,
+                    defaultSecretName: resolvedOptions.nativeCloudBucketSecretName,
+                }),
+            });
+            try {
+                await session.applyManifest(cloneManifestWithoutMountEntries(manifest));
+            }
+            catch (error) {
+                if (resolvedOptions.sandbox) {
+                    throw error;
+                }
+                await closeRemoteSessionOnManifestError('Modal', session, error);
+            }
+            return session;
+        });
+    }
+    async serializeSessionState(state) {
+        return serializeRemoteSandboxSessionState(state);
+    }
+    canPersistOwnedSessionState() {
+        return false;
+    }
+    async deserializeSessionState(state) {
+        const baseState = deserializeRemoteSandboxSessionStateValues(state, this.options.env);
+        return {
+            ...state,
+            ...baseState,
+            ownsSandbox: state.ownsSandbox === false ? false : true,
+            appName: readString(state, 'appName'),
+            imageId: readOptionalString(state, 'imageId'),
+            imageTag: readString(state, 'imageTag', DEFAULT_MODAL_IMAGE_TAG),
+            workspacePersistence: state.workspacePersistence ??
+                'tar',
+            snapshotFilesystemTimeoutMs: readOptionalNumber(state, 'snapshotFilesystemTimeoutMs'),
+            snapshotFilesystemRestoreTimeoutMs: readOptionalNumber(state, 'snapshotFilesystemRestoreTimeoutMs'),
+            timeoutMs: readOptionalNumber(state, 'timeoutMs'),
+            idleTimeoutMs: readOptionalNumber(state, 'idleTimeoutMs'),
+            gpu: readOptionalString(state, 'gpu'),
+            configuredExposedPorts: readOptionalNumberArray(state.configuredExposedPorts),
+            modalEnvironment: readOptionalString(state, 'modalEnvironment'),
+            endpoint: readOptionalString(state, 'endpoint'),
+            nativeCloudBucketSecretName: readOptionalString(state, 'nativeCloudBucketSecretName'),
+            imageBuilderVersion: readOptionalString(state, 'imageBuilderVersion'),
+            useSleepCmd: typeof state.useSleepCmd === 'boolean' ? state.useSleepCmd : true,
+        };
+    }
+    async resume(state) {
+        if (!state.sandboxId) {
+            throw new UserError('Modal sandbox resume requires a persisted sandboxId.');
+        }
+        const sandboxId = state.sandboxId;
+        const modalModule = await loadModalModule();
+        const modal = createModalClientFromModule(modalModule, {
+            ...this.options,
+            appName: state.appName,
+            image: state.imageId
+                ? ModalImageSelector.fromId(state.imageId)
+                : undefined,
+            imageTag: state.imageTag,
+            sandboxCreateTimeoutS: state.sandboxCreateTimeoutS,
+            workspacePersistence: state.workspacePersistence,
+            snapshotFilesystemTimeoutMs: state.snapshotFilesystemTimeoutMs,
+            snapshotFilesystemRestoreTimeoutMs: state.snapshotFilesystemRestoreTimeoutMs,
+            timeoutMs: state.timeoutMs,
+            idleTimeoutMs: state.idleTimeoutMs,
+            gpu: state.gpu,
+            exposedPorts: state.configuredExposedPorts,
+            environment: state.modalEnvironment ?? this.options.environment,
+            endpoint: state.endpoint ?? this.options.endpoint,
+            imageBuilderVersion: state.imageBuilderVersion ?? this.options.imageBuilderVersion,
+            useSleepCmd: state.useSleepCmd,
+        });
+        const sandbox = await withProviderError('ModalSandboxClient', 'modal', 'resume sandbox', async () => await modal.sandboxes.fromId(sandboxId), { sandboxId });
+        const ownsSandbox = state.ownsSandbox !== false;
+        const app = shouldResolveModalApp({
+            ownsSandbox,
+            workspacePersistence: state.workspacePersistence,
+        })
+            ? await lookupModalApp({
+                modal,
+                appName: state.appName,
+                environment: state.modalEnvironment,
+                createIfMissing: ownsSandbox,
+            })
+            : {};
+        const exitCode = await withProviderError('ModalSandboxClient', 'modal', 'poll sandbox', async () => await sandbox.poll(), { sandboxId });
+        if (exitCode !== null) {
+            throw new UserError(`Modal sandbox ${state.sandboxId} is no longer running.`);
+        }
+        return new ModalSandboxSession({
+            state,
+            modal,
+            app,
+            sandbox,
+            ownsSandbox,
+            cloudBucketMountsProvider: async () => await modalCloudBucketMountsForManifest({
+                modalModule,
+                manifest: state.manifest,
+                defaultSecretName: state.nativeCloudBucketSecretName ??
+                    this.options.nativeCloudBucketSecretName,
+            }),
+        });
+    }
+}
+async function loadModalModule() {
+    try {
+        return adaptModalModule(await import('modal'));
+    }
+    catch (error) {
+        throw new UserError(`Modal sandbox support requires the optional \`modal\` package. Install it before using Modal-backed sandbox examples. ${error.message}`);
+    }
+}
+async function lookupModalApp(args) {
+    return await withProviderError('ModalSandboxClient', 'modal', 'look up app', async () => await args.modal.apps.fromName(args.appName, {
+        createIfMissing: args.createIfMissing,
+        ...(args.environment ? { environment: args.environment } : {}),
+    }), { appName: args.appName });
+}
+function shouldResolveModalApp(args) {
+    return (args.ownsSandbox || args.workspacePersistence === 'snapshot_filesystem');
+}
+function adaptModalModule(modal) {
+    const secretApi = modal.Secret;
+    const usesClassSecretApi = typeof secretApi === 'function';
+    const cloudBucketMountClass = typeof modal.CloudBucketMount === 'function'
+        ? modal.CloudBucketMount
+        : undefined;
+    return {
+        ModalClient: modal.ModalClient,
+        CloudBucketMount: usesClassSecretApi && cloudBucketMountClass
+            ? adaptClassModalCloudBucketMount(cloudBucketMountClass)
+            : modal.CloudBucketMount,
+        Secret: {
+            fromName: async (name, params) => {
+                if (usesClassSecretApi) {
+                    return await modal.Secret.fromName(name, {
+                        ...(params?.environment ? { environment: params.environment } : {}),
+                    });
+                }
+                if (isModalSecretModule(secretApi)) {
+                    return await secretApi.fromName(name, params);
+                }
+                throw new Error('Missing Secret export from modal.');
+            },
+            fromObject: async (entries, params) => {
+                if (usesClassSecretApi) {
+                    const environment = readOptionalString(params, 'environment');
+                    return await modal.Secret.fromObject(entries, {
+                        ...(environment ? { environment } : {}),
+                    });
+                }
+                if (isModalSecretModule(secretApi)) {
+                    return await secretApi.fromObject(entries, params);
+                }
+                throw new Error('Missing Secret export from modal.');
+            },
+        },
+    };
+}
+function adaptClassModalCloudBucketMount(CloudBucketMount) {
+    return class {
+        mount;
+        constructor(bucketName, params) {
+            const bucketEndpointUrl = readOptionalString(params, 'bucketEndpointUrl');
+            const keyPrefix = readOptionalString(params, 'keyPrefix');
+            this.mount = new CloudBucketMount(bucketName, {
+                ...(bucketEndpointUrl ? { bucketEndpointUrl } : {}),
+                ...(keyPrefix ? { keyPrefix } : {}),
+                ...(typeof params?.readOnly === 'boolean'
+                    ? { readOnly: params.readOnly }
+                    : {}),
+                ...(params?.secret ? { secret: params.secret } : {}),
+            });
+        }
+        toProto(mountPath) {
+            if (!this.mount.toProto) {
+                throw new SandboxProviderError('Modal CloudBucketMount is missing toProto support.', {
+                    provider: 'modal',
+                });
+            }
+            return this.mount.toProto(mountPath);
+        }
+    };
+}
+function isModalSecretModule(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'fromName' in value &&
+        'fromObject' in value);
+}
+function createModalClientFromModule(modalModule, options) {
+    const { ModalClient } = modalModule;
+    const client = new ModalClient({
+        ...(options.tokenId ? { tokenId: options.tokenId } : {}),
+        ...(options.tokenSecret ? { tokenSecret: options.tokenSecret } : {}),
+        ...(options.environment ? { environment: options.environment } : {}),
+        ...(options.endpoint ? { endpoint: options.endpoint } : {}),
+    });
+    if (options.imageBuilderVersion !== undefined && client.imageBuilderVersion) {
+        const originalImageBuilderVersion = client.imageBuilderVersion.bind(client);
+        client.imageBuilderVersion = (version) => originalImageBuilderVersion(version ?? options.imageBuilderVersion);
+    }
+    return client;
+}
+async function resolveModalImage(modal, options) {
+    const selector = modalImageSelectorFromOptions(options);
+    if (selector.kind === 'image') {
+        const image = selector.value;
+        return {
+            image,
+            imageId: modalImageId(image),
+            imageTag: options.imageTag ?? DEFAULT_MODAL_IMAGE_TAG,
+        };
+    }
+    if (selector.kind === 'id') {
+        const imageId = selector.value;
+        const image = modal.images.fromId
+            ? await withProviderError('ModalSandboxClient', 'modal', 'look up image', async () => await modal.images.fromId(imageId), { imageId })
+            : { imageId };
+        return {
+            image,
+            imageId,
+            imageTag: options.imageTag ?? DEFAULT_MODAL_IMAGE_TAG,
+        };
+    }
+    const imageTag = selector.value;
+    const image = await withProviderError('ModalSandboxClient', 'modal', 'resolve image', async () => modal.images.fromRegistry(imageTag), { imageTag });
+    return {
+        image,
+        imageId: modalImageId(image),
+        imageTag,
+    };
+}
+function modalImageStateFromOptions(options) {
+    const selector = modalImageSelectorFromOptions(options);
+    if (selector.kind === 'image') {
+        return {
+            imageId: modalImageId(selector.value),
+            imageTag: options.imageTag ?? DEFAULT_MODAL_IMAGE_TAG,
+        };
+    }
+    if (selector.kind === 'id') {
+        return {
+            imageId: selector.value,
+            imageTag: options.imageTag ?? DEFAULT_MODAL_IMAGE_TAG,
+        };
+    }
+    return {
+        imageTag: selector.value,
+    };
+}
+function modalImageSelectorFromOptions(options) {
+    return (options.image ??
+        ModalImageSelector.fromTag(options.imageTag ?? DEFAULT_MODAL_IMAGE_TAG));
+}
+async function resolveSelectedModalSandbox(modal, selector) {
+    if (selector.kind === 'sandbox') {
+        return selector.value;
+    }
+    return await withProviderError('ModalSandboxClient', 'modal', 'resolve sandbox', async () => await modal.sandboxes.fromId(selector.value), { sandboxId: selector.value });
+}
+function modalImageId(image) {
+    return image.imageId ?? image.objectId;
+}
+function maybeSetModalSandboxCmd(image, useSleepCmd) {
+    if (!useSleepCmd || typeof image.cmd !== 'function') {
+        return image;
+    }
+    return image.cmd(['sleep', 'infinity']);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function modalCloudBucketMountsForManifest(args) {
+    const mountEntries = args.manifest
+        .mountTargets()
+        .filter(({ entry }) => isModalCloudBucketMountEntry(entry));
+    if (mountEntries.length === 0) {
+        return undefined;
+    }
+    if (!args.modalModule.CloudBucketMount) {
+        throw new SandboxProviderError('Modal cloud bucket mounts require modal.CloudBucketMount support.', {
+            provider: 'modal',
+        });
+    }
+    const cloudBucketMounts = {};
+    for (const { entry, mountPath } of mountEntries) {
+        const config = buildModalCloudBucketMountConfig(entry, {
+            secretName: readOptionalString(entry.mountStrategy, 'secretName') ??
+                args.defaultSecretName,
+            secretEnvironmentName: readOptionalString(entry.mountStrategy, 'secretEnvironmentName'),
+        });
+        cloudBucketMounts[mountPath] = new args.modalModule.CloudBucketMount(config.bucketName, {
+            ...(config.bucketEndpointUrl
+                ? { bucketEndpointUrl: config.bucketEndpointUrl }
+                : {}),
+            ...(config.keyPrefix ? { keyPrefix: config.keyPrefix } : {}),
+            ...(typeof config.readOnly === 'boolean'
+                ? { readOnly: config.readOnly }
+                : {}),
+            ...(await modalCloudBucketMountSecret(args.modalModule, config)),
+        });
+    }
+    return cloudBucketMounts;
+}
+async function modalCloudBucketMountSecret(modalModule, config) {
+    if (!config.secretName && !config.credentials) {
+        return {};
+    }
+    const Secret = modalModule.Secret;
+    if (!Secret) {
+        throw new SandboxProviderError('Modal cloud bucket mounts require modal.Secret support when credentials are configured.', {
+            provider: 'modal',
+            bucketName: config.bucketName,
+        });
+    }
+    const secretName = config.secretName;
+    if (secretName) {
+        return {
+            secret: await withProviderError('ModalSandboxClient', 'modal', 'resolve cloud bucket secret', async () => await Secret.fromName(secretName, {
+                ...(config.secretEnvironmentName
+                    ? { environment: config.secretEnvironmentName }
+                    : {}),
+            }), {
+                bucketName: config.bucketName,
+                secretName,
+            }),
+        };
+    }
+    return {
+        secret: await withProviderError('ModalSandboxClient', 'modal', 'create cloud bucket secret', async () => await Secret.fromObject(config.credentials ?? {}), { bucketName: config.bucketName }),
+    };
+}
+function assertModalManifestMountsSupported(manifest, defaultSecretName) {
+    for (const { entry, mountPath } of manifest.mountTargets()) {
+        assertModalMountEntrySupported(entry, mountPath, defaultSecretName);
+    }
+}
+function assertModalMountEntrySupported(entry, mountPath, defaultSecretName) {
+    if (!isModalCloudBucketMountEntry(entry)) {
+        throw new SandboxUnsupportedFeatureError('ModalSandboxClient only supports ModalCloudBucketMountStrategy mount entries.', {
+            provider: 'modal',
+            feature: 'entry.mountStrategy',
+            path: mountPath,
+            mountType: entry.type,
+            strategyType: entry.mountStrategy?.type,
+        });
+    }
+    buildModalCloudBucketMountConfig(entry, {
+        secretName: readOptionalString(entry.mountStrategy, 'secretName') ??
+            defaultSecretName,
+        secretEnvironmentName: readOptionalString(entry.mountStrategy, 'secretEnvironmentName'),
+    });
+}
+function assertModalLiveManifestMountsUnsupported(manifest, currentManifest) {
+    const mountPaths = uniqueStrings([
+        ...manifest.mountTargets().map(({ mountPath }) => mountPath),
+        ...collectExistingModalMountPathsOverlappedByPaths(currentManifest, collectModalManifestEntryPaths(manifest)),
+    ]);
+    if (mountPaths.length === 0) {
+        return;
+    }
+    throwModalLiveMountsUnsupported(mountPaths);
+}
+function assertModalLiveEntryMountsUnsupported(entry, path, currentManifest) {
+    const mountPaths = uniqueStrings([
+        ...collectModalEntryMountPaths(entry, path),
+        ...collectExistingModalMountPathsOverlappedByPaths(currentManifest, collectModalEntryPaths(entry, path, currentManifest.root)),
+    ]);
+    if (mountPaths.length === 0) {
+        return;
+    }
+    throwModalLiveMountsUnsupported(mountPaths);
+}
+function collectModalManifestEntryPaths(manifest) {
+    return [...manifest.iterEntries()].map(({ logicalPath }) => logicalPath);
+}
+function collectModalEntryPaths(entry, path, root) {
+    const logicalPath = resolveSandboxRelativePath(root, path);
+    return collectModalEntryPathsFromRelative(entry, logicalPath);
+}
+function collectModalEntryPathsFromRelative(entry, path) {
+    if (entry.type !== 'dir' || !entry.children) {
+        return [normalizeManifestRelativePath(path)];
+    }
+    const paths = [normalizeManifestRelativePath(path)];
+    for (const [childPath, childEntry] of Object.entries(entry.children)) {
+        paths.push(...collectModalEntryPathsFromRelative(childEntry, pathPosix.join(path, childPath)));
+    }
+    return paths;
+}
+function collectModalEntryMountPaths(entry, path) {
+    if (isMount(entry)) {
+        return [entry.mountPath ?? path];
+    }
+    if (entry.type !== 'dir' || !entry.children) {
+        return [];
+    }
+    const mountPaths = [];
+    for (const [childPath, childEntry] of Object.entries(entry.children)) {
+        mountPaths.push(...collectModalEntryMountPaths(childEntry, pathPosix.join(path, childPath)));
+    }
+    return mountPaths;
+}
+function collectExistingModalMountPathsOverlappedByPaths(currentManifest, paths) {
+    if (paths.length === 0) {
+        return [];
+    }
+    const normalizedPaths = paths.map(normalizeManifestRelativePath);
+    const mountPaths = [];
+    for (const target of currentManifest.mountTargets()) {
+        const mountedPaths = [
+            target.logicalPath,
+            existingMountPathRelativeToManifestRoot(currentManifest, target.mountPath),
+        ].filter((path) => path !== null);
+        if (mountedPaths.some((mountedPath) => normalizedPaths.some((path) => manifestRelativePathsOverlap(path, mountedPath)))) {
+            mountPaths.push(target.mountPath);
+        }
+    }
+    return mountPaths;
+}
+function existingMountPathRelativeToManifestRoot(manifest, mountPath) {
+    return relativePosixPathWithinRoot(normalizePosixPath(manifest.root), normalizePosixPath(mountPath));
+}
+function manifestRelativePathsOverlap(left, right) {
+    const normalizedLeft = normalizeManifestRelativePath(left);
+    const normalizedRight = normalizeManifestRelativePath(right);
+    if (normalizedLeft === '' || normalizedRight === '') {
+        return true;
+    }
+    return (normalizedLeft === normalizedRight ||
+        normalizedLeft.startsWith(`${normalizedRight}/`) ||
+        normalizedRight.startsWith(`${normalizedLeft}/`));
+}
+function normalizeManifestRelativePath(path) {
+    const normalized = normalizePosixPath(path);
+    return normalized === '.' ? '' : normalized;
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function throwModalLiveMountsUnsupported(mountPaths) {
+    throw new SandboxUnsupportedFeatureError('ModalSandboxClient cannot apply mount entries to a running sandbox.', {
+        provider: 'modal',
+        feature: 'manifest.mounts',
+        mountPaths,
+    });
+}
+function assertModalReusableSandboxMountsSupported(manifest, sandbox) {
+    if (!sandbox) {
+        return;
+    }
+    const mountTargets = manifest.mountTargets();
+    if (mountTargets.length === 0) {
+        return;
+    }
+    throw new SandboxUnsupportedFeatureError('ModalSandboxClient cannot apply mount entries when reusing an existing sandbox.', {
+        provider: 'modal',
+        feature: 'manifest.mounts',
+        mountPaths: mountTargets.map(({ mountPath }) => mountPath),
+    });
+}
+function resolveOptions(defaults, overrides) {
+    return {
+        appName: overrides?.appName ?? defaults.appName ?? '',
+        image: overrides?.image ?? defaults.image,
+        sandbox: overrides?.sandbox ?? defaults.sandbox,
+        imageTag: overrides?.imageTag ?? defaults.imageTag,
+        sandboxCreateTimeoutS: overrides?.sandboxCreateTimeoutS ?? defaults.sandboxCreateTimeoutS,
+        workspacePersistence: overrides?.workspacePersistence ?? defaults.workspacePersistence ?? 'tar',
+        snapshotFilesystemTimeoutMs: overrides?.snapshotFilesystemTimeoutMs ??
+            defaults.snapshotFilesystemTimeoutMs,
+        snapshotFilesystemRestoreTimeoutMs: overrides?.snapshotFilesystemRestoreTimeoutMs ??
+            defaults.snapshotFilesystemRestoreTimeoutMs,
+        env: {
+            ...(defaults.env ?? {}),
+            ...(overrides?.env ?? {}),
+        },
+        timeoutMs: overrides?.timeoutMs ?? defaults.timeoutMs,
+        idleTimeoutMs: overrides?.idleTimeoutMs ?? defaults.idleTimeoutMs,
+        gpu: overrides?.gpu ?? defaults.gpu,
+        exposedPorts: overrides?.exposedPorts ?? defaults.exposedPorts,
+        environment: overrides?.environment ?? defaults.environment,
+        endpoint: overrides?.endpoint ?? defaults.endpoint,
+        tokenId: overrides?.tokenId ?? defaults.tokenId,
+        tokenSecret: overrides?.tokenSecret ?? defaults.tokenSecret,
+        imageBuilderVersion: overrides?.imageBuilderVersion ?? defaults.imageBuilderVersion,
+        nativeCloudBucketSecretName: overrides?.nativeCloudBucketSecretName ??
+            defaults.nativeCloudBucketSecretName,
+        useSleepCmd: overrides?.useSleepCmd ?? defaults.useSleepCmd ?? true,
+    };
+}
+function validateOptions(options) {
+    if (!options.appName || options.appName.trim().length === 0) {
+        throw new UserError('ModalSandboxClient requires a non-empty appName.');
+    }
+    const workspacePersistence = options.workspacePersistence ?? 'tar';
+    if (!['tar', 'snapshot_filesystem', 'snapshot_directory'].includes(workspacePersistence)) {
+        throw new SandboxUnsupportedFeatureError('ModalSandboxClient workspacePersistence must be "tar", "snapshot_filesystem", or "snapshot_directory".', {
+            provider: 'modal',
+            feature: 'workspacePersistence',
+        });
+    }
+    if (options.nativeCloudBucketSecretName !== undefined &&
+        options.nativeCloudBucketSecretName.trim() === '') {
+        throw new SandboxUnsupportedFeatureError('Modal nativeCloudBucketSecretName must be a non-empty string.', {
+            provider: 'modal',
+            feature: 'nativeCloudBucketSecretName',
+        });
+    }
+    if (options.image) {
+        validateModalImageSelector(options.image);
+    }
+    if (options.sandbox) {
+        validateModalSandboxSelector(options.sandbox);
+    }
+    for (const [name, value] of [
+        ['sandboxCreateTimeoutS', options.sandboxCreateTimeoutS],
+        ['snapshotFilesystemTimeoutMs', options.snapshotFilesystemTimeoutMs],
+        [
+            'snapshotFilesystemRestoreTimeoutMs',
+            options.snapshotFilesystemRestoreTimeoutMs,
+        ],
+        ['timeoutMs', options.timeoutMs],
+        ['idleTimeoutMs', options.idleTimeoutMs],
+    ]) {
+        if (value !== undefined &&
+            (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)) {
+            throw new UserError(`ModalSandboxClient ${name} must be a positive number.`);
+        }
+    }
+}
+function validateModalImageSelector(selector) {
+    if (selector.kind === 'image') {
+        if (!selector.value || typeof selector.value !== 'object') {
+            throw new UserError('ModalSandboxClient image selector requires a Modal image object.');
+        }
+        return;
+    }
+    if ((selector.kind === 'id' || selector.kind === 'tag') &&
+        (typeof selector.value !== 'string' || selector.value.trim().length === 0)) {
+        throw new UserError('ModalSandboxClient image selector requires a non-empty string value.');
+    }
+}
+function validateModalSandboxSelector(selector) {
+    if (selector.kind === 'sandbox') {
+        if (!selector.value || typeof selector.value !== 'object') {
+            throw new UserError('ModalSandboxClient sandbox selector requires a Modal sandbox object.');
+        }
+        return;
+    }
+    if (selector.kind === 'id' &&
+        (typeof selector.value !== 'string' || selector.value.trim().length === 0)) {
+        throw new UserError('ModalSandboxClient sandbox selector requires a non-empty sandbox id.');
+    }
+}
+function snapshotIdFromModalResult(snapshot) {
+    if (typeof snapshot === 'string') {
+        return snapshot || undefined;
+    }
+    return snapshot.objectId ?? snapshot.imageId ?? snapshot.id;
+}
+function buildShellCommand(args) {
+    const shellPath = args.shell ?? '/bin/sh';
+    const login = args.shell ? (args.login ?? true) : false;
+    const flag = login ? '-lc' : '-c';
+    return [shellPath, flag, args.cmd];
+}
+function createActiveProcess(process) {
+    const activeProcess = {
+        process,
+        stdout: '',
+        stderr: '',
+        droppedStdoutChars: 0,
+        droppedStderrChars: 0,
+        done: false,
+        exitCode: null,
+        donePromise: Promise.resolve(),
+    };
+    const stdoutPump = startTextStreamPump(process.stdout, (chunk) => {
+        appendActiveProcessOutput(activeProcess, chunk, 'stdout');
+    });
+    const stderrPump = startTextStreamPump(process.stderr, (chunk) => {
+        appendActiveProcessOutput(activeProcess, chunk, 'stderr');
+    });
+    activeProcess.stopOutputPumps = async () => {
+        await Promise.allSettled([stdoutPump.cancel(), stderrPump.cancel()]);
+    };
+    activeProcess.donePromise = (async () => {
+        try {
+            activeProcess.exitCode = await process.wait();
+            await Promise.allSettled([stdoutPump.promise, stderrPump.promise]);
+        }
+        catch (error) {
+            activeProcess.waitError = error;
+            await Promise.allSettled([stdoutPump.promise, stderrPump.promise]);
+        }
+        finally {
+            activeProcess.done = true;
+        }
+    })();
+    return activeProcess;
+}
+function startTextStreamPump(stream, onChunk) {
+    const reader = stream.getReader();
+    const promise = (async () => {
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    return;
+                }
+                if (typeof value === 'string') {
+                    onChunk(value);
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    })();
+    return {
+        promise,
+        cancel: async () => {
+            await reader.cancel().catch(() => { });
+            await promise.catch(() => { });
+        },
+    };
+}
+function clearActiveProcessCleanup(activeProcess) {
+    if (activeProcess.cleanupTimer) {
+        clearTimeout(activeProcess.cleanupTimer);
+        activeProcess.cleanupTimer = undefined;
+    }
+}
+function unrefTimer(timer) {
+    const maybeTimer = timer;
+    maybeTimer.unref?.();
+}
+async function pumpTextStream(stream, onChunk) {
+    await startTextStreamPump(stream, onChunk).promise;
+}
+async function readStreamText(stream) {
+    let text = '';
+    await pumpTextStream(stream, (chunk) => {
+        text += chunk;
+    });
+    return text;
+}
+async function waitForProcessOrTimeout(activeProcess, timeoutMs) {
+    let timeout;
+    try {
+        await Promise.race([
+            activeProcess.donePromise,
+            new Promise((resolve) => {
+                timeout = setTimeout(resolve, timeoutMs);
+                unrefTimer(timeout);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+    if (activeProcess.waitError) {
+        await activeProcess.stopOutputPumps?.();
+        throw new SandboxProviderError('ModalSandboxClient failed to wait for process completion.', {
+            provider: 'modal',
+            operation: 'wait process',
+            cause: modalErrorMessage(activeProcess.waitError),
+        });
+    }
+}
+function modalErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function joinCommandOutput(activeProcess) {
+    return [
+        withDroppedOutputPrefix(activeProcess.stdout, activeProcess.droppedStdoutChars),
+        withDroppedOutputPrefix(activeProcess.stderr, activeProcess.droppedStderrChars),
+    ]
+        .filter((value) => value.trim().length > 0)
+        .map((value) => value.trimEnd())
+        .join('\n');
+}
+function consumeCommandOutput(activeProcess) {
+    const output = joinCommandOutput(activeProcess);
+    activeProcess.stdout = '';
+    activeProcess.stderr = '';
+    activeProcess.droppedStdoutChars = 0;
+    activeProcess.droppedStderrChars = 0;
+    return output;
+}
+function appendActiveProcessOutput(activeProcess, chunk, stream) {
+    if (chunk.length === 0) {
+        return;
+    }
+    if (stream === 'stdout') {
+        const stdout = appendBoundedOutput(activeProcess.stdout, activeProcess.droppedStdoutChars, chunk);
+        activeProcess.stdout = stdout.output;
+        activeProcess.droppedStdoutChars = stdout.droppedChars;
+        return;
+    }
+    const stderr = appendBoundedOutput(activeProcess.stderr, activeProcess.droppedStderrChars, chunk);
+    activeProcess.stderr = stderr.output;
+    activeProcess.droppedStderrChars = stderr.droppedChars;
+}
+function appendBoundedOutput(output, droppedChars, chunk) {
+    const nextLength = output.length + chunk.length;
+    if (nextLength <= MAX_ACTIVE_PROCESS_OUTPUT_CHARS) {
+        return {
+            output: output + chunk,
+            droppedChars,
+        };
+    }
+    const nextDroppedChars = droppedChars + nextLength - MAX_ACTIVE_PROCESS_OUTPUT_CHARS;
+    if (chunk.length >= MAX_ACTIVE_PROCESS_OUTPUT_CHARS) {
+        return {
+            output: chunk.slice(-MAX_ACTIVE_PROCESS_OUTPUT_CHARS),
+            droppedChars: nextDroppedChars,
+        };
+    }
+    const existingCharsToKeep = MAX_ACTIVE_PROCESS_OUTPUT_CHARS - chunk.length;
+    return {
+        output: output.slice(-existingCharsToKeep) + chunk,
+        droppedChars: nextDroppedChars,
+    };
+}
+function withDroppedOutputPrefix(output, droppedChars) {
+    if (droppedChars === 0) {
+        return output;
+    }
+    return `[...${droppedChars} characters truncated from process output...]\n${output}`;
+}
+async function withOptionalTimeout(promise, timeoutSeconds, message, onLateResolve) {
+    if (typeof timeoutSeconds !== 'number') {
+        return await promise;
+    }
+    return await withOptionalTimeoutMs(promise, timeoutSeconds * 1000, message, onLateResolve);
+}
+async function withOptionalTimeoutMs(promise, timeoutMs, message, onLateResolve) {
+    if (typeof timeoutMs !== 'number') {
+        return await promise;
+    }
+    let settled = false;
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise.then((value) => {
+                settled = true;
+                return value;
+            }, (error) => {
+                settled = true;
+                throw error;
+            }),
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => {
+                    if (settled) {
+                        return;
+                    }
+                    promise
+                        .then(async (value) => {
+                        await onLateResolve?.(value);
+                    })
+                        .catch(() => { });
+                    reject(new UserError(message));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+async function terminateModalSandboxAfterTimeout(sandbox) {
+    await sandbox.terminate().catch(() => { });
+}
+//# sourceMappingURL=sandbox.mjs.map