@vercel/sandbox 2.0.0-beta.2 → 2.0.0-beta.20

package/dist/sandbox.js

@@ -1,564 +1,815 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Sandbox = void 0;
-const api_client_1 = require("./api-client");
-const api_error_1 = require("./api-client/api-error");
-const get_credentials_1 = require("./utils/get-credentials");
-const types_1 = require("./utils/types");
-const session_1 = require("./session");
-const network_policy_1 = require("./utils/network-policy");
-const promises_1 = require("node:timers/promises");
+import { APIError } from "./api-client/api-error.js";
+import { fromAPINetworkPolicy } from "./utils/network-policy.js";
+import { getPrivateParams } from "./utils/types.js";
+import { APIClient } from "./api-client/api-client.js";
+import "./api-client/index.js";
+import { getCredentials } from "./utils/get-credentials.js";
+import { attachPaginator } from "./utils/paginator.js";
+import { Session } from "./session.js";
+import { FileSystem } from "./filesystem.js";
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
+import { setTimeout } from "node:timers/promises";
+
+//#region src/sandbox.ts
 function isSandboxStoppedError(err) {
-    return err instanceof api_error_1.APIError && err.response.status === 410;
+	return err instanceof APIError && err.response.status === 410;
+}
+function isNotFoundError(err) {
+	return err instanceof APIError && err.response.status === 404;
+}
+function isSnapshotNotFoundError(err) {
+	return err instanceof APIError && err.response.status === 410 && err.json?.error?.code === "snapshot_not_found";
 }
 function isSandboxStoppingError(err) {
-    return (err instanceof api_error_1.APIError &&
-        err.response.status === 422 &&
-        err.json?.error?.code === "sandbox_stopping");
+	return err instanceof APIError && err.response.status === 422 && err.json?.error?.code === "sandbox_stopping";
 }
-/**
- * A Sandbox is a persistent, isolated Linux MicroVMs to run commands in.
- * Use {@link Sandbox.create} or {@link Sandbox.get} to construct.
- * @hideconstructor
- */
-class Sandbox {
-    /**
-     * The name of this sandbox.
-     */
-    get name() {
-        return this.namedSandbox.name;
-    }
-    /**
-     * Routes from ports to subdomains.
-     * @hidden
-     */
-    get routes() {
-        return this.session.routes;
-    }
-    /**
-     * Whether the sandbox persists the state.
-     */
-    get persistent() {
-        return this.namedSandbox.persistent;
-    }
-    /**
-     * The region this sandbox runs in.
-     */
-    get region() {
-        return this.namedSandbox.region;
-    }
-    /**
-     * Number of virtual CPUs allocated.
-     */
-    get vcpus() {
-        return this.namedSandbox.vcpus;
-    }
-    /**
-     * Memory allocated in MB.
-     */
-    get memory() {
-        return this.namedSandbox.memory;
-    }
-    /** Runtime identifier (e.g. "node24", "python3.13"). */
-    get runtime() {
-        return this.namedSandbox.runtime;
-    }
-    /**
-     * Cumulative egress bytes across all sessions.
-     */
-    get totalEgressBytes() {
-        return this.namedSandbox.totalEgressBytes;
-    }
-    /**
-     * Cumulative ingress bytes across all sessions.
-     */
-    get totalIngressBytes() {
-        return this.namedSandbox.totalIngressBytes;
-    }
-    /**
-     * Cumulative active CPU duration in milliseconds across all sessions.
-     */
-    get totalActiveCpuDurationMs() {
-        return this.namedSandbox.totalActiveCpuDurationMs;
-    }
-    /**
-     * Cumulative wall-clock duration in milliseconds across all sessions.
-     */
-    get totalDurationMs() {
-        return this.namedSandbox.totalDurationMs;
-    }
-    /**
-     * When this sandbox was last updated.
-     */
-    get updatedAt() {
-        return new Date(this.namedSandbox.updatedAt);
-    }
-    /**
-     * When this sandbox was created.
-     */
-    get createdAt() {
-        return new Date(this.namedSandbox.createdAt);
-    }
-    /**
-     * Interactive port.
-     */
-    get interactivePort() {
-        return this.session.interactivePort;
-    }
-    /**
-     * The status of the current session.
-     */
-    get status() {
-        return this.session.status;
-    }
-    /**
-     * The default timeout of this sandbox in milliseconds.
-     */
-    get timeout() {
-        return this.namedSandbox.timeout;
-    }
-    /**
-     * The default network policy of this sandbox.
-     */
-    get networkPolicy() {
-        return this.namedSandbox.networkPolicy
-            ? (0, network_policy_1.fromAPINetworkPolicy)(this.namedSandbox.networkPolicy)
-            : undefined;
-    }
-    /**
-     * If the session was created from a snapshot, the ID of that snapshot.
-     */
-    get sourceSnapshotId() {
-        return this.session.sourceSnapshotId;
-    }
-    /**
-     * The current snapshot ID of this sandbox, if any.
-     */
-    get currentSnapshotId() {
-        return this.namedSandbox.currentSnapshotId;
-    }
-    /**
-     * The amount of CPU used by the session. Only reported once the VM is stopped.
-     */
-    get activeCpuUsageMs() {
-        return this.session.activeCpuUsageMs;
-    }
-    /**
-     * The amount of network data used by the session. Only reported once the VM is stopped.
-     */
-    get networkTransfer() {
-        return this.session.networkTransfer;
-    }
-    /**
-     * Allow to get a list of sandboxes for a team narrowed to the given params.
-     * It returns both the sandboxes and the pagination metadata to allow getting
-     * the next page of results.
-     */
-    static async list(params) {
-        const credentials = await (0, get_credentials_1.getCredentials)(params);
-        const client = new api_client_1.APIClient({
-            teamId: credentials.teamId,
-            token: credentials.token,
-            fetch: params?.fetch,
-        });
-        return client.listNamedSandboxes({
-            ...credentials,
-            ...params,
-        });
-    }
-    /**
-     * Create a new sandbox.
-     *
-     * @param params - Creation parameters and optional credentials.
-     * @returns A promise resolving to the created {@link Sandbox}.
-     * @example
-     * <caption>Create a sandbox and drop it in the end of the block</caption>
-     * async function fn() {
-     *   await using const sandbox = await Sandbox.create();
-     *   // Sandbox automatically stopped at the end of the lexical scope
-     * }
-     */
-    static async create(params) {
-        const credentials = await (0, get_credentials_1.getCredentials)(params);
-        const client = new api_client_1.APIClient({
-            teamId: credentials.teamId,
-            token: credentials.token,
-            fetch: params?.fetch,
-        });
-        const privateParams = (0, types_1.getPrivateParams)(params);
-        const response = await client.createSandbox({
-            source: params?.source,
-            projectId: credentials.projectId,
-            ports: params?.ports ?? [],
-            timeout: params?.timeout,
-            resources: params?.resources,
-            runtime: params && "runtime" in params ? params?.runtime : undefined,
-            networkPolicy: params?.networkPolicy,
-            env: params?.env,
-            signal: params?.signal,
-            name: params?.name,
-            persistent: params?.persistent,
-            ...privateParams,
-        });
-        return new DisposableSandbox({
-            client,
-            session: response.json.sandbox,
-            namedSandbox: response.json.namedSandbox,
-            routes: response.json.routes,
-            projectId: credentials.projectId,
-        });
-    }
-    /**
-     * Retrieve an existing sandbox and resume its session.
-     *
-     * @param params - Get parameters and optional credentials.
-     * @returns A promise resolving to the {@link Sandbox}.
-     */
-    static async get(params) {
-        const credentials = await (0, get_credentials_1.getCredentials)(params);
-        const client = new api_client_1.APIClient({
-            teamId: credentials.teamId,
-            token: credentials.token,
-            fetch: params.fetch,
-        });
-        const response = await client.getNamedSandbox({
-            name: params.name,
-            projectId: credentials.projectId,
-            resume: params.resume,
-            signal: params.signal,
-        });
-        return new Sandbox({
-            client,
-            session: response.json.sandbox,
-            namedSandbox: response.json.namedSandbox,
-            routes: response.json.routes,
-            projectId: credentials.projectId,
-        });
-    }
-    constructor({ client, routes, session, namedSandbox, projectId, }) {
-        this.client = client;
-        this.session = new session_1.Session({ client, routes, session });
-        this.namedSandbox = namedSandbox;
-        this.projectId = projectId;
-    }
-    /**
-     * Get the current session (the running VM) for this sandbox.
-     *
-     * @returns The {@link Session} instance.
-     */
-    currentSession() {
-        return this.session;
-    }
-    /**
-     * Resume this sandbox by creating a new session via `getNamedSandbox`.
-     */
-    async resume(signal) {
-        const response = await this.client.getNamedSandbox({
-            name: this.namedSandbox.name,
-            projectId: this.projectId,
-            resume: true,
-            signal,
-        });
-        this.session = new session_1.Session({
-            client: this.client,
-            routes: response.json.routes,
-            session: response.json.sandbox,
-        });
-    }
-    /**
-     * Poll until the current session reaches a terminal state, then resume.
-     */
-    async waitForStopAndResume(signal) {
-        const pollingInterval = 500;
-        let status = this.session.status;
-        while (status === "stopping" || status === "snapshotting") {
-            await (0, promises_1.setTimeout)(pollingInterval, undefined, { signal });
-            const poll = await this.client.getSandbox({
-                sandboxId: this.session.sessionId,
-                signal,
-            });
-            this.session = new session_1.Session({
-                client: this.client,
-                routes: poll.json.routes,
-                session: poll.json.sandbox,
-            });
-            status = poll.json.sandbox.status;
-        }
-        await this.resume(signal);
-    }
-    /**
-     * Execute `fn`, and if the session is stopped/stopping, resume and retry.
-     */
-    async withResume(fn, signal) {
-        try {
-            return await fn();
-        }
-        catch (err) {
-            if (isSandboxStoppedError(err)) {
-                await this.resume(signal);
-                return fn();
-            }
-            if (isSandboxStoppingError(err)) {
-                await this.waitForStopAndResume(signal);
-                return fn();
-            }
-            throw err;
-        }
-    }
-    async runCommand(commandOrParams, args, opts) {
-        const signal = typeof commandOrParams === "string" ? opts?.signal : commandOrParams.signal;
-        return this.withResume(() => this.session.runCommand(commandOrParams, args, opts), signal);
-    }
-    /**
-     * Internal helper to start a command in the sandbox.
-     *
-     * @param params - Command execution parameters.
-     * @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
-     * @internal
-     */
-    async getCommand(cmdId, opts) {
-        return this.withResume(() => this.session.getCommand(cmdId, opts), opts?.signal);
-    }
-    /**
-     * Create a directory in the filesystem of this sandbox.
-     *
-     * @param path - Path of the directory to create
-     * @param opts - Optional parameters.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     */
-    async mkDir(path, opts) {
-        return this.withResume(() => this.session.mkDir(path, opts), opts?.signal);
-    }
-    /**
-     * Read a file from the filesystem of this sandbox as a stream.
-     *
-     * @param file - File to read, with path and optional cwd
-     * @param opts - Optional parameters.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found
-     */
-    async readFile(file, opts) {
-        return this.withResume(() => this.session.readFile(file, opts), opts?.signal);
-    }
-    /**
-     * Read a file from the filesystem of this sandbox as a Buffer.
-     *
-     * @param file - File to read, with path and optional cwd
-     * @param opts - Optional parameters.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @returns A promise that resolves to the file contents as a Buffer, or null if file not found
-     */
-    async readFileToBuffer(file, opts) {
-        return this.withResume(() => this.session.readFileToBuffer(file, opts), opts?.signal);
-    }
-    /**
-     * Download a file from the sandbox to the local filesystem.
-     *
-     * @param src - Source file on the sandbox, with path and optional cwd
-     * @param dst - Destination file on the local machine, with path and optional cwd
-     * @param opts - Optional parameters.
-     * @param opts.mkdirRecursive - If true, create parent directories for the destination if they don't exist.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @returns The absolute path to the written file, or null if the source file was not found
-     */
-    async downloadFile(src, dst, opts) {
-        return this.withResume(() => this.session.downloadFile(src, dst, opts), opts?.signal);
-    }
-    /**
-     * Write files to the filesystem of this sandbox.
-     * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
-     * Writes files using the `vercel-sandbox` user.
-     *
-     * @param files - Array of files with path and stream/buffer contents
-     * @param opts - Optional parameters.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @returns A promise that resolves when the files are written
-     */
-    async writeFiles(files, opts) {
-        return this.withResume(() => this.session.writeFiles(files, opts), opts?.signal);
-    }
-    /**
-     * Get the public domain of a port of this sandbox.
-     *
-     * @param p - Port number to resolve
-     * @returns A full domain (e.g. `https://subdomain.vercel.run`)
-     * @throws If the port has no associated route
-     */
-    domain(p) {
-        return this.session.domain(p);
-    }
-    /**
-     * Stop the sandbox.
-     *
-     * @param opts - Optional parameters.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @param opts.blocking - If true, poll until the sandbox has fully stopped and return the final state.
-     * @returns The sandbox metadata at the time the stop was acknowledged, or after fully stopped if `blocking` is true.
-     */
-    async stop(opts) {
-        return this.session.stop(opts);
-    }
-    /**
-     * Update the network policy for this sandbox.
-     *
-     * @deprecated Use {@link Sandbox.update} instead.
-     *
-     * @param networkPolicy - The new network policy to apply.
-     * @param opts - Optional parameters.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @returns A promise that resolves when the network policy is updated.
-     *
-     * @example
-     * // Restrict to specific domains
-     * await sandbox.updateNetworkPolicy({
-     *   allow: ["*.npmjs.org", "github.com"],
-     * });
-     *
-     * @example
-     * // Inject credentials with per-domain transformers
-     * await sandbox.updateNetworkPolicy({
-     *   allow: {
-     *     "ai-gateway.vercel.sh": [{
-     *       transform: [{
-     *         headers: { authorization: "Bearer ..." }
-     *       }]
-     *     }],
-     *     "*": []
-     *   }
-     * });
-     *
-     * @example
-     * // Deny all network access
-     * await sandbox.updateNetworkPolicy("deny-all");
-     */
-    async updateNetworkPolicy(networkPolicy, opts) {
-        await this.withResume(() => this.session.update({ networkPolicy: networkPolicy }, opts), opts?.signal);
-        return this.session.networkPolicy;
-    }
-    /**
-     * Extend the timeout of the sandbox by the specified duration.
-     *
-     * This allows you to extend the lifetime of a sandbox up until the maximum
-     * execution timeout for your plan.
-     *
-     * @param duration - The duration in milliseconds to extend the timeout by
-     * @param opts - Optional parameters.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @returns A promise that resolves when the timeout is extended
-     *
-     * @example
-     * const sandbox = await Sandbox.create({ timeout: ms('10m') });
-     * // Extends timeout by 5 minutes, to a total of 15 minutes.
-     * await sandbox.extendTimeout(ms('5m'));
-     */
-    async extendTimeout(duration, opts) {
-        return this.withResume(() => this.session.extendTimeout(duration, opts), opts?.signal);
-    }
-    /**
-     * Create a snapshot from this currently running sandbox. New sandboxes can
-     * then be created from this snapshot using {@link Sandbox.createFromSnapshot}.
-     *
-     * Note: this sandbox will be stopped as part of the snapshot creation process.
-     *
-     * @param opts - Optional parameters.
-     * @param opts.expiration - Optional expiration time in milliseconds. Use 0 for no expiration at all.
-     * @param opts.signal - An AbortSignal to cancel the operation.
-     * @returns A promise that resolves to the Snapshot instance
-     */
-    async snapshot(opts) {
-        return this.withResume(() => this.session.snapshot(opts), opts?.signal);
-    }
-    /**
-     * Update the named sandbox configuration.
-     *
-     * @param params - Fields to update.
-     * @param opts - Optional abort signal.
-     */
-    async update(params, opts) {
-        // Update the sandbox config. This config will be used on the next session.
-        const response = await this.client.updateNamedSandbox({
-            name: this.namedSandbox.name,
-            projectId: this.projectId,
-            persistent: params.persistent,
-            resources: params.resources,
-            timeout: params.timeout,
-            networkPolicy: params.networkPolicy,
-            signal: opts?.signal,
-        });
-        this.namedSandbox = response.json.namedSandbox;
-        // Update the current session config. This only applies to network policy.
-        if (params.networkPolicy) {
-            try {
-                return await this.session.update({ networkPolicy: params.networkPolicy }, opts);
-            }
-            catch (err) {
-                if (isSandboxStoppedError(err) || isSandboxStoppingError(err)) {
-                    return;
-                }
-                throw err;
-            }
-        }
-    }
-    /**
-     * Delete this named sandbox.
-     *
-     * After deletion the instance becomes inert — all further API calls will
-     * throw immediately.
-     */
-    async delete(opts) {
-        await this.client.deleteNamedSandbox({
-            name: this.namedSandbox.name,
-            projectId: this.projectId,
-            preserveSnapshots: opts?.preserveSnapshots,
-            signal: opts?.signal,
-        });
-    }
-    /**
-     * List sessions (VMs) that have been created for this named sandbox.
-     *
-     * @param params - Optional pagination parameters.
-     * @returns The list of sessions and pagination metadata.
-     */
-    async listSessions(params) {
-        return this.client.listSandboxes({
-            projectId: this.projectId,
-            name: this.namedSandbox.name,
-            limit: params?.limit,
-            since: params?.since,
-            until: params?.until,
-            signal: params?.signal,
-        });
-    }
-    /**
-     * List snapshots that belong to this named sandbox.
-     *
-     * @param params - Optional pagination parameters.
-     * @returns The list of snapshots and pagination metadata.
-     */
-    async listSnapshots(params) {
-        return this.client.listSnapshots({
-            projectId: this.projectId,
-            name: this.namedSandbox.name,
-            limit: params?.limit,
-            since: params?.since,
-            until: params?.until,
-            signal: params?.signal,
-        });
-    }
+function isSandboxSnapshottingError(err) {
+	return err instanceof APIError && err.response.status === 422 && err.json?.error?.code === "sandbox_snapshotting";
 }
-exports.Sandbox = Sandbox;
 /**
- * A {@link Sandbox} that can automatically be disposed using a `await using` statement.
- *
- * @example
- * {
- *   await using const sandbox = await Sandbox.create();
- * }
- * // Sandbox is automatically stopped here
- */
-class DisposableSandbox extends Sandbox {
-    async [Symbol.asyncDispose]() {
-        await this.stop();
-    }
-}
+* A Sandbox is a persistent, isolated Linux MicroVMs to run commands in.
+* Use {@link Sandbox.create} or {@link Sandbox.get} to construct.
+* @hideconstructor
+*/
+var Sandbox = class Sandbox {
+	/**
+	* Lazily resolve credentials and construct an API client.
+	* @internal
+	*/
+	async ensureClient() {
+		"use step";
+		if (this._client) return this._client;
+		const credentials = await getCredentials();
+		this._client = new APIClient({
+			teamId: credentials.teamId,
+			token: credentials.token
+		});
+		return this._client;
+	}
+	/**
+	* The name of this sandbox.
+	*/
+	get name() {
+		return this.sandbox.name;
+	}
+	/**
+	* Routes from ports to subdomains.
+	* @hidden
+	*/
+	get routes() {
+		return this.currentSession().routes;
+	}
+	/**
+	* Whether the sandbox persists the state.
+	*/
+	get persistent() {
+		return this.sandbox.persistent;
+	}
+	/**
+	* The region this sandbox runs in.
+	*/
+	get region() {
+		return this.sandbox.region;
+	}
+	/**
+	* Number of virtual CPUs allocated.
+	*/
+	get vcpus() {
+		return this.sandbox.vcpus;
+	}
+	/**
+	* Memory allocated in MB.
+	*/
+	get memory() {
+		return this.sandbox.memory;
+	}
+	/** Runtime identifier (e.g. "node24", "python3.13"). */
+	get runtime() {
+		return this.sandbox.runtime;
+	}
+	/**
+	* Cumulative egress bytes across all sessions.
+	*/
+	get totalEgressBytes() {
+		return this.sandbox.totalEgressBytes;
+	}
+	/**
+	* Cumulative ingress bytes across all sessions.
+	*/
+	get totalIngressBytes() {
+		return this.sandbox.totalIngressBytes;
+	}
+	/**
+	* Cumulative active CPU duration in milliseconds across all sessions.
+	*/
+	get totalActiveCpuDurationMs() {
+		return this.sandbox.totalActiveCpuDurationMs;
+	}
+	/**
+	* Cumulative wall-clock duration in milliseconds across all sessions.
+	*/
+	get totalDurationMs() {
+		return this.sandbox.totalDurationMs;
+	}
+	/**
+	* When this sandbox was last updated.
+	*/
+	get updatedAt() {
+		return new Date(this.sandbox.updatedAt);
+	}
+	/**
+	* When the sandbox status was last updated.
+	*/
+	get statusUpdatedAt() {
+		return this.sandbox.statusUpdatedAt ? new Date(this.sandbox.statusUpdatedAt) : void 0;
+	}
+	/**
+	* When this sandbox was created.
+	*/
+	get createdAt() {
+		return new Date(this.sandbox.createdAt);
+	}
+	/**
+	* Interactive port.
+	*/
+	get interactivePort() {
+		return this.currentSession().interactivePort;
+	}
+	/**
+	* The status of the current session.
+	*/
+	get status() {
+		return this.currentSession().status;
+	}
+	/**
+	* The default timeout of this sandbox in milliseconds.
+	*/
+	get timeout() {
+		return this.sandbox.timeout;
+	}
+	/**
+	* Key-value tags attached to the sandbox.
+	*/
+	get tags() {
+		return this.sandbox.tags;
+	}
+	/**
+	* The default network policy of this sandbox.
+	*/
+	get networkPolicy() {
+		return this.sandbox.networkPolicy ? fromAPINetworkPolicy(this.sandbox.networkPolicy) : void 0;
+	}
+	/**
+	* If the session was created from a snapshot, the ID of that snapshot.
+	*/
+	get sourceSnapshotId() {
+		return this.currentSession().sourceSnapshotId;
+	}
+	/**
+	* The current snapshot ID of this sandbox, if any.
+	*/
+	get currentSnapshotId() {
+		return this.sandbox.currentSnapshotId;
+	}
+	/**
+	* The default snapshot expiration in milliseconds, if set.
+	*/
+	get snapshotExpiration() {
+		return this.sandbox.snapshotExpiration;
+	}
+	/**
+	* The amount of CPU used by the session. Only reported once the VM is stopped.
+	*/
+	get activeCpuUsageMs() {
+		return this.currentSession().activeCpuUsageMs;
+	}
+	/**
+	* The amount of network data used by the session. Only reported once the VM is stopped.
+	*/
+	get networkTransfer() {
+		return this.currentSession().networkTransfer;
+	}
+	/**
+	* Allow to get a list of sandboxes for a team narrowed to the given params.
+	* It returns both the sandboxes and the pagination metadata to allow getting
+	* the next page of results.
+	*
+	* The returned object is async-iterable to auto-paginate through all pages:
+	*
+	* ```ts
+	* const result = await Sandbox.list({ namePrefix: "ci-" });
+	* for await (const sandbox of result) { ... }
+	* // or: await result.toArray();
+	* // or: for await (const page of result.pages()) { ... }
+	* ```
+	*/
+	static async list(params) {
+		"use step";
+		const credentials = await getCredentials(params);
+		const client = new APIClient({
+			teamId: credentials.teamId,
+			token: credentials.token,
+			fetch: params?.fetch
+		});
+		const fetchPage = async (cursor) => {
+			return (await client.listSandboxes({
+				...credentials,
+				...params,
+				...cursor !== void 0 && { cursor }
+			})).json;
+		};
+		return attachPaginator(await fetchPage(params?.cursor), {
+			itemsKey: "sandboxes",
+			fetchNext: fetchPage,
+			signal: params?.signal
+		});
+	}
+	/**
+	* Serialize a Sandbox instance to plain data for @workflow/serde.
+	*
+	* @param instance - The Sandbox instance to serialize
+	* @returns A plain object containing sandbox metadata and routes
+	*/
+	static [WORKFLOW_SERIALIZE](instance) {
+		return {
+			metadata: instance.session?._sessionSnapshot,
+			routes: instance.session?.routes ?? [],
+			sandboxMetadata: instance.sandbox,
+			projectId: instance.projectId
+		};
+	}
+	/**
+	* Deserialize a Sandbox from serialized snapshot data.
+	*
+	* The deserialized instance uses the serialized metadata synchronously and
+	* lazily creates an API client only when methods perform API requests.
+	*
+	* @param data - The serialized sandbox data
+	* @returns The reconstructed Sandbox instance
+	*/
+	static [WORKFLOW_DESERIALIZE](data) {
+		const sandbox = new Sandbox({
+			sandbox: data.sandboxMetadata,
+			routes: data.routes,
+			projectId: data.projectId
+		});
+		if (data.metadata) sandbox.session = new Session({
+			routes: data.routes,
+			snapshot: data.metadata
+		});
+		return sandbox;
+	}
+	/**
+	* Create a new sandbox.
+	*
+	* @param params - Creation parameters and optional credentials.
+	* @returns A promise resolving to the created {@link Sandbox}.
+	* @example
+	* <caption>Create a sandbox with default options</caption>
+	* const sandbox = await Sandbox.create();
+	*
+	* @example
+	* <caption>Create a sandbox and drop it in the end of the block</caption>
+	* async function fn() {
+	*   await using const sandbox = await Sandbox.create();
+	*   // Sandbox automatically stopped at the end of the lexical scope
+	* }
+	*/
+	static async create(params) {
+		"use step";
+		const credentials = await getCredentials(params);
+		const client = new APIClient({
+			teamId: credentials.teamId,
+			token: credentials.token,
+			fetch: params?.fetch
+		});
+		const privateParams = getPrivateParams(params);
+		const response = await client.createSandbox({
+			source: params?.source,
+			projectId: credentials.projectId,
+			ports: params?.ports ?? [],
+			timeout: params?.timeout,
+			resources: params?.resources,
+			runtime: params && "runtime" in params ? params?.runtime : void 0,
+			networkPolicy: params?.networkPolicy,
+			env: params?.env,
+			tags: params?.tags,
+			snapshotExpiration: params?.snapshotExpiration,
+			signal: params?.signal,
+			name: params?.name,
+			persistent: params?.persistent,
+			...privateParams
+		});
+		return new DisposableSandbox({
+			client,
+			session: response.json.session,
+			sandbox: response.json.sandbox,
+			routes: response.json.routes,
+			projectId: credentials.projectId,
+			onResume: params?.onResume
+		});
+	}
+	/**
+	* Retrieve an existing sandbox and resume its session.
+	*
+	* @param params - Get parameters and optional credentials.
+	* @returns A promise resolving to the {@link Sandbox}.
+	*/
+	static async get(params) {
+		"use step";
+		const credentials = await getCredentials(params);
+		const client = new APIClient({
+			teamId: credentials.teamId,
+			token: credentials.token,
+			fetch: params.fetch
+		});
+		const privateParams = getPrivateParams(params);
+		const response = await client.getSandbox({
+			name: params.name,
+			projectId: credentials.projectId,
+			resume: params.resume,
+			signal: params.signal,
+			...privateParams
+		});
+		const sandbox = new Sandbox({
+			client,
+			session: response.json.session,
+			sandbox: response.json.sandbox,
+			routes: response.json.routes,
+			projectId: credentials.projectId,
+			onResume: params.onResume
+		});
+		if (response.json.resumed && params.onResume) await params.onResume(sandbox);
+		return sandbox;
+	}
+	/**
+	* Retrieve an existing named sandbox, or create a new one if none exists.
+	*
+	* If `name` is omitted, this always creates a new sandbox and fires
+	* `onCreate`. If `name` is provided, it first tries {@link Sandbox.get};
+	* on `not_found` it creates a new sandbox with that name; on
+	* `snapshot_not_found` it deletes the stale named sandbox and creates
+	* a fresh one with the same name.
+	*
+	* @param params - Get/create parameters plus an optional `onCreate` hook.
+	* @returns A promise resolving to the {@link Sandbox}.
+	*
+	* @example
+	* <caption>Idempotent named sandbox with one-time setup</caption>
+	* const sandbox = await Sandbox.getOrCreate({
+	*   name: "my-workspace",
+	*   onCreate: async (sbx) => {
+	*     await sbx.writeFiles([
+	*       { path: "README.md", content: Buffer.from("# Hello") },
+	*     ]);
+	*   },
+	* });
+	*
+	* @example
+	* <caption>Unnamed — always creates</caption>
+	* const sandbox = await Sandbox.getOrCreate({
+	*   onCreate: async (sbx) => {
+	*     await sbx.runCommand("npm", ["install"]);
+	*   },
+	* });
+	*/
+	static async getOrCreate(params) {
+		"use step";
+		if (!params?.name) {
+			const sandbox = await Sandbox.create(params);
+			if (params?.onCreate) await params.onCreate(sandbox);
+			return sandbox;
+		}
+		try {
+			return await Sandbox.get(params);
+		} catch (err) {
+			if (isNotFoundError(err)) {
+				const sandbox = await Sandbox.create(params);
+				if (params.onCreate) await params.onCreate(sandbox);
+				return sandbox;
+			}
+			if (isSnapshotNotFoundError(err)) {
+				const credentials = await getCredentials(params);
+				const client = new APIClient({
+					teamId: credentials.teamId,
+					token: credentials.token,
+					fetch: params.fetch
+				});
+				const privateParams = getPrivateParams(params);
+				try {
+					await client.deleteSandbox({
+						name: params.name,
+						projectId: credentials.projectId,
+						signal: params.signal,
+						...privateParams
+					});
+				} catch (deleteErr) {
+					if (!isNotFoundError(deleteErr)) throw deleteErr;
+				}
+				const sandbox = await Sandbox.create(params);
+				if (params.onCreate) await params.onCreate(sandbox);
+				return sandbox;
+			}
+			throw err;
+		}
+	}
+	/**
+	* Create a new Sandbox instance.
+	*
+	* @param params.client - Optional API client. If not provided, will be lazily created using global credentials.
+	* @param params.routes - Port-to-subdomain mappings for exposed ports
+	* @param params.sandbox - Sandbox snapshot metadata
+	*/
+	constructor({ client, routes, session, sandbox, projectId, onResume }) {
+		this._client = null;
+		this.resumePromise = null;
+		this._client = client ?? null;
+		if (session) this.session = new Session({
+			client,
+			routes,
+			session
+		});
+		this.sandbox = sandbox;
+		this.projectId = projectId ?? "";
+		this.onResume = onResume;
+		this.fs = new FileSystem(this);
+	}
+	/**
+	* Get the current session (the running VM) for this sandbox.
+	*
+	* @returns The {@link Session} instance.
+	*/
+	currentSession() {
+		if (!this.session) throw new Error("No active session. Run a command or call resume first.");
+		return this.session;
+	}
+	/**
+	* Resume this sandbox by creating a new session via `getSandbox`.
+	*/
+	async resume(signal) {
+		if (!this.resumePromise) this.resumePromise = this.doResume(signal).finally(() => {
+			this.resumePromise = null;
+		});
+		return this.resumePromise;
+	}
+	async doResume(signal) {
+		const client = await this.ensureClient();
+		const response = await client.getSandbox({
+			name: this.sandbox.name,
+			projectId: this.projectId,
+			resume: true,
+			signal
+		});
+		this.session = new Session({
+			client,
+			routes: response.json.routes,
+			session: response.json.session
+		});
+		if (this.onResume && response.json.resumed) await this.onResume(this);
+	}
+	/**
+	* Poll until the current session reaches a terminal state, then resume.
+	*/
+	async waitForStopAndResume(signal) {
+		"use step";
+		const client = await this.ensureClient();
+		const pollingInterval = 500;
+		let status = this.session.status;
+		while (status === "stopping" || status === "snapshotting") {
+			await setTimeout(pollingInterval, void 0, { signal });
+			const poll = await client.getSession({
+				sessionId: this.session.sessionId,
+				signal
+			});
+			this.session = new Session({
+				client,
+				routes: poll.json.routes,
+				session: poll.json.session
+			});
+			status = poll.json.session.status;
+		}
+		await this.resume(signal);
+	}
+	/**
+	* Execute `fn`, and if the session is stopped/stopping/snapshotting, resume and retry.
+	*/
+	async withResume(fn, signal) {
+		if (!this.session) await this.resume(signal);
+		try {
+			return await fn();
+		} catch (err) {
+			if (isSandboxStoppedError(err)) {
+				await this.resume(signal);
+				return fn();
+			}
+			if (isSandboxStoppingError(err) || isSandboxSnapshottingError(err)) {
+				await this.waitForStopAndResume(signal);
+				return fn();
+			}
+			throw err;
+		}
+	}
+	async runCommand(commandOrParams, args, opts) {
+		"use step";
+		const signal = typeof commandOrParams === "string" ? opts?.signal : commandOrParams.signal;
+		return this.withResume(() => this.session.runCommand(commandOrParams, args, opts), signal);
+	}
+	/**
+	* Internal helper to start a command in the sandbox.
+	*
+	* @param params - Command execution parameters.
+	* @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
+	* @internal
+	*/
+	async getCommand(cmdId, opts) {
+		"use step";
+		return this.withResume(() => this.session.getCommand(cmdId, opts), opts?.signal);
+	}
+	/**
+	* Create a directory in the filesystem of this sandbox.
+	*
+	* @param path - Path of the directory to create
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	*/
+	async mkDir(path, opts) {
+		"use step";
+		return this.withResume(() => this.session.mkDir(path, opts), opts?.signal);
+	}
+	/**
+	* Read a file from the filesystem of this sandbox as a stream.
+	*
+	* @param file - File to read, with path and optional cwd
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns A promise that resolves to a ReadableStream containing the file contents, or null if file not found
+	*/
+	async readFile(file, opts) {
+		"use step";
+		return this.withResume(() => this.session.readFile(file, opts), opts?.signal);
+	}
+	/**
+	* Read a file from the filesystem of this sandbox as a Buffer.
+	*
+	* @param file - File to read, with path and optional cwd
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns A promise that resolves to the file contents as a Buffer, or null if file not found
+	*/
+	async readFileToBuffer(file, opts) {
+		"use step";
+		return this.withResume(() => this.session.readFileToBuffer(file, opts), opts?.signal);
+	}
+	/**
+	* Download a file from the sandbox to the local filesystem.
+	*
+	* @param src - Source file on the sandbox, with path and optional cwd
+	* @param dst - Destination file on the local machine, with path and optional cwd
+	* @param opts - Optional parameters.
+	* @param opts.mkdirRecursive - If true, create parent directories for the destination if they don't exist.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns The absolute path to the written file, or null if the source file was not found
+	*/
+	async downloadFile(src, dst, opts) {
+		"use step";
+		return this.withResume(() => this.session.downloadFile(src, dst, opts), opts?.signal);
+	}
+	/**
+	* Write files to the filesystem of this sandbox.
+	* Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+	* Writes files using the `vercel-sandbox` user.
+	*
+	* @param files - Array of files with path, content, and optional mode (permissions)
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns A promise that resolves when the files are written
+	*
+	* @example
+	* // Write an executable script
+	* await sandbox.writeFiles([
+	*   { path: "/usr/local/bin/myscript", content: "#!/bin/bash\necho hello", mode: 0o755 }
+	* ]);
+	*/
+	async writeFiles(files, opts) {
+		"use step";
+		return this.withResume(() => this.session.writeFiles(files, opts), opts?.signal);
+	}
+	/**
+	* Get the public domain of a port of this sandbox.
+	*
+	* @param p - Port number to resolve
+	* @returns A full domain (e.g. `https://subdomain.vercel.run`)
+	* @throws If the port has no associated route
+	*/
+	domain(p) {
+		return this.currentSession().domain(p);
+	}
+	/**
+	* Stop the sandbox.
+	*
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns The final session state after stopping, with optional snapshot metadata.
+	*/
+	async stop(opts) {
+		"use step";
+		if (!this.session) throw new Error("No active session to stop.");
+		const { session, sandbox, snapshot } = await this.session.stop(opts);
+		if (sandbox) this.sandbox = sandbox;
+		return Object.assign(session, { snapshot });
+	}
+	/**
+	* Update the network policy for this sandbox.
+	*
+	* @deprecated Use {@link Sandbox.update} instead.
+	*
+	* @param networkPolicy - The new network policy to apply.
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns A promise that resolves when the network policy is updated.
+	*
+	* @example
+	* // Restrict to specific domains
+	* await sandbox.updateNetworkPolicy({
+	*   allow: ["*.npmjs.org", "github.com"],
+	* });
+	*
+	* @example
+	* // Inject credentials with per-domain transformers
+	* await sandbox.updateNetworkPolicy({
+	*   allow: {
+	*     "ai-gateway.vercel.sh": [{
+	*       transform: [{
+	*         headers: { authorization: "Bearer ..." }
+	*       }]
+	*     }],
+	*     "*": []
+	*   }
+	* });
+	*
+	* @example
+	* // Deny all network access
+	* await sandbox.updateNetworkPolicy("deny-all");
+	*/
+	async updateNetworkPolicy(networkPolicy, opts) {
+		"use step";
+		await this.withResume(() => this.session.update({ networkPolicy }, opts), opts?.signal);
+		return this.session.networkPolicy;
+	}
+	/**
+	* Extend the timeout of the sandbox by the specified duration.
+	*
+	* This allows you to extend the lifetime of a sandbox up until the maximum
+	* execution timeout for your plan.
+	*
+	* @param duration - The duration in milliseconds to extend the timeout by
+	* @param opts - Optional parameters.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns A promise that resolves when the timeout is extended
+	*
+	* @example
+	* const sandbox = await Sandbox.create({ timeout: ms('10m') });
+	* // Extends timeout by 5 minutes, to a total of 15 minutes.
+	* await sandbox.extendTimeout(ms('5m'));
+	*/
+	async extendTimeout(duration, opts) {
+		"use step";
+		return this.withResume(() => this.session.extendTimeout(duration, opts), opts?.signal);
+	}
+	/**
+	* Create a snapshot from this currently running sandbox. New sandboxes can
+	* then be created from this snapshot using {@link Sandbox.createFromSnapshot}.
+	*
+	* Note: this sandbox will be stopped as part of the snapshot creation process.
+	*
+	* @param opts - Optional parameters.
+	* @param opts.expiration - Optional expiration time in milliseconds. Use 0 for no expiration at all.
+	* @param opts.signal - An AbortSignal to cancel the operation.
+	* @returns A promise that resolves to the Snapshot instance
+	*/
+	async snapshot(opts) {
+		"use step";
+		return this.withResume(() => this.session.snapshot(opts), opts?.signal);
+	}
+	/**
+	* Update the sandbox configuration.
+	*
+	* When `ports` is provided, it is treated as the full desired port list:
+	* any currently exposed port omitted from the array will be deregistered.
+	*
+	* @param params - Fields to update.
+	* @param opts - Optional abort signal.
+	*/
+	async update(params, opts) {
+		"use step";
+		const client = await this.ensureClient();
+		let resources;
+		if (params.resources?.vcpus) resources = {
+			vcpus: params.resources.vcpus,
+			memory: params.resources.vcpus * 2048
+		};
+		const response = await client.updateSandbox({
+			name: this.sandbox.name,
+			projectId: this.projectId,
+			persistent: params.persistent,
+			resources,
+			timeout: params.timeout,
+			networkPolicy: params.networkPolicy,
+			tags: params.tags,
+			ports: params.ports,
+			snapshotExpiration: params.snapshotExpiration,
+			currentSnapshotId: params.currentSnapshotId,
+			signal: opts?.signal
+		});
+		this.sandbox = response.json.sandbox;
+		if (params.ports !== void 0 && response.json.routes) this.session?.updateRoutes(response.json.routes);
+		if (params.networkPolicy) try {
+			return await this.session?.update({ networkPolicy: params.networkPolicy }, opts);
+		} catch (err) {
+			if (isSandboxStoppedError(err) || isSandboxStoppingError(err)) return;
+			throw err;
+		}
+	}
+	/**
+	* Delete this sandbox.
+	*
+	* After deletion the instance becomes inert — all further API calls will
+	* throw immediately.
+	*/
+	async delete(opts) {
+		"use step";
+		await (await this.ensureClient()).deleteSandbox({
+			name: this.sandbox.name,
+			projectId: this.projectId,
+			signal: opts?.signal
+		});
+	}
+	/**
+	* List sessions (VMs) that have been created for this sandbox.
+	*
+	* @param params - Optional pagination parameters.
+	* @returns The list of sessions and pagination metadata.
+	*/
+	async listSessions(params) {
+		"use step";
+		const client = await this.ensureClient();
+		const fetchPage = async (cursor) => {
+			return (await client.listSessions({
+				projectId: this.projectId,
+				name: this.sandbox.name,
+				limit: params?.limit,
+				cursor,
+				sortOrder: params?.sortOrder,
+				signal: params?.signal
+			})).json;
+		};
+		return attachPaginator(await fetchPage(params?.cursor), {
+			itemsKey: "sessions",
+			fetchNext: fetchPage,
+			signal: params?.signal
+		});
+	}
+	/**
+	* List snapshots that belong to this sandbox.
+	*
+	* @param params - Optional pagination parameters.
+	* @returns The list of snapshots and pagination metadata.
+	*/
+	async listSnapshots(params) {
+		"use step";
+		const client = await this.ensureClient();
+		const fetchPage = async (cursor) => {
+			return (await client.listSnapshots({
+				projectId: this.projectId,
+				name: this.sandbox.name,
+				limit: params?.limit,
+				cursor,
+				sortOrder: params?.sortOrder,
+				signal: params?.signal
+			})).json;
+		};
+		return attachPaginator(await fetchPage(params?.cursor), {
+			itemsKey: "snapshots",
+			fetchNext: fetchPage,
+			signal: params?.signal
+		});
+	}
+};
+/**
+* A {@link Sandbox} that can automatically be disposed using a `await using` statement.
+*
+* @example
+* {
+*   await using const sandbox = await Sandbox.create();
+* }
+* // Sandbox is automatically stopped here
+*/
+var DisposableSandbox = class extends Sandbox {
+	async [Symbol.asyncDispose]() {
+		await this.stop();
+	}
+};
+
+//#endregion
+export { Sandbox };
 //# sourceMappingURL=sandbox.js.map