@openai/agents-extensions 0.8.5 → 0.9.0

package/dist/sandbox/blaxel/sandbox.mjs

@@ -0,0 +1,1072 @@
+import { UserError } from '@openai/agents-core';
+import { loadEnv, randomUUID } from '@openai/agents-core/_shims';
+import { SandboxProviderError, SandboxUnsupportedFeatureError, normalizeSandboxClientCreateArgs, } from '@openai/agents-core/sandbox';
+import { addPtyWebSocketListener, appendPtyOutput, assertCoreSnapshotUnsupported, assertResumeRecreateAllowed, createPtyProcessEntry, assertSandboxManifestMetadataSupported, SANDBOX_MANIFEST_METADATA_SUPPORT, assertRunAsUnsupported, closeRemoteSessionOnManifestError, assertShellEnvironmentName, deserializeRemoteSandboxSessionStateValues, formatPtyExecUpdate, materializeEnvironment, openPtyWebSocket, parseExposedPortEndpoint, posixDirname, resolveSandboxWorkdir, serializeRemoteSandboxSessionState, shellQuote, shellCommandForPty, toUint8Array, markPtyDone, writePtyStdin, isRecord, readOptionalBoolean, readOptionalNumber, readOptionalRecordArray, readOptionalString, readOptionalStringRecord, readString, withProviderError, withSandboxSpan, PtyProcessRegistry, RemoteSandboxSessionBase, } from "../shared/index.mjs";
+import { isBlaxelCloudBucketMountEntry, isBlaxelDriveMountEntry, mountBlaxelCloudBucket, mountBlaxelDrive, unmountBlaxelDrive, unmountBlaxelFuseMount, } from "./mounts.mjs";
+export const DEFAULT_BLAXEL_WORKSPACE_ROOT = '/workspace';
+const BLAXEL_AUTOGENERATED_NAME_CREATE_ATTEMPTS = 5;
+const BLAXEL_NON_RESUMABLE_SANDBOX_STATUSES = new Set([
+    'DEACTIVATING',
+    'DEACTIVATED',
+    'DELETING',
+    'FAILED',
+    'TERMINATING',
+    'TERMINATED',
+]);
+export class BlaxelSandboxSession extends RemoteSandboxSessionBase {
+    sandbox;
+    apiKey;
+    ownsSandbox;
+    closed = false;
+    ptyProcesses = new PtyProcessRegistry();
+    activeFuseMountPaths = new Set();
+    activeDriveMountPaths = new Set();
+    constructor(args) {
+        super({
+            state: args.state,
+            options: {
+                providerName: 'BlaxelSandboxClient',
+                providerId: 'blaxel',
+                concurrencyLimits: args.concurrencyLimits,
+            },
+        });
+        this.sandbox = args.sandbox;
+        this.apiKey = args.apiKey;
+        this.ownsSandbox = args.ownsSandbox ?? true;
+        this.ensureMountArtifactScope();
+    }
+    supportsPty() {
+        return Boolean(this.state.sandboxUrl && this.apiKey);
+    }
+    async writeStdin(args) {
+        return await writePtyStdin({
+            providerName: 'BlaxelSandboxClient',
+            registry: this.ptyProcesses,
+            sessionId: args.sessionId,
+            chars: args.chars,
+            yieldTimeMs: args.yieldTimeMs,
+            maxOutputTokens: args.maxOutputTokens,
+        });
+    }
+    async execPtyCommand(args) {
+        assertRunAsUnsupported('BlaxelSandboxClient', args.runAs);
+        if (!this.state.sandboxUrl || !this.apiKey) {
+            throw new SandboxUnsupportedFeatureError('BlaxelSandboxClient tty=true requires a sandbox URL and apiKey.', {
+                provider: 'blaxel',
+                feature: 'tty',
+            });
+        }
+        const start = Date.now();
+        const entry = createPtyProcessEntry({ tty: true });
+        const socket = await openPtyWebSocket({
+            url: buildBlaxelPtyWebSocketUrl({
+                sandboxUrl: this.state.sandboxUrl,
+                token: this.apiKey,
+                sessionId: `pty-${Math.random().toString(16).slice(2, 14)}`,
+                cwd: resolveSandboxWorkdir(this.state.manifest.root, args.workdir),
+            }),
+            providerName: 'BlaxelSandboxClient',
+        });
+        const removeMessageListener = addPtyWebSocketListener(socket, 'message', (event) => handleBlaxelPtyMessage(entry, event));
+        const removeCloseListener = addPtyWebSocketListener(socket, 'close', (event) => {
+            markPtyDone(entry, blaxelPtyCloseExitCode(entry, event));
+        });
+        const removeErrorListener = addPtyWebSocketListener(socket, 'error', () => {
+            markPtyDone(entry, 1);
+        });
+        entry.sendInput = async (chars) => {
+            socket.send(JSON.stringify({ type: 'input', data: chars }));
+        };
+        entry.terminate = async () => {
+            removeMessageListener();
+            removeCloseListener();
+            removeErrorListener();
+            socket.close();
+        };
+        let registered = false;
+        try {
+            await entry.sendInput(`${shellCommandForPty({
+                ...args,
+                cmd: buildShellCommand(args.cmd, this.state.environment),
+            })}\n`);
+            const { sessionId, pruned } = this.ptyProcesses.register(entry);
+            registered = true;
+            if (pruned) {
+                await pruned.terminate?.().catch(() => { });
+            }
+            return await formatPtyExecUpdate({
+                registry: this.ptyProcesses,
+                sessionId,
+                entry,
+                startTime: start,
+                yieldTimeMs: args.yieldTimeMs,
+                maxOutputTokens: args.maxOutputTokens,
+            });
+        }
+        finally {
+            if (!registered) {
+                await entry.terminate?.().catch(() => { });
+            }
+        }
+    }
+    allowOnDemandExposedPorts() {
+        return true;
+    }
+    useCachedExposedPortEndpoint(_port) {
+        return this.state.exposedPortPublic !== false;
+    }
+    exposedPortSource() {
+        return 'preview URL';
+    }
+    async resolveRemoteExposedPort(requestedPort) {
+        if (!this.sandbox.previews?.createIfNotExists) {
+            throw new SandboxProviderError('BlaxelSandboxClient exposed port resolution requires the Blaxel previews API.', {
+                provider: 'blaxel',
+                port: requestedPort,
+            });
+        }
+        let preview;
+        try {
+            preview = await this.sandbox.previews.createIfNotExists({
+                metadata: { name: `port-${requestedPort}` },
+                spec: {
+                    port: requestedPort,
+                    public: this.state.exposedPortPublic ?? true,
+                },
+            });
+        }
+        catch (error) {
+            throw new SandboxProviderError(`BlaxelSandboxClient failed to create a preview for exposed port ${requestedPort}.`, {
+                provider: 'blaxel',
+                port: requestedPort,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const url = extractBlaxelPreviewUrl(preview);
+        if (!url) {
+            throw new SandboxProviderError('BlaxelSandboxClient preview did not include a URL.', {
+                provider: 'blaxel',
+                port: requestedPort,
+            });
+        }
+        const query = this.state.exposedPortPublic === false
+            ? await createBlaxelPreviewTokenQuery(preview, this.state.exposedPortUrlTtlS ?? 3600, requestedPort)
+            : undefined;
+        return parseExposedPortEndpoint(url, {
+            providerName: 'BlaxelSandboxClient',
+            source: 'preview URL',
+            query,
+        });
+    }
+    async prepareWorkspaceRoot() {
+        const result = await this.sandbox.process.exec({
+            command: `mkdir -p -- ${shellQuote(this.state.manifest.root)}`,
+            workingDir: '/',
+            waitForCompletion: true,
+            timeout: this.state.timeouts?.fastOperationTimeoutMs,
+        });
+        if ((result.exitCode ?? 1) !== 0) {
+            throw new SandboxProviderError('BlaxelSandboxClient failed to prepare the workspace root.', {
+                provider: 'blaxel',
+                operation: 'prepare workspace root',
+                sandboxName: this.state.sandboxName,
+                root: this.state.manifest.root,
+                stderr: result.stderr ?? '',
+                stdout: result.stdout ?? '',
+            });
+        }
+    }
+    async close() {
+        await this.ptyProcesses.terminateAll();
+        if (this.state.pauseOnExit || this.closed) {
+            return;
+        }
+        await withSandboxSpan('sandbox.shutdown', {
+            backend_id: 'blaxel',
+            sandbox_name: this.state.sandboxName,
+        }, async () => {
+            await this.unmountActiveMounts();
+            if (this.ownsSandbox) {
+                await this.sandbox.delete();
+            }
+        });
+        this.closed = true;
+    }
+    async shutdown() {
+        await this.close();
+    }
+    async delete() {
+        await this.ptyProcesses.terminateAll();
+        if (this.closed) {
+            return;
+        }
+        await withSandboxSpan('sandbox.shutdown', {
+            backend_id: 'blaxel',
+            sandbox_name: this.state.sandboxName,
+        }, async () => {
+            await this.unmountActiveMounts();
+            if (this.ownsSandbox) {
+                await this.sandbox.delete();
+            }
+        });
+        this.closed = true;
+    }
+    async rehydrateActiveMountPathsFromManifest() {
+        for (const { logicalPath, entry, } of this.state.manifest.mountTargetsForMaterialization()) {
+            const mountPath = await this.resolveRemotePath(entry.mountPath ?? logicalPath, { forWrite: true });
+            if (isBlaxelCloudBucketMountEntry(entry)) {
+                this.activeFuseMountPaths.add(mountPath);
+            }
+            else if (isBlaxelDriveMountEntry(entry)) {
+                this.activeDriveMountPaths.add(mountPath);
+            }
+        }
+    }
+    manifestMetadataSupport() {
+        return SANDBOX_MANIFEST_METADATA_SUPPORT;
+    }
+    manifestMaterializationOptions() {
+        return {
+            materializeMount: this.materializeMountEntry.bind(this),
+        };
+    }
+    assertExecRunAs(_runAs) {
+        void _runAs;
+    }
+    assertFilesystemRunAs(_runAs) {
+        void _runAs;
+    }
+    async materializeMountEntry(absolutePath, entry) {
+        const mountPath = await this.resolveRemotePath(entry.mountPath ?? absolutePath, { forWrite: true });
+        if (entry.mountStrategy?.type === 'blaxel_cloud_bucket') {
+            await mountBlaxelCloudBucket({
+                entry,
+                mountPath,
+                artifactScope: this.ensureMountArtifactScope(),
+                runCommand: this.mountCommandRunner(),
+                writeSecretFile: this.writeMountSecretFile.bind(this),
+            });
+            this.activeFuseMountPaths.add(mountPath);
+            return;
+        }
+        if (entry.mountStrategy?.type === 'blaxel_drive') {
+            const config = await mountBlaxelDrive({
+                entry,
+                mountPath,
+                drives: this.sandbox.drives,
+            });
+            this.activeDriveMountPaths.add(config.mountPath);
+            return;
+        }
+        throw new SandboxUnsupportedFeatureError('BlaxelSandboxClient only supports BlaxelCloudBucketMountStrategy and BlaxelDriveMountStrategy mount entries.', {
+            provider: 'blaxel',
+            feature: 'entry.mountStrategy',
+            path: absolutePath,
+            mountType: entry.type,
+            strategyType: entry.mountStrategy?.type,
+        });
+    }
+    async unmountActiveMounts() {
+        for (const mountPath of [...this.activeDriveMountPaths].reverse()) {
+            try {
+                await unmountBlaxelDrive({
+                    mountPath,
+                    drives: this.sandbox.drives,
+                });
+                this.activeDriveMountPaths.delete(mountPath);
+            }
+            catch (error) {
+                throw new SandboxProviderError('BlaxelSandboxClient failed to unmount an active drive mount.', {
+                    provider: 'blaxel',
+                    mountPath,
+                    cause: unknownErrorMessage(error),
+                });
+            }
+        }
+        for (const mountPath of [...this.activeFuseMountPaths].reverse()) {
+            try {
+                await unmountBlaxelFuseMount({
+                    mountPath,
+                    artifactScope: this.ensureMountArtifactScope(),
+                    runCommand: this.mountCommandRunner(),
+                });
+                this.activeFuseMountPaths.delete(mountPath);
+            }
+            catch (error) {
+                throw new SandboxProviderError('BlaxelSandboxClient failed to unmount an active FUSE mount.', {
+                    provider: 'blaxel',
+                    mountPath,
+                    cause: unknownErrorMessage(error),
+                });
+            }
+        }
+    }
+    mountCommandRunner() {
+        return async (command, options = {}) => {
+            const result = await this.sandbox.process.exec({
+                command,
+                workingDir: '/',
+                waitForCompletion: true,
+                timeout: options.timeoutMs ??
+                    this.state.timeouts?.fastOperationTimeoutMs ??
+                    this.state.timeoutMs,
+            });
+            return {
+                status: result.exitCode ?? 1,
+                stdout: result.stdout ?? '',
+                stderr: result.stderr ?? '',
+            };
+        };
+    }
+    async writeMountSecretFile(path, content) {
+        const operation = this.sandbox.fs.write(path, content);
+        await withBlaxelOperationTimeout(operation, this.state.timeouts?.fileUploadTimeoutMs, 'write mount secret', {
+            onTimeout: () => {
+                void operation.then(async () => {
+                    await this.sandbox.fs.rm(path).catch(() => { });
+                }, () => { });
+            },
+        });
+    }
+    async runRemoteCommand(command, options) {
+        const shellCommand = buildShellCommand(command, this.state.environment);
+        const commandForUser = options.runAs
+            ? `sudo -n -u ${shellQuote(options.runAs)} -- sh -lc ${shellQuote(shellCommand)}`
+            : shellCommand;
+        const result = await this.sandbox.process.exec({
+            command: commandForUser,
+            workingDir: options.workdir,
+            waitForCompletion: true,
+            timeout: this.timeoutForCommand(options),
+        });
+        return {
+            status: result.exitCode ?? 1,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+        };
+    }
+    async mkdirRemote(path) {
+        await this.sandbox.fs.mkdir(path);
+    }
+    async readRemoteText(path) {
+        return await withBlaxelOperationTimeout(this.sandbox.fs.read(path), this.state.timeouts?.fileDownloadTimeoutMs, 'read file');
+    }
+    async readRemoteFile(path) {
+        return await toUint8Array(await withBlaxelOperationTimeout(this.sandbox.fs.readBinary(path), this.state.timeouts?.fileDownloadTimeoutMs, 'read binary file'));
+    }
+    async writeRemoteFile(path, content) {
+        const tempPath = remoteWriteTempPath(path);
+        if (typeof content === 'string') {
+            await this.writeRemoteTempFile(tempPath, this.sandbox.fs.write(tempPath, content), 'write file');
+        }
+        else {
+            await this.writeRemoteTempFile(tempPath, this.sandbox.fs.writeBinary(tempPath, content), 'write binary file');
+        }
+        try {
+            const result = await this.sandbox.process.exec({
+                command: `mv -f -- ${shellQuote(tempPath)} ${shellQuote(path)}`,
+                workingDir: '/',
+                waitForCompletion: true,
+                timeout: this.state.timeouts?.fileUploadTimeoutMs,
+            });
+            if ((result.exitCode ?? 1) === 0) {
+                return;
+            }
+            throw new SandboxProviderError('BlaxelSandboxClient failed to commit uploaded file.', {
+                provider: 'blaxel',
+                operation: 'commit uploaded file',
+                path,
+                tempPath,
+                exitCode: result.exitCode ?? 1,
+                stdout: result.stdout ?? '',
+                stderr: result.stderr ?? '',
+            });
+        }
+        catch (error) {
+            await this.sandbox.fs.rm(tempPath).catch(() => { });
+            throw error;
+        }
+    }
+    async writeRemoteTempFile(tempPath, operation, operationName) {
+        await withBlaxelOperationTimeout(operation, this.state.timeouts?.fileUploadTimeoutMs, operationName, {
+            onTimeout: () => {
+                void operation.then(async () => {
+                    await this.sandbox.fs.rm(tempPath).catch(() => { });
+                }, () => { });
+            },
+        });
+    }
+    async deleteRemotePath(path) {
+        await this.sandbox.fs.rm(path);
+    }
+    ensureMountArtifactScope() {
+        this.state.mountArtifactScope ??= randomUUID();
+        return this.state.mountArtifactScope;
+    }
+    timeoutForCommand(options) {
+        if (options.timeoutMs !== undefined) {
+            return options.timeoutMs;
+        }
+        if (options.kind === 'archive') {
+            return this.state.timeouts?.workspaceTarTimeoutMs ?? this.state.timeoutMs;
+        }
+        if (options.kind === 'exec') {
+            return this.state.timeouts?.execTimeoutMs ?? this.state.timeoutMs;
+        }
+        if (options.kind === 'path' || options.kind === 'running') {
+            return this.state.timeouts?.fastOperationTimeoutMs;
+        }
+        return undefined;
+    }
+}
+/**
+ * @see {@link https://docs.blaxel.ai/Sandboxes/Overview | Sandboxes overview}.
+ * @see {@link https://docs.blaxel.ai/Sandboxes/Filesystem | Filesystem operations}.
+ * @see {@link https://docs.blaxel.ai/Sandboxes/Sessions | Client-side sessions}.
+ */
+export class BlaxelSandboxClient {
+    backendId = 'blaxel';
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async create(args, manifestOptions, internalOptions = {}) {
+        const createArgs = normalizeSandboxClientCreateArgs(args, manifestOptions);
+        assertCoreSnapshotUnsupported('BlaxelSandboxClient', createArgs.snapshot);
+        const manifest = createArgs.manifest;
+        const resolvedOptions = {
+            ...this.options,
+            ...createArgs.options,
+        };
+        const timeouts = resolveBlaxelTimeouts(resolvedOptions);
+        assertSandboxManifestMetadataSupported('BlaxelSandboxClient', manifest, SANDBOX_MANIFEST_METADATA_SUPPORT);
+        const SandboxInstance = await loadBlaxelSandboxClass();
+        return await withSandboxSpan('sandbox.start', {
+            backend_id: this.backendId,
+        }, async () => {
+            const sandboxCreateParams = {
+                ...(resolvedOptions.image ? { image: resolvedOptions.image } : {}),
+                ...(typeof resolvedOptions.memory === 'number'
+                    ? { memory: resolvedOptions.memory }
+                    : {}),
+                ...(resolvedOptions.region ? { region: resolvedOptions.region } : {}),
+                ...(resolvedOptions.ports ? { ports: resolvedOptions.ports } : {}),
+                ...(typeof resolvedOptions.exposedPortPublic === 'boolean'
+                    ? { exposedPortPublic: resolvedOptions.exposedPortPublic }
+                    : {}),
+                ...(typeof resolvedOptions.exposedPortUrlTtlS === 'number'
+                    ? { exposedPortUrlTtlS: resolvedOptions.exposedPortUrlTtlS }
+                    : {}),
+                ...(typeof resolvedOptions.timeoutMs === 'number'
+                    ? { timeoutMs: resolvedOptions.timeoutMs }
+                    : {}),
+                ...(typeof timeouts.createTimeoutMs === 'number'
+                    ? { createTimeoutMs: timeouts.createTimeoutMs }
+                    : {}),
+                ...(resolvedOptions.labels ? { labels: resolvedOptions.labels } : {}),
+                ...(resolvedOptions.ttl ? { ttl: resolvedOptions.ttl } : {}),
+            };
+            const { sandbox, ownsSandbox, sandboxName } = await withProviderError('BlaxelSandboxClient', 'blaxel', 'create sandbox', async () => await createBlaxelSandboxWithOwnership({
+                SandboxInstance,
+                sandboxName: resolvedOptions.name,
+                allowExistingNamedSandbox: internalOptions.allowExistingNamedSandbox ?? true,
+                paramsForName: (sandboxName) => ({
+                    name: sandboxName,
+                    ...sandboxCreateParams,
+                }),
+            }), { sandboxName: resolvedOptions.name });
+            let environment;
+            try {
+                environment = await materializeEnvironment(manifest, resolvedOptions.env);
+            }
+            catch (error) {
+                if (ownsSandbox) {
+                    try {
+                        await sandbox.delete();
+                    }
+                    catch (deleteError) {
+                        throw new UserError(`Failed to materialize a Blaxel sandbox environment and delete the sandbox. Environment error: ${unknownErrorMessage(error)} Delete error: ${unknownErrorMessage(deleteError)}`);
+                    }
+                }
+                throw error;
+            }
+            const session = new BlaxelSandboxSession({
+                sandbox,
+                apiKey: resolvedOptions.apiKey ?? loadEnv().BL_API_KEY,
+                ownsSandbox,
+                concurrencyLimits: createArgs.concurrencyLimits,
+                state: {
+                    manifest,
+                    sandboxName,
+                    image: resolvedOptions.image,
+                    memory: resolvedOptions.memory,
+                    region: resolvedOptions.region,
+                    ports: resolvedOptions.ports,
+                    exposedPortPublic: resolvedOptions.exposedPortPublic,
+                    exposedPortUrlTtlS: resolvedOptions.exposedPortUrlTtlS,
+                    timeoutMs: resolvedOptions.timeoutMs,
+                    createTimeoutMs: timeouts.createTimeoutMs,
+                    timeouts,
+                    sandboxUrl: extractBlaxelSandboxUrl(sandbox),
+                    sandboxIdentity: extractBlaxelSandboxIdentity(sandbox),
+                    mountArtifactScope: randomUUID(),
+                    labels: resolvedOptions.labels,
+                    ttl: resolvedOptions.ttl,
+                    pauseOnExit: resolvedOptions.pauseOnExit ?? false,
+                    ownsSandbox,
+                    environment,
+                },
+            });
+            try {
+                await session.prepareWorkspaceRoot();
+                await session.applyManifest(manifest);
+            }
+            catch (error) {
+                session.state.pauseOnExit = false;
+                await closeRemoteSessionOnManifestError('Blaxel', session, error);
+            }
+            return session;
+        });
+    }
+    async serializeSessionState(state) {
+        return serializeRemoteSandboxSessionState(state);
+    }
+    canPersistOwnedSessionState(state) {
+        return state.pauseOnExit && state.ownsSandbox && !!state.sandboxIdentity;
+    }
+    async deserializeSessionState(state) {
+        const baseState = deserializeRemoteSandboxSessionStateValues(state, this.options.env);
+        return {
+            ...state,
+            ...baseState,
+            sandboxName: readString(state, 'sandboxName'),
+            image: readOptionalString(state, 'image'),
+            memory: readOptionalNumber(state, 'memory'),
+            region: readOptionalString(state, 'region'),
+            ports: readOptionalRecordArray(state.ports),
+            exposedPortPublic: readOptionalBoolean(state, 'exposedPortPublic'),
+            exposedPortUrlTtlS: readOptionalNumber(state, 'exposedPortUrlTtlS'),
+            timeoutMs: readOptionalNumber(state, 'timeoutMs'),
+            createTimeoutMs: readOptionalNumber(state, 'createTimeoutMs'),
+            timeouts: resolveBlaxelTimeouts({
+                timeoutMs: readOptionalNumber(state, 'timeoutMs'),
+                createTimeoutMs: readOptionalNumber(state, 'createTimeoutMs'),
+                timeouts: isRecord(state.timeouts)
+                    ? state.timeouts
+                    : undefined,
+            }),
+            sandboxUrl: readOptionalString(state, 'sandboxUrl'),
+            sandboxIdentity: readOptionalString(state, 'sandboxIdentity'),
+            mountArtifactScope: readOptionalString(state, 'mountArtifactScope') ?? randomUUID(),
+            labels: readOptionalStringRecord(state.labels),
+            ttl: readOptionalString(state, 'ttl'),
+            pauseOnExit: Boolean(state.pauseOnExit),
+            ownsSandbox: readOptionalBoolean(state, 'ownsSandbox') ?? true,
+        };
+    }
+    async resume(state) {
+        const SandboxInstance = await loadBlaxelSandboxClass();
+        let sandbox;
+        try {
+            sandbox = await SandboxInstance.get(state.sandboxName);
+        }
+        catch (error) {
+            assertResumeRecreateAllowed(error, {
+                providerName: 'BlaxelSandboxClient',
+                provider: 'blaxel',
+                details: { sandboxName: state.sandboxName },
+            });
+            return await this.recreateFromState(state);
+        }
+        if (isBlaxelSandboxNonResumable(sandbox)) {
+            return await this.recreateFromState(state);
+        }
+        if (state.ownsSandbox) {
+            assertBlaxelSandboxIdentityMatchesState(sandbox, state);
+        }
+        const sandboxUrl = extractBlaxelSandboxUrl(sandbox);
+        if (sandboxUrl) {
+            state.sandboxUrl = sandboxUrl;
+        }
+        const session = new BlaxelSandboxSession({
+            state,
+            sandbox,
+            apiKey: this.options.apiKey ?? loadEnv().BL_API_KEY,
+            ownsSandbox: state.ownsSandbox,
+        });
+        await session.rehydrateActiveMountPathsFromManifest();
+        return session;
+    }
+    async recreateFromState(state) {
+        const session = await this.create(state.manifest, {
+            image: state.image,
+            memory: state.memory,
+            region: state.region,
+            ports: state.ports,
+            exposedPortPublic: state.exposedPortPublic,
+            exposedPortUrlTtlS: state.exposedPortUrlTtlS,
+            timeoutMs: state.timeoutMs,
+            createTimeoutMs: state.createTimeoutMs,
+            timeouts: state.timeouts,
+            apiKey: this.options.apiKey,
+            labels: state.labels,
+            ttl: state.ttl,
+            name: state.sandboxName,
+            pauseOnExit: state.pauseOnExit,
+            env: state.environment,
+        }, {
+            allowExistingNamedSandbox: !state.ownsSandbox,
+        });
+        return session;
+    }
+}
+async function loadBlaxelSandboxClass() {
+    try {
+        const { SandboxInstance } = await import('@blaxel/core');
+        if (!SandboxInstance) {
+            throw new Error('Missing SandboxInstance export from @blaxel/core.');
+        }
+        return adaptBlaxelSandboxClass(SandboxInstance);
+    }
+    catch (error) {
+        throw new UserError(`Blaxel sandbox support requires the optional \`@blaxel/core\` package. Install it before using Blaxel-backed sandbox examples. ${error.message}`);
+    }
+}
+async function createBlaxelSandboxWithOwnership(args) {
+    if (!args.sandboxName) {
+        return await createAutogeneratedBlaxelSandbox(args);
+    }
+    return await createNamedBlaxelSandboxWithOwnership({
+        SandboxInstance: args.SandboxInstance,
+        sandboxName: args.sandboxName,
+        allowExistingNamedSandbox: args.allowExistingNamedSandbox,
+        params: args.paramsForName(args.sandboxName),
+    });
+}
+async function createNamedBlaxelSandboxWithOwnership(args) {
+    try {
+        return {
+            sandbox: await args.SandboxInstance.create(args.params),
+            ownsSandbox: true,
+            sandboxName: args.sandboxName,
+        };
+    }
+    catch (error) {
+        if (!isBlaxelSandboxAlreadyExistsError(error)) {
+            throw error;
+        }
+        if (!args.allowExistingNamedSandbox) {
+            throw new UserError(`Blaxel sandbox ${args.sandboxName} cannot be safely recreated because another sandbox already uses that name.`);
+        }
+    }
+    const existing = await args.SandboxInstance.get(args.sandboxName);
+    if (!isBlaxelSandboxNonResumable(existing)) {
+        return {
+            sandbox: existing,
+            ownsSandbox: false,
+            sandboxName: args.sandboxName,
+        };
+    }
+    try {
+        return {
+            sandbox: await args.SandboxInstance.create(args.params),
+            ownsSandbox: true,
+            sandboxName: args.sandboxName,
+        };
+    }
+    catch (error) {
+        if (!isBlaxelSandboxAlreadyExistsError(error)) {
+            throw error;
+        }
+        if (!args.allowExistingNamedSandbox) {
+            throw new UserError(`Blaxel sandbox ${args.sandboxName} cannot be safely recreated because another sandbox already uses that name.`);
+        }
+        const fallback = await args.SandboxInstance.get(args.sandboxName);
+        assertBlaxelSandboxReusable(fallback, args.sandboxName);
+        return {
+            sandbox: fallback,
+            ownsSandbox: false,
+            sandboxName: args.sandboxName,
+        };
+    }
+}
+async function createAutogeneratedBlaxelSandbox(args) {
+    let lastConflict;
+    for (let attempt = 0; attempt < BLAXEL_AUTOGENERATED_NAME_CREATE_ATTEMPTS; attempt += 1) {
+        const sandboxName = generateBlaxelSandboxName();
+        try {
+            return {
+                sandbox: await args.SandboxInstance.create(args.paramsForName(sandboxName)),
+                ownsSandbox: true,
+                sandboxName,
+            };
+        }
+        catch (error) {
+            if (!isBlaxelSandboxAlreadyExistsError(error)) {
+                throw error;
+            }
+            lastConflict = error;
+        }
+    }
+    throw lastConflict;
+}
+function generateBlaxelSandboxName() {
+    return `openai-agents-${Math.random().toString(16).slice(2, 10)}`;
+}
+function isBlaxelSandboxNonResumable(sandbox) {
+    const status = sandbox.status?.trim().toUpperCase();
+    return status ? BLAXEL_NON_RESUMABLE_SANDBOX_STATUSES.has(status) : false;
+}
+function assertBlaxelSandboxReusable(sandbox, sandboxName) {
+    if (!isBlaxelSandboxNonResumable(sandbox)) {
+        return;
+    }
+    throw new UserError(`Blaxel sandbox ${sandboxName} cannot be safely reused because its status is ${sandbox.status ?? 'unknown'}.`);
+}
+function assertBlaxelSandboxIdentityMatchesState(sandbox, state) {
+    const identity = extractBlaxelSandboxIdentity(sandbox);
+    if (identity && identity === state.sandboxIdentity) {
+        return;
+    }
+    throw new UserError(`Blaxel sandbox ${state.sandboxName} cannot be safely resumed with ownership because its identity could not be verified.`);
+}
+function extractBlaxelSandboxIdentity(sandbox) {
+    const metadata = sandbox.metadata;
+    if (!isRecord(metadata)) {
+        return undefined;
+    }
+    const name = readMetadataString(metadata, 'name');
+    const createdAt = readMetadataString(metadata, 'createdAt');
+    if (!name || !createdAt) {
+        return undefined;
+    }
+    return JSON.stringify({
+        name,
+        createdAt,
+        workspace: readMetadataString(metadata, 'workspace') ?? null,
+        createdBy: readMetadataString(metadata, 'createdBy') ?? null,
+    });
+}
+function readMetadataString(metadata, key) {
+    const value = metadata[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function isBlaxelSandboxAlreadyExistsError(error) {
+    if (isRecord(error)) {
+        if (isConflictValue(error.code)) {
+            return true;
+        }
+        const response = error.response;
+        if (isRecord(response) && isConflictValue(response.status)) {
+            return true;
+        }
+    }
+    return /\b(409|already exists|SANDBOX_ALREADY_EXISTS)\b/iu.test(unknownErrorMessage(error));
+}
+function isConflictValue(value) {
+    if (value === 409 || value === '409') {
+        return true;
+    }
+    return (typeof value === 'string' &&
+        value.trim().toUpperCase() === 'SANDBOX_ALREADY_EXISTS');
+}
+function adaptBlaxelSandboxClass(SandboxInstance) {
+    return {
+        create: async (params) => adaptBlaxelSandbox(await SandboxInstance.create(params)),
+        get: async (name) => adaptBlaxelSandbox(await SandboxInstance.get(name)),
+    };
+}
+function adaptBlaxelSandbox(sandbox) {
+    const sandboxUrl = extractBlaxelSandboxUrl(sandbox);
+    const previews = adaptBlaxelPreviewApi(sandbox.previews);
+    return {
+        metadata: sandbox.metadata,
+        url: sandboxUrl,
+        status: typeof sandbox.status === 'string' ? sandbox.status : undefined,
+        ...(sandboxUrl ? { sandbox: { metadata: { url: sandboxUrl } } } : {}),
+        process: {
+            exec: async (params) => await sandbox.process.exec(params),
+        },
+        fs: {
+            mkdir: async (path) => {
+                await sandbox.fs.mkdir(path);
+            },
+            write: async (path, content) => {
+                await sandbox.fs.write(path, content);
+            },
+            writeBinary: async (path, content) => {
+                await sandbox.fs.writeBinary(path, content);
+            },
+            read: async (path) => await sandbox.fs.read(path),
+            readBinary: async (path) => await sandbox.fs.readBinary(path),
+            rm: async (path, recursive) => {
+                await sandbox.fs.rm(path, recursive);
+            },
+        },
+        ...(previews ? { previews } : {}),
+        drives: adaptBlaxelDriveApi(sandbox.drives),
+        delete: async () => {
+            await sandbox.delete();
+        },
+    };
+}
+function adaptBlaxelPreviewApi(previews) {
+    if (!isRecord(previews)) {
+        return undefined;
+    }
+    const createIfNotExists = previews.createIfNotExists;
+    if (typeof createIfNotExists !== 'function') {
+        return undefined;
+    }
+    return {
+        createIfNotExists: async (params) => await createIfNotExists.call(previews, params),
+    };
+}
+function adaptBlaxelDriveApi(drives) {
+    if (!isRecord(drives)) {
+        return undefined;
+    }
+    const mount = drives.mount;
+    if (typeof mount !== 'function') {
+        return undefined;
+    }
+    const unmount = drives.unmount;
+    if (!('list' in drives)) {
+        return {
+            mount: async (driveName, mountPath, drivePath, readOnly) => await mount.call(drives, driveName, mountPath, drivePath, readOnly),
+            unmount: async (mountPath) => typeof unmount === 'function'
+                ? await unmount.call(drives, mountPath)
+                : undefined,
+        };
+    }
+    const sdkDrives = drives;
+    return {
+        mount: async (driveName, mountPath, drivePath, readOnly) => await mount.call(sdkDrives, {
+            driveName,
+            mountPath,
+            ...(drivePath ? { drivePath } : {}),
+            readOnly,
+        }),
+        unmount: async (mountPath) => typeof unmount === 'function'
+            ? await unmount.call(sdkDrives, mountPath)
+            : undefined,
+    };
+}
+function unknownErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function buildShellCommand(command, environment) {
+    const exports = Object.entries(environment).map(([key, value]) => {
+        assertShellEnvironmentName(key);
+        return `export ${key}=${shellQuote(value)}`;
+    });
+    if (exports.length === 0) {
+        return command;
+    }
+    return [...exports, command].join(' && ');
+}
+function remoteWriteTempPath(path) {
+    const dir = posixDirname(path);
+    const prefix = dir === '/' ? '' : dir;
+    return `${prefix}/.openai-agents-write-${randomUUID()}`;
+}
+function resolveBlaxelTimeouts(options) {
+    return {
+        ...options.timeouts,
+        execTimeoutMs: options.timeouts?.execTimeoutMs ?? options.timeoutMs,
+        createTimeoutMs: options.timeouts?.createTimeoutMs ?? options.createTimeoutMs,
+        workspaceTarTimeoutMs: options.timeouts?.workspaceTarTimeoutMs ?? options.timeoutMs,
+        fastOperationTimeoutMs: options.timeouts?.fastOperationTimeoutMs ?? options.timeoutMs,
+    };
+}
+async function withBlaxelOperationTimeout(operation, timeoutMs, operationName, options = {}) {
+    if (typeof timeoutMs !== 'number') {
+        return await operation;
+    }
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            options.onTimeout?.();
+            reject(new SandboxProviderError(`BlaxelSandboxClient ${operationName} timed out after ${timeoutMs}ms.`, {
+                provider: 'blaxel',
+                operation: operationName,
+                timeoutMs,
+            }));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+function extractBlaxelSandboxUrl(sandbox) {
+    if (!isRecord(sandbox)) {
+        return undefined;
+    }
+    const directUrl = sandbox.url;
+    if (typeof directUrl === 'string') {
+        return directUrl;
+    }
+    const nestedSandbox = sandbox.sandbox;
+    if (!isRecord(nestedSandbox)) {
+        return undefined;
+    }
+    const metadata = nestedSandbox.metadata;
+    if (!isRecord(metadata) || typeof metadata.url !== 'string') {
+        return undefined;
+    }
+    return metadata.url;
+}
+function buildBlaxelPtyWebSocketUrl(args) {
+    const base = args.sandboxUrl.replace(/\/$/u, '');
+    const wsBase = base.replace(/^https:/u, 'wss:').replace(/^http:/u, 'ws:');
+    const params = new URLSearchParams({
+        token: args.token,
+        cols: String(args.cols ?? 80),
+        rows: String(args.rows ?? 24),
+        sessionId: args.sessionId,
+        workingDir: args.cwd,
+    });
+    return `${wsBase}/terminal/ws?${params.toString()}`;
+}
+function handleBlaxelPtyMessage(entry, event) {
+    const text = webSocketEventText(event);
+    if (!text) {
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        return;
+    }
+    if (!isRecord(payload)) {
+        return;
+    }
+    const type = payload.type ?? payload.Type;
+    if (type === 'output') {
+        const data = payload.data ?? payload.Data;
+        if (typeof data === 'string') {
+            appendPtyOutput(entry, data);
+        }
+        return;
+    }
+    if (type === 'error') {
+        const data = payload.data ?? payload.Data;
+        if (typeof data === 'string') {
+            appendPtyOutput(entry, data);
+        }
+        markPtyDone(entry, 1);
+    }
+}
+function blaxelPtyCloseExitCode(entry, event) {
+    if (entry.exitCode !== null) {
+        return entry.exitCode;
+    }
+    return webSocketCloseCode(event) === 1000 ? 0 : 1;
+}
+function webSocketCloseCode(event) {
+    if (typeof event === 'number') {
+        return event;
+    }
+    if (!isRecord(event)) {
+        return undefined;
+    }
+    const code = event.code ?? event.data;
+    return typeof code === 'number' ? code : undefined;
+}
+function extractBlaxelPreviewUrl(preview) {
+    if (!isRecord(preview)) {
+        return undefined;
+    }
+    for (const nested of ['spec', 'status']) {
+        const value = preview[nested];
+        if (isRecord(value) && typeof value.url === 'string' && value.url) {
+            return value.url;
+        }
+    }
+    for (const key of ['url', 'endpoint']) {
+        const value = preview[key];
+        if (typeof value === 'string' && value) {
+            return value;
+        }
+    }
+    return extractBlaxelPreviewUrl(preview.preview);
+}
+async function createBlaxelPreviewTokenQuery(preview, ttlSeconds, port) {
+    const tokens = findBlaxelPreviewTokens(preview);
+    if (!tokens) {
+        throw new SandboxProviderError('BlaxelSandboxClient private previews require a preview token API.', {
+            provider: 'blaxel',
+            port,
+        });
+    }
+    const createToken = tokens.create;
+    if (typeof createToken !== 'function') {
+        throw new SandboxProviderError('BlaxelSandboxClient private previews require tokens.create().', {
+            provider: 'blaxel',
+            port,
+        });
+    }
+    let token;
+    try {
+        token = await createToken.call(tokens, new Date(Date.now() + Math.max(1, ttlSeconds) * 1000));
+    }
+    catch (error) {
+        throw new SandboxProviderError(`BlaxelSandboxClient failed to create a private preview token for port ${port}.`, {
+            provider: 'blaxel',
+            port,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const tokenValue = typeof token === 'string'
+        ? token
+        : isRecord(token) && typeof token.value === 'string'
+            ? token.value
+            : isRecord(token) && typeof token.token === 'string'
+                ? token.token
+                : undefined;
+    if (!tokenValue) {
+        throw new SandboxProviderError('BlaxelSandboxClient private preview token response did not include a token value.', {
+            provider: 'blaxel',
+            port,
+        });
+    }
+    return new URLSearchParams({
+        bl_preview_token: tokenValue,
+    }).toString();
+}
+function findBlaxelPreviewTokens(preview, seen = new Set()) {
+    if (!isRecord(preview)) {
+        return undefined;
+    }
+    if (seen.has(preview)) {
+        return undefined;
+    }
+    seen.add(preview);
+    if (isRecord(preview.tokens)) {
+        return preview.tokens;
+    }
+    return findBlaxelPreviewTokens(preview.preview, seen);
+}
+function webSocketEventText(event) {
+    const data = event && typeof event === 'object' && 'data' in event
+        ? event.data
+        : event;
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return new TextDecoder().decode(data);
+    }
+    if (ArrayBuffer.isView(data)) {
+        return new TextDecoder().decode(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+    }
+    return undefined;
+}
+//# sourceMappingURL=sandbox.mjs.map