@openai/agents-extensions 0.8.5 → 0.9.1

package/dist/sandbox/runloop/sandbox.mjs

@@ -0,0 +1,1346 @@
+import { UserError } from '@openai/agents-core';
+import { SandboxConfigurationError, SandboxProviderError, SandboxUnsupportedFeatureError, normalizeSandboxClientCreateArgs, } from '@openai/agents-core/sandbox';
+import { posix as pathPosix } from 'node:path';
+import { assertCoreSnapshotUnsupported, assertTarWorkspacePersistence, assertResumeRecreateAllowed, assertRunAsUnsupported, assertSandboxManifestMetadataSupported, SANDBOX_MANIFEST_METADATA_SUPPORT, closeRemoteSessionOnManifestError, cloneManifestWithRoot, decodeNativeSnapshotRef, assertShellEnvironmentName, deserializeRemoteSandboxSessionStateValues, encodeNativeSnapshotRef, materializeEnvironment, serializeRemoteSandboxSessionState, shellQuote, isRecord, readOptionalNumber, readOptionalNumberArray, readOptionalRecord, readOptionalString, readOptionalStringRecord, readString, withProviderError, withSandboxSpan, RemoteSandboxSessionBase, } from "../shared/index.mjs";
+import { mountRcloneCloudBucket, rclonePatternFromMountStrategy, unmountRcloneMount, } from "../shared/inContainerMounts.mjs";
+import { isRunloopCloudBucketMountEntry } from "./mounts.mjs";
+export const DEFAULT_RUNLOOP_WORKSPACE_ROOT = '/home/user';
+export const DEFAULT_RUNLOOP_ROOT_WORKSPACE_ROOT = '/root';
+const UNKNOWN_RUNLOOP_EXIT_CODE = 1;
+const DEFAULT_RUNLOOP_TUNNEL_PARAMS = {
+    auth_mode: 'open',
+    http_keep_alive: true,
+    wake_on_http: false,
+};
+export class RunloopPlatformBlueprintsClient {
+    sdk;
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    async list(params = {}) {
+        return await callRunloopPlatformMethod('blueprint.list', this.sdk.blueprint?.list, params);
+    }
+    async listPublic(params = {}) {
+        return await callRunloopPlatformMethod('api.blueprints.listPublic', this.sdk.api?.blueprints?.listPublic, params);
+    }
+    get(blueprintId) {
+        return callRunloopPlatformGetter('blueprint.fromId', this.sdk.blueprint?.fromId, blueprintId);
+    }
+    async logs(blueprintId, params = {}) {
+        return await callRunloopPlatformMethod('api.blueprints.logs', this.sdk.api?.blueprints?.logs, blueprintId, params);
+    }
+    async create(params = {}) {
+        return await callRunloopPlatformMethod('blueprint.create', this.sdk.blueprint?.create, params);
+    }
+    async awaitBuildComplete(blueprintId, params = {}) {
+        return await callRunloopPlatformMethod('api.blueprints.awaitBuildComplete', this.sdk.api?.blueprints?.awaitBuildComplete, blueprintId, params);
+    }
+    async delete(blueprintId, params = {}) {
+        return await callRunloopPlatformMethod('blueprint.delete', bindRunloopMethod(this.get(blueprintId), 'delete'), params);
+    }
+}
+export class RunloopPlatformBenchmarksClient {
+    sdk;
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    async list(params = {}) {
+        return await callRunloopPlatformMethod('benchmark.list', this.sdk.benchmark?.list, params);
+    }
+    async listPublic(params = {}) {
+        return await callRunloopPlatformMethod('api.benchmarks.listPublic', this.sdk.api?.benchmarks?.listPublic, params);
+    }
+    get(benchmarkId) {
+        if (this.sdk.benchmark?.retrieve) {
+            return callRunloopPlatformMethod('benchmark.retrieve', this.sdk.benchmark.retrieve, benchmarkId);
+        }
+        return this.getBenchmarkFacade(benchmarkId);
+    }
+    async create(params = {}) {
+        return await callRunloopPlatformMethod('benchmark.create', this.sdk.benchmark?.create, params);
+    }
+    async update(benchmarkId, params = {}) {
+        if (this.sdk.benchmark?.update) {
+            return await callRunloopPlatformMethod('benchmark.update', this.sdk.benchmark.update, benchmarkId, params);
+        }
+        return await callRunloopPlatformMethod('benchmark.update', bindRunloopMethod(this.getBenchmarkFacade(benchmarkId), 'update'), params);
+    }
+    async definitions(benchmarkId, params = {}) {
+        return await callRunloopPlatformMethod('api.benchmarks.definitions', this.sdk.api?.benchmarks?.definitions, benchmarkId, params);
+    }
+    async startRun(benchmarkId, params = {}) {
+        if (this.sdk.benchmark?.startRun) {
+            return await callRunloopPlatformMethod('benchmark.startRun', this.sdk.benchmark.startRun, {
+                ...params,
+                benchmark_id: benchmarkId,
+            });
+        }
+        return await callRunloopPlatformMethod('benchmark.startRun', bindRunloopMethod(this.getBenchmarkFacade(benchmarkId), 'startRun'), params);
+    }
+    async updateScenarios(benchmarkId, params = {}) {
+        return await callRunloopPlatformMethod('api.benchmarks.updateScenarios', this.sdk.api?.benchmarks?.updateScenarios, benchmarkId, params);
+    }
+    getBenchmarkFacade(benchmarkId) {
+        return callRunloopPlatformGetter('benchmark.fromId', this.sdk.benchmark?.fromId, benchmarkId);
+    }
+}
+export class RunloopPlatformSecretsClient {
+    sdk;
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    async create(params) {
+        return await callRunloopPlatformMethod('secret.create', this.sdk.secret?.create, params);
+    }
+    async list(params = {}) {
+        return await callRunloopPlatformMethod('secret.list', this.sdk.secret
+            ?.list, params);
+    }
+    async get(name, params = {}) {
+        return await callRunloopPlatformMethod('api.secrets.retrieve', this.sdk.api?.secrets?.retrieve, name, params);
+    }
+    async update(params) {
+        return await callRunloopPlatformMethod('secret.update', this.sdk.secret?.update, params.name, { value: params.value });
+    }
+    async delete(name, params = {}) {
+        return await callRunloopPlatformMethod('secret.delete', this.sdk.secret
+            ?.delete, name, params);
+    }
+}
+export class RunloopPlatformNetworkPoliciesClient {
+    sdk;
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    async create(params = {}) {
+        return await callRunloopPlatformMethod('networkPolicy.create', this.sdk.networkPolicy?.create, params);
+    }
+    async list(params = {}) {
+        return await callRunloopPlatformMethod('networkPolicy.list', this.sdk.networkPolicy?.list, params);
+    }
+    get(networkPolicyId) {
+        return callRunloopPlatformGetter('networkPolicy.fromId', this.sdk.networkPolicy?.fromId, networkPolicyId);
+    }
+    async update(networkPolicyId, params = {}) {
+        return await callRunloopPlatformMethod('networkPolicy.update', bindRunloopMethod(this.get(networkPolicyId), 'update'), params);
+    }
+    async delete(networkPolicyId, params = {}) {
+        return await callRunloopPlatformMethod('networkPolicy.delete', bindRunloopMethod(this.get(networkPolicyId), 'delete'), params);
+    }
+}
+export class RunloopPlatformAxonsClient {
+    sdk;
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    async create(params = {}) {
+        return await callRunloopPlatformMethod('axon.create', this.sdk.axon?.create, params);
+    }
+    async list(params = {}) {
+        return await callRunloopPlatformMethod('axon.list', this.sdk.axon?.list, params);
+    }
+    get(axonId) {
+        return callRunloopPlatformGetter('axon.fromId', this.sdk.axon?.fromId, axonId);
+    }
+    async publish(axonId, params = {}) {
+        return await callRunloopPlatformMethod('axon.publish', bindRunloopMethod(this.get(axonId), 'publish'), params);
+    }
+    async querySql(axonId, params = {}) {
+        const axon = this.get(axonId);
+        return await callRunloopPlatformMethod('axon.sql.query', bindRunloopMethod(axon.sql, 'query'), params);
+    }
+    async batchSql(axonId, params = {}) {
+        const axon = this.get(axonId);
+        return await callRunloopPlatformMethod('axon.sql.batch', bindRunloopMethod(axon.sql, 'batch'), params);
+    }
+}
+export class RunloopPlatformClient {
+    sdk;
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    get blueprints() {
+        return new RunloopPlatformBlueprintsClient(this.sdk);
+    }
+    get benchmarks() {
+        return new RunloopPlatformBenchmarksClient(this.sdk);
+    }
+    get secrets() {
+        return new RunloopPlatformSecretsClient(this.sdk);
+    }
+    get networkPolicies() {
+        return new RunloopPlatformNetworkPoliciesClient(this.sdk);
+    }
+    get axons() {
+        return new RunloopPlatformAxonsClient(this.sdk);
+    }
+}
+export class RunloopSandboxSession extends RemoteSandboxSessionBase {
+    sdk;
+    devbox;
+    activeMountPaths = new Set();
+    constructor(args) {
+        super({
+            state: args.state,
+            options: {
+                providerName: 'RunloopSandboxClient',
+                providerId: 'runloop',
+                concurrencyLimits: args.concurrencyLimits,
+            },
+        });
+        this.sdk = args.sdk;
+        this.devbox = args.devbox;
+    }
+    supportsPty() {
+        return false;
+    }
+    exposedPortSource() {
+        return 'tunnel URL';
+    }
+    async resolveRemoteExposedPort(port) {
+        return await this.ensureTunnelUrl(port);
+    }
+    resolveManifestForApply(manifest) {
+        return resolveRunloopManifestRoot(manifest, this.state.userParameters, true);
+    }
+    async beforeApplyManifest(manifest) {
+        await this.ensureManifestRoot(manifest.root);
+    }
+    async persistWorkspace() {
+        const snapshot = await this.persistWorkspaceViaNativeSnapshot();
+        if (snapshot) {
+            return snapshot;
+        }
+        assertTarWorkspacePersistence('RunloopSandboxClient', 'tar');
+        return await this.persistWorkspaceTar();
+    }
+    async hydrateWorkspace(data) {
+        const snapshotRef = decodeNativeSnapshotRef(data);
+        if (snapshotRef?.provider === 'runloop') {
+            await this.replaceDevboxFromSnapshot(snapshotRef.snapshotId);
+            return;
+        }
+        assertTarWorkspacePersistence('RunloopSandboxClient', 'tar');
+        await this.hydrateWorkspaceTar(data);
+    }
+    async close() {
+        if (this.state.pauseOnExit) {
+            await withSandboxSpan('sandbox.stop', {
+                backend_id: 'runloop',
+                devbox_id: this.state.devboxId,
+            }, async () => {
+                await this.devbox.suspend(runloopRequestOptions(this.state.timeouts?.suspendTimeoutMs));
+            });
+            return;
+        }
+        await withSandboxSpan('sandbox.shutdown', {
+            backend_id: 'runloop',
+            devbox_id: this.state.devboxId,
+        }, async () => {
+            await this.unmountActiveMounts();
+            await this.devbox.shutdown(runloopRequestOptions(this.state.timeouts?.cleanupTimeoutMs));
+        });
+    }
+    async shutdown() {
+        await this.close();
+    }
+    async delete() {
+        await withSandboxSpan('sandbox.shutdown', {
+            backend_id: 'runloop',
+            devbox_id: this.state.devboxId,
+        }, async () => {
+            await this.unmountActiveMounts();
+            await this.devbox.shutdown(runloopRequestOptions(this.state.timeouts?.cleanupTimeoutMs));
+        });
+    }
+    async persistWorkspaceViaNativeSnapshot() {
+        if (this.nativeSnapshotRequiresTarFallback()) {
+            return undefined;
+        }
+        if (!this.devbox.snapshotDisk) {
+            return undefined;
+        }
+        let snapshot;
+        try {
+            const snapshotOptions = runloopLongPollOptions(this.state.timeouts?.snapshotTimeoutMs);
+            const snapshotParams = {
+                name: `sandbox-${this.state.devboxId}`,
+                metadata: {
+                    openai_agents_devbox_id: this.state.devboxId,
+                },
+            };
+            snapshot = snapshotOptions
+                ? await this.devbox.snapshotDisk(snapshotParams, snapshotOptions)
+                : await this.devbox.snapshotDisk(snapshotParams);
+        }
+        catch (error) {
+            throw new SandboxProviderError('RunloopSandboxClient failed to create a native disk snapshot.', {
+                provider: 'runloop',
+                devboxId: this.state.devboxId,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (!snapshot.id) {
+            throw new SandboxProviderError('RunloopSandboxClient native disk snapshot did not return a snapshot id.', {
+                provider: 'runloop',
+                devboxId: this.state.devboxId,
+            });
+        }
+        return encodeNativeSnapshotRef({
+            provider: 'runloop',
+            snapshotId: snapshot.id,
+        });
+    }
+    nativeSnapshotRequiresTarFallback() {
+        return this.state.manifest.ephemeralPersistencePaths().size > 0;
+    }
+    async replaceDevboxFromSnapshot(snapshotId) {
+        if (!this.sdk.devbox.createFromSnapshot) {
+            throw new SandboxProviderError('RunloopSandboxClient native snapshot restore requires createFromSnapshot(snapshotId).', {
+                provider: 'runloop',
+                snapshotId,
+            });
+        }
+        const previousDevbox = this.devbox;
+        const previousActiveMountPaths = new Set(this.activeMountPaths);
+        let devbox;
+        try {
+            devbox = await this.sdk.devbox.createFromSnapshot(snapshotId, createRunloopParams(this.state, this.state.environment, {
+                includeBlueprint: false,
+                includeSecrets: false,
+            }), createRunloopOptions(this.state));
+        }
+        catch (error) {
+            throw new SandboxProviderError('RunloopSandboxClient failed to restore a native disk snapshot.', {
+                provider: 'runloop',
+                snapshotId,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const previousDevboxId = this.state.devboxId;
+        this.devbox = devbox;
+        this.state.devboxId = devbox.id;
+        this.activeMountPaths.clear();
+        invalidateRunloopRuntimeCaches(this.state);
+        try {
+            await rematerializeRunloopManifestMounts(this, this.state.manifest);
+        }
+        catch (error) {
+            let replacementCleanupCause;
+            try {
+                await this.unmountActiveMounts();
+            }
+            catch (unmountError) {
+                replacementCleanupCause = errorMessage(unmountError);
+            }
+            try {
+                await devbox.shutdown();
+            }
+            catch (shutdownError) {
+                replacementCleanupCause = replacementCleanupCause
+                    ? `${replacementCleanupCause}; ${errorMessage(shutdownError)}`
+                    : errorMessage(shutdownError);
+            }
+            this.devbox = previousDevbox;
+            this.state.devboxId = previousDevboxId;
+            this.activeMountPaths.clear();
+            for (const mountPath of previousActiveMountPaths) {
+                this.activeMountPaths.add(mountPath);
+            }
+            invalidateRunloopRuntimeCaches(this.state);
+            throw new SandboxProviderError('RunloopSandboxClient native snapshot restore failed while rematerializing mounts.', {
+                provider: 'runloop',
+                devboxId: previousDevboxId,
+                replacementDevboxId: devbox.id,
+                snapshotId,
+                cause: errorMessage(error),
+                ...(replacementCleanupCause ? { replacementCleanupCause } : {}),
+            });
+        }
+        try {
+            await previousDevbox.shutdown();
+        }
+        catch (error) {
+            let replacementShutdownCause;
+            try {
+                await this.unmountActiveMounts();
+            }
+            catch (unmountError) {
+                replacementShutdownCause = errorMessage(unmountError);
+            }
+            try {
+                await devbox.shutdown();
+            }
+            catch (replacementShutdownError) {
+                replacementShutdownCause = replacementShutdownCause
+                    ? `${replacementShutdownCause}; ${errorMessage(replacementShutdownError)}`
+                    : errorMessage(replacementShutdownError);
+            }
+            this.devbox = previousDevbox;
+            this.state.devboxId = previousDevboxId;
+            this.activeMountPaths.clear();
+            for (const mountPath of previousActiveMountPaths) {
+                this.activeMountPaths.add(mountPath);
+            }
+            invalidateRunloopRuntimeCaches(this.state);
+            throw new SandboxProviderError('RunloopSandboxClient native snapshot restore created a replacement devbox, but shutting down the previous devbox failed.', {
+                provider: 'runloop',
+                devboxId: previousDevbox.id,
+                replacementDevboxId: devbox.id,
+                snapshotId,
+                cause: errorMessage(error),
+                ...(replacementShutdownCause ? { replacementShutdownCause } : {}),
+            });
+        }
+    }
+    manifestMetadataSupport() {
+        return SANDBOX_MANIFEST_METADATA_SUPPORT;
+    }
+    manifestMaterializationOptions() {
+        return {
+            materializeMount: this.materializeMountEntry.bind(this),
+        };
+    }
+    assertExecRunAs(_runAs) {
+        void _runAs;
+    }
+    assertFilesystemRunAs(_runAs) {
+        assertRunAsUnsupported('RunloopSandboxClient', _runAs);
+    }
+    async materializeMountEntry(absolutePath, entry) {
+        if (!isRunloopCloudBucketMountEntry(entry)) {
+            throw new SandboxUnsupportedFeatureError('RunloopSandboxClient only supports RunloopCloudBucketMountStrategy mount entries.', {
+                provider: 'runloop',
+                feature: 'entry.mountStrategy',
+                path: absolutePath,
+                mountType: entry.type,
+                strategyType: entry.mountStrategy?.type,
+            });
+        }
+        const mountPath = await this.resolveRemotePath(entry.mountPath ?? absolutePath, { forWrite: true });
+        await mountRcloneCloudBucket({
+            providerName: 'RunloopSandboxClient',
+            providerId: 'runloop',
+            strategyType: 'runloop_cloud_bucket',
+            entry,
+            mountPath,
+            pattern: rclonePatternFromMountStrategy(entry.mountStrategy),
+            runCommand: this.mountCommandRunner(),
+            writeFile: this.writeRemoteFile.bind(this),
+            packageManagers: ['apt'],
+            installRcloneViaScript: true,
+        });
+        this.activeMountPaths.add(mountPath);
+    }
+    async rematerializeManifestMounts(manifest) {
+        for (const { absolutePath, entry, } of manifest.mountTargetsForMaterialization()) {
+            await this.materializeMountEntry(absolutePath, structuredClone(entry));
+        }
+    }
+    async cleanupAfterFailedResume() {
+        await this.unmountActiveMounts().catch(() => { });
+        if (this.state.pauseOnExit) {
+            await this.devbox
+                .suspend(runloopRequestOptions(this.state.timeouts?.suspendTimeoutMs))
+                .catch(() => { });
+            return;
+        }
+        await this.devbox
+            .shutdown(runloopRequestOptions(this.state.timeouts?.cleanupTimeoutMs))
+            .catch(() => { });
+    }
+    async ensureCurrentManifestRoot() {
+        await this.ensureManifestRoot(this.state.manifest.root);
+    }
+    async unmountActiveMounts() {
+        for (const mountPath of [...this.activeMountPaths].reverse()) {
+            await unmountRcloneMount({
+                providerName: 'RunloopSandboxClient',
+                providerId: 'runloop',
+                mountPath,
+                runCommand: this.mountCommandRunner(),
+            }).catch(() => { });
+            this.activeMountPaths.delete(mountPath);
+        }
+    }
+    mountCommandRunner() {
+        return async (command, options = {}) => {
+            const result = await this.execShellWithEnvironment(command, undefined, options.timeoutMs ?? this.state.timeouts?.fastOperationTimeoutMs, mountCommandEnvironment(this.state.environment, options.user, this.state.userParameters), options.user);
+            return {
+                status: runloopExitStatus(result),
+                stdout: await result.stdout(),
+                stderr: await result.stderr(),
+            };
+        };
+    }
+    async ensureManifestRoot(root) {
+        const home = effectiveRunloopHome(this.state.userParameters);
+        const rootParent = root === home ? root : pathPosix.dirname(root);
+        const result = await this.execShellInWorkdir([
+            `home_real=$(cd -- ${shellQuote(home)} && pwd -P)`,
+            `root_ancestor=${shellQuote(rootParent)}`,
+            'while [ ! -e "$root_ancestor" ]; do parent=$(dirname -- "$root_ancestor"); [ "$parent" = "$root_ancestor" ] && break; root_ancestor="$parent"; done',
+            'ancestor_real=$(cd -- "$root_ancestor" && pwd -P)',
+            `printf 'OPENAI_AGENTS_REALPATH_HOME=%s\\nOPENAI_AGENTS_REALPATH_ANCESTOR=%s\\n' "$home_real" "$ancestor_real"`,
+            'case "$ancestor_real" in "$home_real"|"$home_real"/*) ancestor_confined=1 ;; *) ancestor_confined=0 ;; esac',
+            `if [ "$home_real" = / ] || [ "$ancestor_confined" != 1 ]; then printf 'OPENAI_AGENTS_REALPATH_ROOT=%s\\n' ''; exit 0; fi`,
+            `mkdir -p -- ${shellQuote(root)}`,
+            `root_real=$(cd -- ${shellQuote(root)} && pwd -P)`,
+            `printf 'OPENAI_AGENTS_REALPATH_ROOT=%s\\n' "$root_real"`,
+        ].join(' && '), home, this.state.timeouts?.fastOperationTimeoutMs, {});
+        if (!runloopSucceeded(result)) {
+            throw new SandboxProviderError('RunloopSandboxClient failed to prepare the workspace root.', {
+                provider: 'runloop',
+                root,
+                exitCode: runloopExitStatus(result),
+                stderr: await result.stderr(),
+            });
+        }
+        assertRunloopManifestRootRealPath(root, home, await result.stdout());
+    }
+    async execShellWithEnvironment(command, workdir, timeoutMs, environment, user) {
+        return await this.execShellInWorkdir(command, this.resolveWorkdir(workdir), timeoutMs, environment, user);
+    }
+    async execShellInWorkdir(command, workdir, timeoutMs, environment, user) {
+        const shellCommand = buildShellCommand(command, environment, workdir, user, this.state.userParameters);
+        const params = {
+            last_n: '2000',
+        };
+        const options = runloopLongPollOptions(timeoutMs);
+        return options
+            ? await this.devbox.cmd.exec(shellCommand, params, options)
+            : await this.devbox.cmd.exec(shellCommand, params);
+    }
+    async runRemoteCommand(command, options) {
+        const result = await this.execShellInWorkdir(command, options.workdir, options.timeoutMs ?? this.timeoutForCommand(options), remoteCommandEnvironment(this.state.environment, options), options.runAs);
+        return {
+            status: runloopExitStatus(result),
+            stdout: await result.stdout(),
+            stderr: await result.stderr(),
+        };
+    }
+    async mkdirRemote(path) {
+        const result = await this.runRemoteCommand(`mkdir -p -- ${shellQuote(path)}`, {
+            kind: 'manifest',
+            workdir: this.state.manifest.root,
+            timeoutMs: this.state.timeouts?.fastOperationTimeoutMs,
+        });
+        this.assertRemoteCommandSucceeded(result, 'create directory', path);
+    }
+    async readRemoteText(path) {
+        return await this.devbox.file.read({
+            file_path: path,
+        });
+    }
+    async readRemoteFile(path) {
+        const downloadOptions = runloopRequestOptions(this.state.timeouts?.fileDownloadTimeoutMs);
+        const response = downloadOptions
+            ? await this.devbox.file.download({ path }, downloadOptions)
+            : await this.devbox.file.download({ path });
+        if (response.buffer) {
+            return Uint8Array.from(await response.buffer());
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async writeRemoteFile(path, content) {
+        const uploadOptions = runloopRequestOptions(this.state.timeouts?.fileUploadTimeoutMs);
+        const uploadParams = {
+            path,
+            file: new File([typeof content === 'string' ? content : Uint8Array.from(content)], basename(path)),
+        };
+        if (uploadOptions) {
+            await this.devbox.file.upload(uploadParams, uploadOptions);
+        }
+        else {
+            await this.devbox.file.upload(uploadParams);
+        }
+    }
+    async deleteRemotePath(path) {
+        const result = await this.runRemoteCommand(`rm -f -- ${shellQuote(path)}`, {
+            kind: 'manifest',
+            workdir: this.state.manifest.root,
+            timeoutMs: this.state.timeouts?.fastOperationTimeoutMs,
+        });
+        this.assertRemoteCommandSucceeded(result, 'delete path', path);
+    }
+    assertRemoteCommandSucceeded(result, operation, path) {
+        if (result.status === 0) {
+            return;
+        }
+        throw new SandboxProviderError(`RunloopSandboxClient failed to ${operation}.`, {
+            provider: 'runloop',
+            operation,
+            devboxId: this.state.devboxId,
+            path,
+            exitCode: result.status,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+        });
+    }
+    timeoutForCommand(options) {
+        if (options.kind === 'exec') {
+            return this.state.timeouts?.execTimeoutMs;
+        }
+        if (options.kind === 'running') {
+            return this.state.timeouts?.keepAliveTimeoutMs;
+        }
+        if (options.kind === 'archive') {
+            return this.state.timeouts?.snapshotTimeoutMs;
+        }
+        if (options.kind === 'path' || options.kind === 'manifest') {
+            return this.state.timeouts?.fastOperationTimeoutMs;
+        }
+        return undefined;
+    }
+    async ensureTunnelUrl(port) {
+        const existingUrl = await this.getTunnelUrl(port);
+        if (existingUrl) {
+            return existingUrl;
+        }
+        if (!this.devbox.net?.enableTunnel) {
+            throw new SandboxProviderError('RunloopSandboxClient exposed port resolution requires a Runloop tunnel API.', {
+                provider: 'runloop',
+                port,
+            });
+        }
+        try {
+            const tunnelOptions = runloopRequestOptions(this.state.timeouts?.fastOperationTimeoutMs);
+            const tunnelParams = runloopTunnelEnableParams(this.state.tunnel);
+            if (!tunnelParams) {
+                throw new SandboxProviderError(`RunloopSandboxClient cannot enable a tunnel for exposed port ${port} because tunnel is disabled.`, {
+                    provider: 'runloop',
+                    port,
+                });
+            }
+            if (tunnelOptions) {
+                await this.devbox.net.enableTunnel(tunnelParams, tunnelOptions);
+            }
+            else {
+                await this.devbox.net.enableTunnel(tunnelParams);
+            }
+        }
+        catch (error) {
+            throw new SandboxProviderError(`RunloopSandboxClient failed to enable a tunnel for exposed port ${port}.`, {
+                provider: 'runloop',
+                port,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const enabledUrl = await this.getTunnelUrl(port);
+        if (!enabledUrl) {
+            throw new SandboxProviderError(`RunloopSandboxClient did not return a tunnel URL for exposed port ${port}.`, {
+                provider: 'runloop',
+                port,
+            });
+        }
+        return enabledUrl;
+    }
+    async getTunnelUrl(port) {
+        if (!this.devbox.getTunnelUrl) {
+            throw new SandboxProviderError('RunloopSandboxClient exposed port resolution requires getTunnelUrl(port).', {
+                provider: 'runloop',
+                port,
+            });
+        }
+        try {
+            const tunnelOptions = runloopRequestOptions(this.state.timeouts?.fastOperationTimeoutMs);
+            const url = tunnelOptions
+                ? await this.devbox.getTunnelUrl(port, tunnelOptions)
+                : await this.devbox.getTunnelUrl(port);
+            return typeof url === 'string' && url ? url : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * @see {@link https://docs.runloop.ai/docs/devboxes/overview | Devbox overview}.
+ * @see {@link https://docs.runloop.ai/docs/devboxes/start-stop | Devbox lifecycle}.
+ * @see {@link https://runloopai.github.io/api-client-ts/stable/classes/sdk.DevboxOps.html | TypeScript SDK Devbox reference}.
+ */
+export class RunloopSandboxClient {
+    backendId = 'runloop';
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async platform() {
+        return new RunloopPlatformClient(await createRunloopClient(this.options));
+    }
+    async create(args, manifestOptions) {
+        const createArgs = normalizeSandboxClientCreateArgs(args, manifestOptions);
+        assertCoreSnapshotUnsupported('RunloopSandboxClient', createArgs.snapshot);
+        const resolvedOptions = {
+            ...this.options,
+            ...createArgs.options,
+        };
+        const timeouts = resolveRunloopTimeouts(resolvedOptions);
+        const manifest = resolveRunloopManifestRoot(createArgs.manifest, resolvedOptions.userParameters, false);
+        assertSandboxManifestMetadataSupported('RunloopSandboxClient', manifest, SANDBOX_MANIFEST_METADATA_SUPPORT);
+        const sdk = await createRunloopClient(resolvedOptions);
+        return await withSandboxSpan('sandbox.start', {
+            backend_id: this.backendId,
+        }, async () => {
+            const environment = await materializeEnvironment(manifest, resolvedOptions.env);
+            const createParams = {
+                environment_variables: environment,
+            };
+            const createBlueprintId = resolvedOptions.blueprintName
+                ? undefined
+                : resolvedOptions.blueprintId;
+            for (const key of [
+                'blueprintId',
+                'name',
+                'exposedPorts',
+                'tunnel',
+                'gateways',
+                'mcp',
+                'metadata',
+            ]) {
+                const value = key === 'blueprintId' ? createBlueprintId : resolvedOptions[key];
+                if (value !== undefined) {
+                    createParams[toSnakeCase(key)] = value;
+                }
+            }
+            if (resolvedOptions.userParameters ||
+                resolvedOptions.launchParameters) {
+                createParams.launch_parameters = {
+                    ...(resolvedOptions.launchParameters ?? {}),
+                    user_parameters: resolvedOptions.userParameters,
+                };
+            }
+            const createOptions = runloopLongPollOptions(timeouts.createTimeoutMs);
+            const secretRefs = resolvedOptions.secretRefs ??
+                (await upsertRunloopManagedSecrets(sdk, resolvedOptions.managedSecrets, runloopRequestOptions(timeouts.fastOperationTimeoutMs) ??
+                    createOptions));
+            const persistedSecretRefs = Object.keys(secretRefs).length > 0 ? secretRefs : undefined;
+            if (persistedSecretRefs) {
+                createParams.secrets = persistedSecretRefs;
+            }
+            const devbox = await withProviderError('RunloopSandboxClient', 'runloop', 'create devbox', async () => resolvedOptions.blueprintName
+                ? await sdk.devbox.createFromBlueprintName(resolvedOptions.blueprintName, createParams, createOptions)
+                : await sdk.devbox.create(createParams, createOptions), {
+                blueprintName: resolvedOptions.blueprintName,
+                blueprintId: createBlueprintId,
+            });
+            const session = new RunloopSandboxSession({
+                sdk,
+                devbox,
+                concurrencyLimits: createArgs.concurrencyLimits,
+                state: {
+                    manifest,
+                    devboxId: devbox.id,
+                    blueprintName: resolvedOptions.blueprintName,
+                    blueprintId: createBlueprintId,
+                    name: resolvedOptions.name,
+                    launchParameters: resolvedOptions.launchParameters,
+                    configuredExposedPorts: resolvedOptions.exposedPorts,
+                    tunnel: resolvedOptions.tunnel,
+                    gateways: resolvedOptions.gateways,
+                    mcp: resolvedOptions.mcp,
+                    metadata: resolvedOptions.metadata,
+                    secretRefs: persistedSecretRefs,
+                    pauseOnExit: resolvedOptions.pauseOnExit ?? false,
+                    userParameters: resolvedOptions.userParameters,
+                    environment,
+                    baseUrl: resolvedOptions.baseUrl,
+                    createTimeoutMs: timeouts.createTimeoutMs,
+                    timeouts,
+                },
+            });
+            try {
+                await session.applyManifest(manifest);
+            }
+            catch (error) {
+                session.state.pauseOnExit = false;
+                await closeRemoteSessionOnManifestError('Runloop', session, error);
+            }
+            return session;
+        });
+    }
+    async serializeSessionState(state) {
+        const { managedSecrets: _managedSecrets, ...serializableState } = state;
+        return serializeRemoteSandboxSessionState(serializableState);
+    }
+    canPersistOwnedSessionState(state) {
+        return state.pauseOnExit;
+    }
+    async deserializeSessionState(state) {
+        const baseState = deserializeRemoteSandboxSessionStateValues(state, this.options.env);
+        const { managedSecrets: _managedSecrets, ...rest } = state;
+        return {
+            ...rest,
+            ...baseState,
+            devboxId: readString(state, 'devboxId'),
+            blueprintName: readOptionalString(state, 'blueprintName'),
+            blueprintId: readOptionalString(state, 'blueprintId'),
+            name: readOptionalString(state, 'name'),
+            launchParameters: readOptionalRecord(state.launchParameters),
+            configuredExposedPorts: readOptionalNumberArray(state.configuredExposedPorts),
+            tunnel: typeof state.tunnel === 'boolean' || isRecord(state.tunnel)
+                ? state.tunnel
+                : undefined,
+            gateways: readOptionalRecord(state.gateways),
+            mcp: readOptionalRecord(state.mcp),
+            metadata: readOptionalStringRecord(state.metadata),
+            secretRefs: readOptionalStringRecord(state.secretRefs),
+            pauseOnExit: Boolean(state.pauseOnExit),
+            userParameters: typeof state.userParameters === 'object' && state.userParameters
+                ? state.userParameters
+                : undefined,
+            baseUrl: readOptionalString(state, 'baseUrl'),
+            createTimeoutMs: readOptionalNumber(state, 'createTimeoutMs'),
+            timeouts: resolveRunloopTimeouts({
+                createTimeoutMs: readOptionalNumber(state, 'createTimeoutMs'),
+                timeouts: isRecord(state.timeouts)
+                    ? state.timeouts
+                    : undefined,
+            }),
+        };
+    }
+    async resume(state) {
+        const resumeState = {
+            ...state,
+            baseUrl: this.options.baseUrl,
+            launchParameters: this.options.launchParameters,
+            userParameters: this.options.userParameters,
+            manifest: resolveRunloopManifestRoot(state.manifest, this.options.userParameters, true),
+        };
+        const sdk = await createRunloopClient(this.options);
+        try {
+            const devbox = sdk.devbox.fromId(resumeState.devboxId);
+            if (resumeState.pauseOnExit) {
+                await devbox.resume(runloopLongPollOptions(resumeState.timeouts?.resumeTimeoutMs));
+            }
+            invalidateRunloopRuntimeCaches(resumeState);
+            const session = new RunloopSandboxSession({
+                state: resumeState,
+                sdk,
+                devbox,
+            });
+            try {
+                await session.ensureCurrentManifestRoot();
+                await rematerializeRunloopManifestMounts(session, resumeState.manifest);
+            }
+            catch (error) {
+                await session.cleanupAfterFailedResume();
+                throw error;
+            }
+            return session;
+        }
+        catch (error) {
+            assertResumeRecreateAllowed(error, {
+                providerName: 'RunloopSandboxClient',
+                provider: 'runloop',
+                details: { devboxId: resumeState.devboxId },
+            });
+            assertRunloopResumeRecreateSecretRefsTrusted(resumeState, this.options);
+            const recreateOptions = {
+                blueprintName: this.options.blueprintName,
+                blueprintId: this.options.blueprintId,
+                name: resumeState.name,
+                launchParameters: this.options.launchParameters,
+                exposedPorts: resumeState.configuredExposedPorts,
+                tunnel: resumeState.tunnel,
+                gateways: resumeState.gateways,
+                mcp: resumeState.mcp,
+                metadata: resumeState.metadata,
+                managedSecrets: this.options.managedSecrets,
+                pauseOnExit: resumeState.pauseOnExit,
+                userParameters: this.options.userParameters,
+                env: this.options.env,
+                baseUrl: this.options.baseUrl,
+                createTimeoutMs: resumeState.createTimeoutMs,
+                timeouts: resumeState.timeouts,
+            };
+            return await this.create(resumeState.manifest, recreateOptions);
+        }
+    }
+}
+async function createRunloopClient(options) {
+    try {
+        const { RunloopSDK } = await import('@runloop/api-client');
+        return adaptRunloopClient(new RunloopSDK({
+            ...(options.apiKey ? { bearerToken: options.apiKey } : {}),
+            ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
+        }));
+    }
+    catch (error) {
+        throw new UserError(`Runloop sandbox support requires the optional \`@runloop/api-client\` package. Install it before using Runloop-backed sandbox examples. ${error.message}`);
+    }
+}
+function adaptRunloopClient(sdk) {
+    const createFromSnapshot = bindRunloopMethod(sdk.devbox, 'createFromSnapshot');
+    const secretList = bindRunloopMethod(sdk.secret, 'list');
+    const secretDelete = bindRunloopMethod(sdk.secret, 'delete');
+    return {
+        devbox: {
+            create: async (params, options) => adaptRunloopDevbox(await sdk.devbox.create(params, options)),
+            createFromBlueprintName: async (blueprintName, params, options) => adaptRunloopDevbox(await sdk.devbox.createFromBlueprintName(blueprintName, params, options)),
+            ...(createFromSnapshot
+                ? {
+                    createFromSnapshot: async (snapshotId, params, options) => adaptRunloopDevbox((await createFromSnapshot(snapshotId, params, options))),
+                }
+                : {}),
+            fromId: (id) => adaptRunloopDevbox(sdk.devbox.fromId(id)),
+        },
+        secret: {
+            create: async (...args) => {
+                const [params, options] = args;
+                const createParams = params;
+                return args.length > 1
+                    ? await sdk.secret.create(createParams, options)
+                    : await sdk.secret.create(createParams);
+            },
+            update: async (...args) => {
+                const [secret, params, options] = args;
+                const updateParams = params;
+                return args.length > 2
+                    ? await sdk.secret.update(secret, updateParams, options)
+                    : await sdk.secret.update(secret, updateParams);
+            },
+            ...(secretList
+                ? {
+                    list: async (...args) => {
+                        const [params, options] = args;
+                        return args.length > 1
+                            ? await secretList(params, options)
+                            : await secretList(params);
+                    },
+                }
+                : {}),
+            ...(secretDelete
+                ? {
+                    delete: async (...args) => {
+                        const [secret, params, options] = args;
+                        return args.length > 2
+                            ? await secretDelete(secret, params, options)
+                            : await secretDelete(secret, params);
+                    },
+                }
+                : {}),
+        },
+        blueprint: adaptRunloopPlatformResource(sdk.blueprint),
+        benchmark: adaptRunloopBenchmarkResource(sdk),
+        networkPolicy: adaptRunloopPlatformResource(sdk.networkPolicy),
+        axon: adaptRunloopPlatformResource(sdk.axon),
+        api: adaptRunloopApi(sdk),
+    };
+}
+function adaptRunloopDevbox(devbox) {
+    const enableTunnel = bindRunloopMethod(devbox.net, 'enableTunnel');
+    const getTunnelUrl = bindRunloopMethod(devbox, 'getTunnelUrl');
+    const snapshotDisk = bindRunloopMethod(devbox, 'snapshotDisk');
+    return {
+        id: devbox.id,
+        cmd: {
+            exec: async (...args) => {
+                const [command, params, options] = args;
+                if (args.length > 2) {
+                    return await devbox.cmd.exec(command, params, options);
+                }
+                return args.length > 1
+                    ? await devbox.cmd.exec(command, params)
+                    : await devbox.cmd.exec(command);
+            },
+        },
+        file: {
+            read: async (params, options) => await devbox.file.read(params, options),
+            write: async (params, options) => await devbox.file.write({
+                file_path: params.path,
+                contents: params.contents,
+            }, options),
+            download: async (params, options) => await devbox.file.download(params, options),
+            upload: async (params, options) => {
+                const uploadParams = params;
+                return options
+                    ? await devbox.file.upload(uploadParams, options)
+                    : await devbox.file.upload(uploadParams);
+            },
+        },
+        ...(enableTunnel
+            ? {
+                net: {
+                    enableTunnel: async (params, options) => options
+                        ? await enableTunnel(params, options)
+                        : await enableTunnel(params),
+                },
+            }
+            : {}),
+        ...(getTunnelUrl
+            ? {
+                getTunnelUrl: async (port, options) => (options
+                    ? await getTunnelUrl(port, options)
+                    : await getTunnelUrl(port)),
+            }
+            : {}),
+        ...(snapshotDisk
+            ? {
+                snapshotDisk: async (params, options) => (options
+                    ? await snapshotDisk(params, options)
+                    : await snapshotDisk(params)),
+            }
+            : {}),
+        resume: async (options) => await devbox.resume(options),
+        suspend: async (options) => await devbox.suspend(options),
+        shutdown: async (options) => await devbox.shutdown(options),
+    };
+}
+function adaptRunloopPlatformResource(resource) {
+    if (!isRecord(resource)) {
+        return undefined;
+    }
+    const fromId = resource.fromId;
+    return {
+        create: bindRunloopMethod(resource, 'create'),
+        list: bindRunloopMethod(resource, 'list'),
+        fromId: typeof fromId === 'function'
+            ? (id) => fromId.call(resource, id)
+            : undefined,
+    };
+}
+function adaptRunloopBenchmarkResource(sdk) {
+    const apiBenchmarks = sdk.api
+        ?.benchmarks;
+    const apiResource = adaptRunloopApiBenchmarkResource(apiBenchmarks);
+    if (apiResource) {
+        return apiResource;
+    }
+    return adaptRunloopPlatformResource(sdk.benchmark);
+}
+function adaptRunloopApiBenchmarkResource(resource) {
+    if (!isRecord(resource)) {
+        return undefined;
+    }
+    const adapted = {
+        create: bindRunloopMethod(resource, 'create'),
+        list: bindRunloopMethod(resource, 'list'),
+        retrieve: bindRunloopMethod(resource, 'retrieve'),
+        update: bindRunloopMethod(resource, 'update'),
+        startRun: bindRunloopMethod(resource, 'startRun'),
+    };
+    return Object.values(adapted).some((value) => typeof value === 'function')
+        ? adapted
+        : undefined;
+}
+function adaptRunloopApi(sdk) {
+    const apiClient = sdk.api;
+    if (!isRecord(apiClient)) {
+        return {};
+    }
+    const api = {};
+    const blueprintsResource = apiClient.blueprints;
+    const benchmarksResource = apiClient.benchmarks;
+    const secretsResource = apiClient.secrets;
+    const blueprints = runloopApiResource({
+        listPublic: bindRunloopMethod(blueprintsResource, 'listPublic'),
+        logs: bindRunloopMethod(blueprintsResource, 'logs'),
+        awaitBuildComplete: bindRunloopMethod(blueprintsResource, 'awaitBuildComplete'),
+    });
+    if (Object.keys(blueprints).length > 0) {
+        api.blueprints = blueprints;
+    }
+    const benchmarks = runloopApiResource({
+        listPublic: bindRunloopMethod(benchmarksResource, 'listPublic'),
+        definitions: bindRunloopMethod(benchmarksResource, 'definitions'),
+        updateScenarios: bindRunloopMethod(benchmarksResource, 'updateScenarios'),
+    });
+    if (Object.keys(benchmarks).length > 0) {
+        api.benchmarks = benchmarks;
+    }
+    const secrets = runloopApiResource({
+        retrieve: bindRunloopMethod(secretsResource, 'retrieve'),
+    });
+    if (Object.keys(secrets).length > 0) {
+        api.secrets = secrets;
+    }
+    return api;
+}
+function runloopApiResource(methods) {
+    return Object.fromEntries(Object.entries(methods).filter((entry) => typeof entry[1] === 'function'));
+}
+function bindRunloopMethod(target, methodName) {
+    if (!isRecord(target)) {
+        return undefined;
+    }
+    const method = target[methodName];
+    return typeof method === 'function'
+        ? method.bind(target)
+        : undefined;
+}
+async function upsertRunloopManagedSecrets(sdk, managedSecrets, options) {
+    if (!managedSecrets || Object.keys(managedSecrets).length === 0) {
+        return {};
+    }
+    if (!sdk.secret?.create || !sdk.secret.update) {
+        throw new SandboxProviderError('RunloopSandboxClient managedSecrets require the Runloop SDK secret API.', {
+            provider: 'runloop',
+        });
+    }
+    const refs = {};
+    for (const [name, value] of Object.entries(managedSecrets).sort(([left], [right]) => left.localeCompare(right))) {
+        try {
+            await sdk.secret.create({ name, value }, options);
+        }
+        catch (error) {
+            if (!isRunloopConflictError(error)) {
+                throw new SandboxProviderError(`RunloopSandboxClient failed to create managed secret ${name}.`, {
+                    provider: 'runloop',
+                    secretName: name,
+                    cause: formatRunloopSecretErrorCause(error, value),
+                });
+            }
+            try {
+                await sdk.secret.update(name, { value }, options);
+            }
+            catch (updateError) {
+                throw new SandboxProviderError(`RunloopSandboxClient failed to update managed secret ${name}.`, {
+                    provider: 'runloop',
+                    secretName: name,
+                    cause: formatRunloopSecretErrorCause(updateError, value),
+                });
+            }
+        }
+        refs[name] = name;
+    }
+    return refs;
+}
+function isRunloopConflictError(error) {
+    if (!isRecord(error)) {
+        return false;
+    }
+    const status = error.status ?? error.statusCode;
+    if (status === 409 || status === '409') {
+        return true;
+    }
+    const code = error.code;
+    if (code === 409 || code === '409') {
+        return true;
+    }
+    const text = `${String(error.name ?? '')} ${String(error.message ?? '')}`;
+    return /\b(conflict|already exists)\b/iu.test(text);
+}
+function formatRunloopSecretErrorCause(error, secretValue) {
+    const message = error instanceof Error ? error.message : String(error);
+    return secretValue ? message.split(secretValue).join('[redacted]') : message;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function callRunloopPlatformMethod(methodName, method, ...args) {
+    if (!method) {
+        throw new SandboxUnsupportedFeatureError(`Runloop platform method ${methodName} is not available in the installed Runloop SDK.`, {
+            provider: 'runloop',
+            feature: `platform.${methodName}`,
+        });
+    }
+    return await withProviderError('RunloopSandboxClient', 'runloop', `call platform method ${methodName}`, async () => await method(...args));
+}
+function callRunloopPlatformGetter(methodName, method, id) {
+    if (!method) {
+        throw new SandboxUnsupportedFeatureError(`Runloop platform method ${methodName} is not available in the installed Runloop SDK.`, {
+            provider: 'runloop',
+            feature: `platform.${methodName}`,
+        });
+    }
+    try {
+        return method(id);
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            throw error;
+        }
+        throw new SandboxProviderError(`RunloopSandboxClient failed to call platform method ${methodName}.`, {
+            provider: 'runloop',
+            operation: `call platform method ${methodName}`,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function createRunloopParams(state, environment, options = {}) {
+    const createParams = {
+        environment_variables: environment,
+    };
+    const includeBlueprint = options.includeBlueprint ?? true;
+    const includeSecrets = options.includeSecrets ?? true;
+    const values = {
+        blueprintId: includeBlueprint ? state.blueprintId : undefined,
+        name: state.name,
+        exposedPorts: state.configuredExposedPorts,
+        tunnel: state.tunnel,
+        gateways: state.gateways,
+        mcp: state.mcp,
+        metadata: state.metadata,
+        secrets: includeSecrets ? state.secretRefs : undefined,
+    };
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== undefined) {
+            createParams[toSnakeCase(key)] = value;
+        }
+    }
+    if (state.userParameters || state.launchParameters) {
+        createParams.launch_parameters = {
+            ...(state.launchParameters ?? {}),
+            user_parameters: state.userParameters,
+        };
+    }
+    return createParams;
+}
+function resolveRunloopManifestRoot(manifest, userParameters, preserveDefaultRoot) {
+    const effectiveHome = effectiveRunloopHome(userParameters);
+    const resolvedManifest = !preserveDefaultRoot && manifest.root === '/workspace'
+        ? cloneManifestWithRoot(manifest, effectiveHome)
+        : manifest;
+    validateRunloopManifestRoot(resolvedManifest, effectiveHome);
+    return resolvedManifest;
+}
+function effectiveRunloopHome(userParameters) {
+    if (!userParameters) {
+        return DEFAULT_RUNLOOP_WORKSPACE_ROOT;
+    }
+    validateRunloopUsername(userParameters.username);
+    if (userParameters.username === 'root' && userParameters.uid === 0) {
+        return DEFAULT_RUNLOOP_ROOT_WORKSPACE_ROOT;
+    }
+    return `/home/${userParameters.username}`;
+}
+function validateRunloopUsername(username) {
+    if (username.length > 0 &&
+        username !== '.' &&
+        !username.includes('/') &&
+        !username.includes('..') &&
+        !username.includes('\0')) {
+        return;
+    }
+    throw new SandboxConfigurationError('RunloopSandboxClient userParameters.username must be non-empty and must not contain "/", "..", or NUL bytes.', {
+        provider: 'runloop',
+        username,
+    });
+}
+function validateRunloopManifestRoot(manifest, home) {
+    const root = pathPosix.normalize(manifest.root);
+    if (root === home || root.startsWith(`${home}/`)) {
+        return;
+    }
+    throw new SandboxConfigurationError(`RunloopSandboxClient requires manifest.root to be the effective Runloop home (${home}) or a subdirectory of it.`, {
+        provider: 'runloop',
+        root: manifest.root,
+        effectiveHome: home,
+    });
+}
+function assertRunloopManifestRootRealPath(root, home, stdout) {
+    const values = new Map(stdout
+        .trim()
+        .split(/\r?\n/u)
+        .map((line) => line.match(/^(OPENAI_AGENTS_REALPATH_(?:ANCESTOR|HOME|ROOT))=(.*)$/u))
+        .filter((match) => match !== null)
+        .map((match) => [match[1], pathPosix.normalize(match[2] ?? '')]));
+    const realHome = values.get('OPENAI_AGENTS_REALPATH_HOME');
+    const realAncestor = values.get('OPENAI_AGENTS_REALPATH_ANCESTOR');
+    const realRoot = values.get('OPENAI_AGENTS_REALPATH_ROOT');
+    const normalizedHome = pathPosix.normalize(home);
+    const realHomeIsConfined = realHome &&
+        realHome !== '/' &&
+        (realHome === normalizedHome || realHome.startsWith(`${normalizedHome}/`));
+    const realAncestorIsConfined = realHome &&
+        realAncestor &&
+        (realAncestor === realHome || realAncestor.startsWith(`${realHome}/`));
+    const realRootIsConfined = realHome &&
+        realRoot &&
+        (realRoot === realHome || realRoot.startsWith(`${realHome}/`));
+    if (realHomeIsConfined && realAncestorIsConfined && realRootIsConfined) {
+        return;
+    }
+    throw new SandboxConfigurationError(`RunloopSandboxClient requires manifest.root to resolve to the effective Runloop home (${home}) or a subdirectory of it.`, {
+        provider: 'runloop',
+        root,
+        effectiveHome: home,
+        resolvedRoot: realRoot,
+        resolvedHome: realHome,
+        resolvedAncestor: realAncestor,
+    });
+}
+function createRunloopOptions(state) {
+    return runloopLongPollOptions(state.timeouts?.createTimeoutMs ?? state.createTimeoutMs);
+}
+function resolveRunloopTimeouts(options) {
+    return {
+        ...options.timeouts,
+        createTimeoutMs: options.timeouts?.createTimeoutMs ?? options.createTimeoutMs,
+        fastOperationTimeoutMs: options.timeouts?.fastOperationTimeoutMs ?? options.createTimeoutMs,
+    };
+}
+function runloopRequestOptions(timeoutMs) {
+    return typeof timeoutMs === 'number' ? { timeout: timeoutMs } : undefined;
+}
+function runloopLongPollOptions(timeoutMs) {
+    return typeof timeoutMs === 'number'
+        ? { timeout: timeoutMs, longPoll: { timeoutMs } }
+        : undefined;
+}
+function runloopTunnelEnableParams(tunnel) {
+    if (tunnel === false) {
+        return undefined;
+    }
+    if (isRecord(tunnel)) {
+        return {
+            ...DEFAULT_RUNLOOP_TUNNEL_PARAMS,
+            ...tunnel,
+        };
+    }
+    return { ...DEFAULT_RUNLOOP_TUNNEL_PARAMS };
+}
+function runloopExitStatus(result) {
+    return result.exitCode ?? UNKNOWN_RUNLOOP_EXIT_CODE;
+}
+function runloopSucceeded(result) {
+    return result.exitCode === 0;
+}
+function invalidateRunloopRuntimeCaches(state) {
+    delete state.exposedPorts;
+}
+function remoteCommandEnvironment(environment, options) {
+    return options.kind === 'exec' ? environment : {};
+}
+function assertRunloopResumeRecreateSecretRefsTrusted(state, options) {
+    if (!state.secretRefs || Object.keys(state.secretRefs).length === 0) {
+        return;
+    }
+    if (options.managedSecrets &&
+        Object.keys(options.managedSecrets).length > 0) {
+        return;
+    }
+    throw new UserError('RunloopSandboxClient cannot recreate a missing devbox with persisted secretRefs. Configure managedSecrets on the client to recreate secrets from trusted input.');
+}
+async function rematerializeRunloopManifestMounts(session, manifest) {
+    await session.rematerializeManifestMounts(manifest);
+}
+function mountCommandEnvironment(environment, user, userParameters) {
+    const effectiveUser = user ?? effectiveRunloopUsername(userParameters);
+    return effectiveUser === 'root' ? {} : environment;
+}
+function buildShellCommand(command, environment, cwd, user, userParameters) {
+    const exports = Object.entries(environment).map(([key, value]) => {
+        assertShellEnvironmentName(key);
+        return `export ${key}=${shellQuote(value)}`;
+    });
+    const shellCommand = [`cd ${shellQuote(cwd)}`, ...exports, command].join(' && ');
+    return runloopShellCommandForUser(shellCommand, user, userParameters);
+}
+function runloopShellCommandForUser(command, user, userParameters) {
+    if (!user || user === effectiveRunloopUsername(userParameters)) {
+        return command;
+    }
+    return `sudo -n -u ${shellQuote(user)} -- sh -lc ${shellQuote(command)}`;
+}
+function effectiveRunloopUsername(userParameters) {
+    return userParameters?.username ?? 'user';
+}
+function toSnakeCase(value) {
+    return value.replace(/[A-Z]/gu, (match) => `_${match.toLowerCase()}`);
+}
+function basename(path) {
+    return path.split('/').pop() || 'file';
+}
+//# sourceMappingURL=sandbox.mjs.map