withruntime 0.3.1 → 0.5.0

package/dist/e2b/sandbox.js

@@ -0,0 +1,490 @@
+import { clientFor, request, } from "./client.js";
+import { Commands } from "./commands.js";
+import { guard, InvalidArgumentError, NotSupportedError, SandboxError, SandboxNotFoundError, TemplateError, } from "./errors.js";
+import { Filesystem } from "./filesystem.js";
+/* E2B's Sandbox over Runtime's. Every call is one or a few calls of the
+   withruntime SDK; nothing here speaks HTTP. What Runtime cannot do the same
+   way throws NotSupportedError before anything happens. */
+/** E2B's default machine: 2 vCPU and 512 MiB (docs.e2b.dev/billing, checked
+ * 23 September 2026). Pass `runtime: { create: { memoryMiB } }` for another. */
+export const DEFAULT_SHAPE = { vcpu: 2, memoryMiB: 512 };
+/** E2B's default sandbox timeout, 300 s. */
+export const DEFAULT_TIMEOUT_MS = 300_000;
+/** Runtime's lease bounds (MAX_TIMEOUT_SECONDS in the API). */
+const MIN_LEASE_SECONDS = 60;
+const MAX_LEASE_SECONDS = 3600;
+/** E2B template names that mean "the stock environment": Runtime's default image. */
+const STOCK_TEMPLATES = new Set(["base", "code-interpreter-v1", "code-interpreter"]);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+let warnedShortLease = false;
+function leaseSeconds(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new InvalidArgumentError(`timeoutMs must be a positive number, not ${timeoutMs}.`);
+    const seconds = Math.ceil(timeoutMs / 1000);
+    if (seconds > MAX_LEASE_SECONDS)
+        throw new NotSupportedError(`A sandbox timeout of ${timeoutMs} ms (over one hour)`, "Runtime leases last up to an hour (3_600_000 ms); call sandbox.setTimeout(...) before it ends to keep going, as often as needed.");
+    if (seconds < MIN_LEASE_SECONDS) {
+        if (!warnedShortLease && typeof process !== "undefined") {
+            warnedShortLease = true;
+            process.emitWarning(`timeoutMs ${timeoutMs} is under Runtime's shortest lease; the sandbox gets 60 s. Call kill() when done.`, { code: "RUNTIME_E2B_SHORT_TIMEOUT" });
+        }
+        return MIN_LEASE_SECONDS;
+    }
+    return seconds;
+}
+function onLeaseEnd(lifecycle) {
+    if (!lifecycle)
+        return "stop";
+    const action = typeof lifecycle.onTimeout === "string" ? lifecycle.onTimeout : lifecycle.onTimeout.action;
+    if (typeof lifecycle.onTimeout === "object" && lifecycle.onTimeout.keepMemory === false)
+        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
+    return action === "pause" ? "pause" : "stop";
+}
+function refuseCreate(opts) {
+    const refusals = [
+        [
+            "mcp",
+            "E2B's MCP gateway (mcp)",
+            "Run MCP servers yourself with commands.run(..., { background: true }).",
+        ],
+        [
+            "network",
+            "E2B's network rules (network)",
+            "Pass Runtime's rules instead: runtime: { create: { network: { internet: true, allow: [...], deny: [...] } } }.",
+        ],
+        ["iam", "E2B workload identity (iam)", "Pass credentials with envs."],
+        [
+            "volumeMounts",
+            "E2B volumes (volumeMounts)",
+            "Use a Runtime volume: runtime: { create: { volumes: [{ volumeId, path }] } }.",
+        ],
+    ];
+    for (const [field, feature, alternative] of refusals)
+        if (opts[field] !== undefined)
+            throw new NotSupportedError(feature, alternative);
+}
+/** Where a template sends the create: the stock image, a Runtime image by
+ * name or id, or a Runtime snapshot by id. */
+async function resolveTemplate(client, template) {
+    if (STOCK_TEMPLATES.has(template))
+        return {};
+    if (UUID.test(template)) {
+        try {
+            await client.images.get(template);
+            return { image: template };
+        }
+        catch (error) {
+            if (error.status !== 404)
+                throw error;
+        }
+        return { snapshot: template };
+    }
+    const page = await client.images.list({ name: template, state: "ready", limit: 1 });
+    const image = page.data[0];
+    if (image)
+        return { image: image.id };
+    const error = new TemplateError(`No Runtime image is named "${template}". E2B templates do not run on Runtime; build the same ` +
+        `environment as a Runtime image with that name and this call starts from it: ` +
+        `\`npx withruntime image build --dockerfile e2b.Dockerfile --name ${template}\`, or ` +
+        `runtime.images.build({ name: "${template}", dockerfile }).`);
+    error.code = "template_not_found";
+    throw error;
+}
+function state(runtime) {
+    const current = runtime.state;
+    if (current === "paused" || current === "pausing")
+        return "paused";
+    if (current === "stopped" || current === "stopping")
+        return "stopped";
+    return "running";
+}
+function infoOf(runtime) {
+    const info = runtime.info;
+    const templateId = typeof info.image === "string"
+        ? info.image
+        : typeof info.snapshot === "string"
+            ? info.snapshot
+            : "base";
+    const current = state(runtime);
+    return {
+        sandboxId: info.id,
+        templateId,
+        ...(info.name ? { name: info.name } : {}),
+        metadata: info.labels ?? {},
+        startedAt: new Date(info.createdAt),
+        endAt: new Date(info.expiresAt),
+        state: current === "stopped" ? "paused" : current,
+        cpuCount: info.vcpu,
+        memoryMB: info.memoryMiB,
+        envdVersion: "runtime",
+        lifecycle: {
+            onTimeout: info.onLeaseEnd === "stop" ? "kill" : "pause",
+            autoResume: info.autoWake === true,
+        },
+    };
+}
+function unsupported(feature, alternative) {
+    return Promise.reject(new NotSupportedError(feature, alternative));
+}
+/** A sandbox, with E2B's methods. `sandbox.runtime` is the Runtime sandbox
+ * underneath, for anything E2B has no name for. */
+export class Sandbox {
+    static defaultTemplate = "base";
+    files;
+    commands;
+    #client;
+    #runtime;
+    #envs;
+    #home;
+    /** Use Sandbox.create or Sandbox.connect. */
+    constructor(runtime, client, envs = {}) {
+        this.#runtime = runtime;
+        this.#client = client;
+        this.#envs = envs;
+        const ctx = {
+            envs,
+            ensureHome: (text) => this.#ensureHome(text),
+        };
+        // A getter, so the modules see the sandbox as it is after each refresh.
+        Object.defineProperty(ctx, "runtime", { get: () => this.#runtime });
+        this.files = new Filesystem(ctx);
+        this.commands = new Commands(ctx);
+    }
+    get sandboxId() {
+        return this.#runtime.id;
+    }
+    /** The Runtime sandbox underneath: previews, network, desktop, interpreter,
+     * processes, terminal and the rest of Runtime's SDK. */
+    get runtime() {
+        return this.#runtime;
+    }
+    get client() {
+        return this.#client;
+    }
+    get envs() {
+        return this.#envs;
+    }
+    /** E2B's home is /home/user and Runtime's is /workspace. The first time a
+     * path or command names /home/user, it is made a link to /workspace (unless
+     * something is already there), so paths written for E2B work. */
+    #ensureHome(text) {
+        if (this.#home || !text?.includes("/home/user"))
+            return this.#home ?? Promise.resolve();
+        this.#home = (async () => {
+            const result = await guard("sandbox", () => this.#runtime.exec("[ -e /home/user ] || sudo ln -s /workspace /home/user"));
+            if (result.exitCode !== 0 && typeof process !== "undefined")
+                process.emitWarning(`Could not link /home/user to /workspace: ${result.stderr.trim()}`, {
+                    code: "RUNTIME_E2B_HOME",
+                });
+        })();
+        return this.#home;
+    }
+    static async create(templateOrOpts, maybeOpts) {
+        const opts = (typeof templateOrOpts === "string" ? maybeOpts : templateOrOpts) ?? {};
+        const template = (typeof templateOrOpts === "string" ? templateOrOpts : opts.template) ?? this.defaultTemplate;
+        refuseCreate(opts);
+        const client = clientFor(opts);
+        const input = {
+            timeoutSeconds: leaseSeconds(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            onLeaseEnd: onLeaseEnd(opts.lifecycle),
+            // With a lifecycle, E2B resumes a paused sandbox on traffic only when
+            // asked (autoResume); Runtime's automatic wake is the same thing (0093).
+            ...(opts.lifecycle ? { autoWake: opts.lifecycle.autoResume === true } : {}),
+            ...(opts.metadata && Object.keys(opts.metadata).length ? { labels: opts.metadata } : {}),
+            ...(opts.allowInternetAccess === false ? { network: { internet: false } } : {}),
+        };
+        const source = await guard("other", () => resolveTemplate(client, template));
+        const create = {
+            // A snapshot carries its own machine; everything else gets E2B's shape.
+            ...(source.snapshot ? {} : DEFAULT_SHAPE),
+            ...input,
+            ...source,
+            ...opts.runtime?.create,
+        };
+        const runtime = await guard("sandbox", () => client.sandboxes.create(create, request(opts)));
+        return new this(runtime, client, { ...opts.envs });
+    }
+    /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
+     * `timeoutMs` moves a running sandbox's end later, never earlier. */
+    static async connect(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+        await resume(runtime, opts);
+        return new this(runtime, client);
+    }
+    /** Wakes this sandbox if it is paused. */
+    async connect(opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        await resume(this.#runtime, opts);
+        return this;
+    }
+    /** Running and paused sandboxes, a page at a time, as E2B's paginator. */
+    static list(opts = {}) {
+        return new SandboxPaginator(clientFor(opts), opts);
+    }
+    // ---- lifecycle --------------------------------------------------------
+    /** Stops the sandbox. False when it was not found or had already ended. */
+    static async kill(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        try {
+            const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+            return await stop(runtime, opts);
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    async kill(opts = {}) {
+        try {
+            return await stop(this.#runtime, opts);
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    /** Sets the sandbox to end `timeoutMs` from now. Runtime leases only move
+     * later: a shorter timeout than the one it has is refused. */
+    static async setTimeout(sandboxId, timeoutMs, opts = {}) {
+        const client = clientFor(opts);
+        const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+        await extendTo(runtime, timeoutMs, opts);
+    }
+    async setTimeout(timeoutMs, opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        await extendTo(this.#runtime, timeoutMs, opts);
+    }
+    static async getInfo(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        return infoOf(await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts))));
+    }
+    async getInfo(opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        return infoOf(this.#runtime);
+    }
+    async isRunning(opts = {}) {
+        try {
+            await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return false;
+            throw error;
+        }
+        return this.#runtime.state === "running";
+    }
+    /** Pauses the sandbox, keeping memory and files. False when it was paused. */
+    static async pause(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        return pause(await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts))), opts);
+    }
+    static betaPause(sandboxId, opts = {}) {
+        return this.pause(sandboxId, opts);
+    }
+    async pause(opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        return pause(this.#runtime, opts);
+    }
+    async betaPause(opts = {}) {
+        return this.pause(opts);
+    }
+    // ---- forks and snapshots ---------------------------------------------
+    /** Copies of this sandbox, memory and all. While Runtime's forks are
+     * switched off this throws NotSupportedError with Runtime's own words. */
+    static async fork(sandboxId, opts = {}) {
+        const { count: _count, timeoutMs: _timeoutMs, ...connection } = opts;
+        const source = await this.connect(sandboxId, connection);
+        return source.fork(opts);
+    }
+    async fork(opts = {}) {
+        if (opts.timeoutMs !== undefined)
+            // A fork's lease is Runtime's to set; one shorter than asked could not be
+            // honoured after the forks exist, so this is refused before any are made.
+            throw new NotSupportedError("A timeout for forks (fork timeoutMs)", "Fork without it, then call setTimeout(ms) on each fork.");
+        const copies = await guard("sandbox", () => this.#runtime.fork({ count: opts.count ?? 1, ...request(opts) }));
+        const Kind = this.constructor;
+        return copies.map((copy) => new Kind(copy, this.#client, { ...this.#envs }));
+    }
+    /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
+     * with Sandbox.create(snapshotId). */
+    async createSnapshot(opts = {}) {
+        const snapshot = await guard("sandbox", () => this.#runtime.snapshot({ ...(opts.name ? { name: opts.name } : {}), ...request(opts) }));
+        return { snapshotId: snapshot.id, names: snapshot.name ? [snapshot.name] : [] };
+    }
+    static async createSnapshot(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+        return new Sandbox(runtime, client).createSnapshot(opts);
+    }
+    static async deleteSnapshot(snapshotId, opts = {}) {
+        const client = clientFor(opts);
+        try {
+            await guard("other", () => client.snapshots.delete(snapshotId, request(opts)));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof SandboxError && error.statusCode === 404)
+                return false;
+            throw error;
+        }
+    }
+    // ---- ports ------------------------------------------------------------
+    /** Refused: E2B answers getHost without a call, and a Runtime port becomes
+     * reachable only once it is shared. Use getPublicHost. */
+    getHost(port) {
+        throw new NotSupportedError(`sandbox.getHost(${port}), which answers without asking the server`, `Use \`await sandbox.getPublicHost(${port})\`: it shares the port at a public HTTPS address and returns its host, as getHost does.`);
+    }
+    /** Shares `port` at a public HTTPS address (a Runtime preview) and returns
+     * its host, `<port>-<id>.<domain>`, like E2B's getHost. Anyone with the
+     * address can reach it; a browser sees a one-time page naming Runtime. */
+    async getPublicHost(port) {
+        const preview = await guard("sandbox", () => this.#runtime.previews.create(port, { visibility: "public" }));
+        return new URL(preview.url).host;
+    }
+    // ---- what Runtime does differently -----------------------------------
+    get pty() {
+        throw new NotSupportedError("E2B's pty module", "Use `await sandbox.runtime.terminal({ cols, rows, onData })` for an interactive terminal, or runtime.spawn(cmd, { pty: {} }).");
+    }
+    get git() {
+        throw new NotSupportedError("E2B's git module (deprecated by E2B too)", "Run git with sandbox.commands.run('git ...'); git is installed.");
+    }
+    /** E2B's metrics, from Runtime's measured readings (`sbx.metrics()`): CPU
+     * as a percent of the sandbox's vCPUs and resident memory, one entry per
+     * host reading (every minute by default) between `start` and `end`, kept
+     * 24 hours at that resolution. Disk use inside the sandbox is not measured:
+     * `diskUsed` is null and `diskTotal` is the disk's size. */
+    async getMetrics(opts = {}) {
+        return e2bMetrics(this.#runtime, opts);
+    }
+    static async getMetrics(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+        return e2bMetrics(runtime, opts);
+    }
+    updateNetwork() {
+        return unsupported("E2B's network rules (updateNetwork)", "Use sandbox.runtime.network.set({ internet, allow, deny }).");
+    }
+    uploadUrl() {
+        return unsupported("Signed upload URLs", "Use sandbox.files.write(path, data).");
+    }
+    downloadUrl() {
+        return unsupported("Signed download URLs", "Use sandbox.files.read(path, { format: 'bytes' }).");
+    }
+    getMcpUrl() {
+        throw new NotSupportedError("E2B's MCP gateway", "Runtime's own MCP server is `npx withruntime mcp`.");
+    }
+    getMcpToken() {
+        return unsupported("E2B's MCP gateway", "Runtime's own MCP server is `npx withruntime mcp`.");
+    }
+}
+async function resume(runtime, opts) {
+    if (opts.onResume === "reboot")
+        throw new NotSupportedError("Resuming by reboot (onResume: 'reboot')", "Runtime's wake restores memory; stop the sandbox and create a new one for a clean boot.");
+    const current = state(runtime);
+    if (current === "stopped")
+        throw new SandboxNotFoundError(`Sandbox ${runtime.id} has ended.`);
+    if (current === "paused") {
+        await guard("sandbox", () => runtime.wake({
+            ...(opts.timeoutMs === undefined ? {} : { timeoutSeconds: leaseSeconds(opts.timeoutMs) }),
+            ...request(opts),
+        }));
+        return;
+    }
+    if (opts.timeoutMs !== undefined) {
+        const later = Date.now() + opts.timeoutMs - Date.parse(runtime.info.expiresAt);
+        if (later > 1000)
+            await guard("sandbox", () => runtime.extend(Math.ceil(later / 1000), request(opts)));
+    }
+}
+async function stop(runtime, opts) {
+    if (state(runtime) === "stopped")
+        return false;
+    await guard("sandbox", () => runtime.stop({ wait: false, ...request(opts) }));
+    return true;
+}
+async function extendTo(runtime, timeoutMs, opts) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new InvalidArgumentError(`timeoutMs must be a positive number, not ${timeoutMs}.`);
+    const later = Date.now() + timeoutMs - Date.parse(runtime.info.expiresAt);
+    if (later < -1000)
+        throw new NotSupportedError("Shortening a sandbox's timeout", "Runtime leases only move later. Call kill() when the work is done.");
+    if (later > 1000)
+        await guard("sandbox", () => runtime.extend(Math.ceil(later / 1000), request(opts)));
+}
+async function pause(runtime, opts) {
+    if (opts.keepMemory === false)
+        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
+    const current = state(runtime);
+    if (current === "paused")
+        return false;
+    if (current === "stopped")
+        throw new SandboxNotFoundError(`Sandbox ${runtime.id} has ended.`);
+    await guard("sandbox", () => runtime.pause(request(opts)));
+    return true;
+}
+const RUNNING = ["starting", "running", "resuming"];
+const PAUSED = ["pausing", "paused"];
+/** E2B's paginator: `while (p.hasNext) items.push(...(await p.nextItems()))`. */
+export class SandboxPaginator {
+    #client;
+    #filter;
+    #page;
+    #hasNext = true;
+    constructor(client, opts) {
+        this.#client = client;
+        const query = opts.query ?? {};
+        if (query.template !== undefined && !STOCK_TEMPLATES.has(query.template))
+            throw new NotSupportedError("Listing by template", "Filter by metadata instead: give sandboxes a metadata key when you create them.");
+        if (query.startedAfter !== undefined)
+            throw new NotSupportedError("Listing by start time (startedAfter)", "List them all and filter on getInfo().startedAt.");
+        if (opts.order === "desc")
+            throw new NotSupportedError("Newest-first listing (order: 'desc')", "Runtime lists oldest first; reverse the list yourself.");
+        if (opts.nextToken !== undefined)
+            throw new NotSupportedError("Starting a list from a saved nextToken", "Keep the paginator and call nextItems() again.");
+        const states = query.state?.length ? query.state : ["running", "paused"];
+        this.#filter = {
+            state: states.flatMap((one) => (one === "running" ? [...RUNNING] : [...PAUSED])),
+            ...(query.metadata && Object.keys(query.metadata).length ? { labels: query.metadata } : {}),
+            ...(opts.limit ? { limit: Math.min(opts.limit, 100) } : {}),
+        };
+    }
+    get hasNext() {
+        return this.#hasNext;
+    }
+    get nextToken() {
+        return this.#page?.nextCursor ?? undefined;
+    }
+    async nextItems() {
+        if (!this.#hasNext)
+            throw new SandboxError("No more items to fetch.");
+        const previous = this.#page;
+        const page = await guard("other", async () => previous ? await previous.next() : await this.#client.sandboxes.list(this.#filter));
+        this.#page = page ?? undefined;
+        this.#hasNext = Boolean(page?.hasMore);
+        return (page?.data ?? []).map(infoOf);
+    }
+}
+async function e2bMetrics(runtime, opts) {
+    const start = opts.start === undefined ? Date.now() - 15 * 60_000 : new Date(opts.start).getTime();
+    const end = opts.end === undefined ? Date.now() : new Date(opts.end).getTime();
+    const span = Date.now() - start;
+    const range = span <= 15 * 60_000 ? "15m" : span <= 3_600_000 ? "1h" : span <= 6 * 3_600_000 ? "6h" : "24h";
+    const metrics = await runtime.metrics({ range });
+    return metrics.points
+        .filter((point) => {
+        const at = Date.parse(point.at);
+        return at >= start - metrics.stepSeconds * 1000 && at <= end && point.cpuPercent !== null;
+    })
+        .map((point) => ({
+        timestamp: new Date(point.at),
+        cpuUsedPct: point.cpuPercent,
+        cpuCount: metrics.vcpu,
+        memUsed: point.memoryBytes,
+        memTotal: metrics.memoryLimitBytes,
+        diskUsed: null,
+        diskTotal: metrics.diskLimitBytes,
+    }));
+}

package/dist/e2b/unsupported.d.ts

@@ -0,0 +1,19 @@
+/** A stand-in for an E2B export Runtime has no counterpart for. Importing it
+ * works, so a module that only mentions it still loads; calling it, building
+ * it or reading anything from it throws NotSupportedError naming the
+ * alternative. */
+export type Unsupported = {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): never;
+    readonly [key: string]: (...args: unknown[]) => never;
+};
+export declare function unsupportedExport(name: string, alternative: string): Unsupported;
+export declare const Template: Unsupported;
+export declare const TemplateBase: Unsupported;
+export declare const waitForPort: Unsupported;
+export declare const waitForURL: Unsupported;
+export declare const waitForProcess: Unsupported;
+export declare const waitForFile: Unsupported;
+export declare const waitForTimeout: Unsupported;
+export declare const Volume: Unsupported;
+export declare const Secret: Unsupported;

package/dist/e2b/unsupported.js

@@ -0,0 +1,27 @@
+import { NotSupportedError } from "./errors.js";
+export function unsupportedExport(name, alternative) {
+    const fail = () => {
+        throw new NotSupportedError(`E2B's ${name}`, alternative);
+    };
+    return new Proxy(function unsupported() { }, {
+        apply: fail,
+        construct: fail,
+        get: (_target, property) => {
+            // Let the module system, inspectors and promise checks look at it
+            // without tripping: only a real use throws.
+            if (typeof property === "symbol" || property === "then" || property === "prototype")
+                return undefined;
+            return fail();
+        },
+    });
+}
+const TEMPLATES = "Build a Runtime image instead: `npx withruntime image build --dockerfile e2b.Dockerfile --name <template>` or runtime.images.build({ name, dockerfile | recipe }), then Sandbox.create('<template>').";
+export const Template = unsupportedExport("Template builder", TEMPLATES);
+export const TemplateBase = unsupportedExport("TemplateBase", TEMPLATES);
+export const waitForPort = unsupportedExport("waitForPort (a template ready check)", TEMPLATES);
+export const waitForURL = unsupportedExport("waitForURL (a template ready check)", TEMPLATES);
+export const waitForProcess = unsupportedExport("waitForProcess (a template ready check)", TEMPLATES);
+export const waitForFile = unsupportedExport("waitForFile (a template ready check)", TEMPLATES);
+export const waitForTimeout = unsupportedExport("waitForTimeout (a template ready check)", TEMPLATES);
+export const Volume = unsupportedExport("Volume", "Use runtime.volumes (Runtime volumes) and mount one with runtime: { create: { volumes: [{ volumeId, path }] } }.");
+export const Secret = unsupportedExport("Secret", "Pass secrets as envs at create or per command, never inside the command text.");

package/dist/errors.d.ts

@@ -1,6 +1,8 @@
-/** Every failure the SDK raises. `code` is stable and machine-readable,
- * `hint` says what to do next, and `requestId` is what to quote in a report
- * (runtime.feedback.submit, `runtime feedback`, or support). */
+/** Refusals of a create that clear when a sandbox stops or pauses, or a host
+ * frees room: the trial's slots, an email domain's trial slots, the account's
+ * quota and the region's capacity. `sandboxes.create` waits them out, retrying
+ * with the same key and input, for up to `waitForCapacityMs`. */
+export declare const WAITS_FOR_ROOM: ReadonlySet<string>;
 export declare class RuntimeError extends Error {
     readonly code: string;
     readonly status: number;
@@ -21,7 +23,11 @@ export declare class RuntimeError extends Error {
         retryAfterMs?: number;
         cause?: unknown;
     });
-    /** Retrying this exact call (the SDK keeps the key) is safe and may work. */
+    /** Retrying this exact call (the SDK keeps the key) is safe and may work.
+     * True for no_capacity and trial_busy as well, which clear by themselves when
+     * a host frees room or a trial sandbox stops. `sandboxes.create` already
+     * waits for those (see `waitForCapacityMs`), so seeing one from a create
+     * means the wait ran out or was switched off. */
     get retryable(): boolean;
     toString(): string;
 }

package/dist/errors.js

@@ -1,6 +1,21 @@
 /** Every failure the SDK raises. `code` is stable and machine-readable,
  * `hint` says what to do next, and `requestId` is what to quote in a report
  * (runtime.feedback.submit, `runtime feedback`, or support). */
+/** Switched off on purpose: retrying cannot change them. */
+const DELIBERATE = new Set(["fork_unavailable", "previews_unavailable", "unavailable"]);
+/** Refusals that pass on their own: a host frees room, a trial slot frees. */
+const PASSING = new Set(["no_capacity", "trial_busy"]);
+/** Refusals of a create that clear when a sandbox stops or pauses, or a host
+ * frees room: the trial's slots, an email domain's trial slots, the account's
+ * quota and the region's capacity. `sandboxes.create` waits them out, retrying
+ * with the same key and input, for up to `waitForCapacityMs`. */
+export const WAITS_FOR_ROOM = new Set([
+    "trial_busy",
+    "trial_domain_limit",
+    "trial_capacity",
+    "quota_exceeded",
+    "no_capacity",
+]);
 export class RuntimeError extends Error {
     code;
     status;
@@ -26,13 +41,18 @@ export class RuntimeError extends Error {
         if (init.retryAfterMs !== undefined)
             this.retryAfterMs = init.retryAfterMs;
     }
-    /** Retrying this exact call (the SDK keeps the key) is safe and may work. */
+    /** Retrying this exact call (the SDK keeps the key) is safe and may work.
+     * True for no_capacity and trial_busy as well, which clear by themselves when
+     * a host frees room or a trial sandbox stops. `sandboxes.create` already
+     * waits for those (see `waitForCapacityMs`), so seeing one from a create
+     * means the wait ran out or was switched off. */
     get retryable() {
-        return (this.status === 0 ||
-            this.status === 429 ||
-            this.status === 502 ||
-            this.status === 503 ||
-            this.status === 504);
+        if (DELIBERATE.has(this.code))
+            return false;
+        // A fork asking for more copies than the trial runs at once never fits.
+        if (PASSING.has(this.code))
+            return this.details?.field !== "count";
+        return [0, 429, 502, 503, 504].includes(this.status);
     }
     toString() {
         return `${this.name} [${this.code}${this.status ? ` ${this.status}` : ""}]: ${this.message}${this.hint ? `\nHint: ${this.hint}` : ""}${this.requestId ? `\nRequest: ${this.requestId}` : ""}`;

package/dist/image-context.d.ts

@@ -0,0 +1,39 @@
+export declare const CONTEXT_LIMITS: {
+    /** The archive, compressed: what is uploaded. */
+    bytes: number;
+    files: number;
+    chunkBytes: number;
+};
+export type ContextFile = {
+    path: string;
+    sha256: string;
+    size: number;
+    mode: number;
+};
+export type PackedContext = {
+    archive: Uint8Array;
+    files: ContextFile[];
+    /** The .dockerignore that was applied, sent so the server applies it too. */
+    dockerignore?: string;
+};
+/** A .dockerignore as Docker reads it: `#` comments, `!` re-includes, `**`
+ * crosses directories, a pattern naming a directory excludes what is in it,
+ * and the last matching pattern decides. The same rules as the server's
+ * (packages/cloud/src/images/dockerfile.ts `dockerignoreFilter`). */
+export declare function dockerignoreFilter(text: string | undefined): (path: string) => boolean;
+/** The context of a folder: its .dockerignore (or `<Dockerfile>.dockerignore`)
+ * applied, `.git` left out when there is none. Symbolic links are left out:
+ * COPY reads files. */
+export declare function packContext(folder: string, options?: {
+    dockerignore?: string;
+    dockerfile?: string;
+}): Promise<PackedContext>;
+/** The archive cut into the 1 MiB chunks the server stores by digest. */
+export declare function chunkArchive(archive: Uint8Array): Promise<{
+    sha256: string;
+    size: number;
+    chunks: {
+        sha256: string;
+        bytes: Uint8Array;
+    }[];
+}>;