promigence 0.1.0-beta.12

package/dist/sdk/sandbox.d.ts

@@ -0,0 +1,537 @@
+/**
+ * `Sandbox`: a simple class for one sandbox (create, connect, commands.run, files, pty, fork, kill).
+ *
+ * `import { Sandbox } from '@promigence/sdk'` gives the familiar call shape; a call outside the
+ * supported set throws `UnsupportedError` naming the Promigence alternative.
+ *
+ * Mapping: a sandbox is a **fork of 1** from a verified snapshot — `Sandbox.create(snapshot)`
+ * is `POST /runs {count: 1}` resolved when the sandbox is ready; `allowInternetAccess: false`
+ * → `network: none`; `metadata` → run labels; `timeoutMs` → the sandbox timeout (billed per
+ * second used). Spend cap: `opts.spendCap` > `PROMIGENCE_SPEND_CAP` > `GET /me.default_spend_cap`.
+ */
+import { inspect, type InspectOptions } from "node:util";
+import { type CommandResult, type CommandRunOpts, type ForkOpts, type OptimizeFor, type SandboxOpts, type Tier } from "./core.js";
+import { PromigenceClient, type BackgroundExecRecord, type DirEntry, type DirListOpts, type ExtractResult, type FileInfo, type FileMatch, type Page, type PortRecord, type AutoPauseMode, type SandboxRecord, type SearchOpts, type SecretBinding, type SnapshotBuild, type VerifySpec } from "./client.js";
+import { CommandHandle } from "./handles.js";
+import type { PtyExit, PtySession, PtySize } from "./pty.js";
+/**
+ * `commands.run` options for a foreground command. The call resolves with the whole result when
+ * the command ends; `onStdout` / `onStderr` also receive its output as it is written.
+ */
+export interface ForegroundRunOpts extends CommandRunOpts {
+    background?: false;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+}
+/** `commands.run` options for a background command: output callbacks instead of a result. */
+export interface BackgroundRunOpts extends CommandRunOpts {
+    background: true;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    /**
+     * Keep standard input open, so the handle's `sendStdin` / `closeStdin` reach the process.
+     *
+     * Has to be decided here: a child's stdin cannot be opened once it has been spawned, so
+     * without it the process reads /dev/null for its whole life and a later write is refused.
+     */
+    stdin?: boolean;
+}
+/** `Sandbox.list` / `Sandbox.listPage`: the client-side half of `SandboxListOptions`. */
+export interface SandboxListStaticOpts {
+    client?: PromigenceClient;
+    limit?: number;
+    labels?: Record<string, string>;
+    state?: string[];
+    cursor?: string;
+}
+/** One running command, from `commands.list()`. `pid` is the `exec_id`. */
+export interface ProcessInfo {
+    pid: string;
+    cmd: string;
+    state: BackgroundExecRecord["state"];
+    exitCode?: number;
+}
+/** One file or directory, from `files.list()`. */
+export interface EntryInfo {
+    name: string;
+    path: string;
+    type: "file" | "dir";
+    size: number;
+    /** Numeric mode bits (`0o100644`). */
+    mode: number;
+    /** `rwxr-xr-x`. */
+    permissions: string;
+    modifiedTime: Date;
+    /** `lstat`, not `stat`: a symlink is reported as one and not followed. */
+    isSymlink: boolean;
+}
+export interface PtyCreateOpts extends Partial<PtySize> {
+    /** Terminal output, as bytes. */
+    onData?: (data: Uint8Array) => void;
+    onExit?: (exit: PtyExit) => void;
+    /** Working directory for the shell. */
+    cwd?: string;
+    /**
+     * Plain environment variables, composed into the command as `export K=v;`.
+     *
+     * **Do not put a credential here.** Use `secrets` — the value is then resolved server-side
+     * and never appears in the command text at all. `envs` is for the things you would not mind
+     * seeing in `ps`.
+     */
+    envs?: Record<string, string>;
+    /**
+     * Stored secret names, or `{ name, as }` bindings, put into the terminal's environment by the
+     * server. The value never leaves the service and is never part of the command.
+     */
+    secrets?: SecretBinding[];
+    /** What to run instead of the login shell. */
+    cmd?: string;
+    /** Handshake bound (default 30 s). */
+    timeoutMs?: number;
+    /**
+     * When the connection drops, or the service is updated, the same terminal is picked up again
+     * over a new connection, where it left off: the same shell or command, still running.
+     * Default: on.
+     */
+    resume?: boolean;
+    /**
+     * When the service is updated and the terminal cannot be picked up again, the session goes on
+     * over a new connection in a NEW shell (what ran in the old one has ended), with its callbacks
+     * and its size, for up to 30 s of trying; past that it ends with `error.code`
+     * `"service_restart"`. Default: on for the login shell, off with `cmd` (reconnecting would start
+     * the command again).
+     */
+    reconnect?: boolean;
+    /** Called after each reconnect: `resumed` says whether it is the same terminal or a new shell. */
+    onReconnected?: (how: {
+        resumed: boolean;
+    }) => void;
+}
+/** The default terminal command. */
+export declare const DEFAULT_PTY_CMD = "TERM=${TERM:-xterm-256color} exec /bin/sh -l";
+/** POSIX single-quote one word for `sh`. */
+export declare function shellQuote(s: string): string;
+/**
+ * The one `cmd` the terminal route takes, with `cwd` and `envs` composed in front of it.
+ * `undefined` when there is nothing to compose, so the default applies.
+ */
+export declare function ptyCommand(opts: {
+    cmd?: string;
+    cwd?: string;
+    envs?: Record<string, string>;
+}): string | undefined;
+export declare function toEntryInfo(e: DirEntry): EntryInfo;
+/**
+ * `mkdir` / `move` / `copy` / `chmod` answer with a path and no name, because the path is what
+ * the caller named. `EntryInfo` has both, so the basename is filled in here rather than left
+ * empty: a handle that returns half a record for four of its verbs is a handle nobody can write
+ * one loop against.
+ */
+export declare function toEntryInfoFromPath(f: FileInfo): EntryInfo;
+export interface SandboxCreateOpts extends SandboxOpts {
+    /** Reuse an existing client (tests, or one client per process). */
+    client?: PromigenceClient;
+    /** `snap_<id>` | `<alias>` | `<alias>@<commit7>`; the same as the first argument. */
+    snapshot?: string;
+    /**
+     * A container image instead of a snapshot — a tag (`python:3.12`, pinned to its digest by the
+     * API) or `registry/name@sha256:<64 hex>`: the snapshot of this image is built on first use
+     * (a new build is billed per second while it runs, at its tier's rate, `client.pricing()`; pass
+     * `allowBuild: true` to allow it) and
+     * reused after (same digest + same inputs → the same snapshot). A name with no tag or digest is
+     * refused: it would pin whatever `:latest` is today. The fields below shape that snapshot and
+     * are ignored without `image`.
+     */
+    image?: string;
+    setup?: string[];
+    /** Without it the image snapshot is stored `verified: false`. */
+    verify?: VerifySpec;
+    /** A background process started before the snapshot, so every fork inherits it running. */
+    start?: string | string[];
+    tier?: Tier;
+    alias?: string;
+    /** Name of a stored secret holding the registry credentials. */
+    registrySecret?: string;
+    /** Bound on the first build of an image (default 15 min). Expiry cancels nothing. */
+    buildTimeoutMs?: number;
+    /**
+     * Let `Sandbox.create({ image })` build the image's snapshot when none exists yet. A new build
+     * is billed per second while it runs, at most `build_price` (your plan's rates, `client.pricing()`);
+     * reusing a snapshot already built is free. Without it, a create from an image is refused before anything is sent: whether the
+     * image's snapshot exists is only known once a build is submitted, and a submitted build cannot
+     * be withdrawn. The other way to pay once and on purpose: `promigence snapshot create --image
+     * REF --alias NAME`, then `Sandbox.create("NAME")`.
+     */
+    allowBuild?: boolean;
+    /**
+     * Called with the `POST /snapshots` answer before any wait: `build_price` (the most the build can
+     * cost) and `per_second_usd`, and `deduped` or `joined` when nothing new is charged. Without it,
+     * a new build's price is reported as a process warning (stderr) before the build is waited for.
+     */
+    onBuild?: (build: SnapshotBuild) => void | Promise<void>;
+    /**
+     * Abort the create. Whatever it had started is ended (nothing is left running, or billed, for
+     * nobody), then it rejects with `TimeoutError` ("aborted by the caller's signal").
+     */
+    signal?: AbortSignal;
+    /**
+     * Stored secrets the sandbox receives, as environment variables: a name binds the secret to a
+     * variable of the same name, `{ name, as }` to a different one. Every command run against the
+     * sandbox gets them. As `Sandbox.fork` takes them.
+     */
+    secrets?: SecretBinding[];
+    /**
+     * The only destinations the sandbox may reach: `["github.com", "*.npmjs.org"]`. Everything
+     * else is refused, and the refusal names the host. It wins over `allowInternetAccess`. As
+     * `Sandbox.fork` takes it.
+     */
+    allowHosts?: string[];
+    /** What to favour, `start` or `compute`. As `Sandbox.fork` takes it. */
+    optimizeFor?: OptimizeFor;
+}
+/**
+ * Create-or-reuse the snapshot for an image digest and return its `snapshot_id`.
+ *
+ * `POST /snapshots {image}` answers 200 with the existing snapshot when this digest (with the same
+ * inputs) was built before, or 202 with a `build_id`. The **body**, not the status, decides: an
+ * idempotency replay answers 202 with a document that may already be `verified`.
+ */
+export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
+    /**
+     * The `POST /snapshots` answer, before any wait: `build_price` (the most it can cost) and
+     * whether it was `deduped` or `joined` (nothing new charged). An implicit build costs money, so a caller that prints prices prints this one too.
+     */
+    onBuild?: (build: SnapshotBuild) => void | Promise<void>;
+    /** Ends the wait for a build at once; the build itself, once submitted, is not withdrawn. */
+    signal?: AbortSignal;
+}): Promise<string>;
+/** `sandbox.fork()` options: `onReady` is handed each new `Sandbox`. */
+export type SandboxInstanceForkOpts = Omit<ForkOpts, "onReady"> & {
+    onReady?: (sandbox: Sandbox, index: number) => void;
+};
+export interface SandboxForkOpts extends Omit<ForkOpts, "onReady"> {
+    /** Called with each `Sandbox` as it becomes ready. */
+    onReady?: (sandbox: Sandbox, index: number) => void;
+    client?: PromigenceClient;
+    apiKey?: string;
+    apiUrl?: string;
+    spendCap?: number;
+    timeoutMs?: number;
+    metadata?: Record<string, string>;
+    /**
+     * Stored secrets every sandbox of this fork receives, as environment variables.
+     *
+     * A string binds a secret to a variable of the same name; `{ name, as }` binds it to a
+     * different one — which is how a pool of workers each hold their own value for one variable:
+     *
+     * ```ts
+     * await Sandbox.create({ secrets: [{ name: `work_secret_${i}`, as: "ANTHROPIC_WORK_SECRET" }] });
+     * ```
+     *
+     * Every command run against the sandbox gets them, background execs included, so a
+     * credentialed worker does not have to hold a streaming exec open for its whole life.
+     */
+    secrets?: SecretBinding[];
+    allowInternetAccess?: boolean;
+    /**
+     * The only destinations this sandbox may reach: `["github.com", "*.npmjs.org"]`. Everything
+     * else is refused, and the refusal names the host rather than hanging.
+     *
+     * What it is, so you can decide whether it is enough: the runtime resolves the names you list
+     * and permits exactly the addresses they answer with, for as long as their TTL says. That is
+     * an address-level fence gated on names, not enforcement at the TLS layer — a host sharing an
+     * address with one you allowed is reachable.
+     */
+    allowHosts?: string[];
+    optimizeFor?: OptimizeFor;
+}
+interface SandboxInit {
+    sandboxId: string;
+    runId: string;
+    snapshot: string;
+    client: PromigenceClient;
+    envs?: Record<string, string>;
+    timeoutMs?: number;
+}
+/**
+ * The snapshot `Sandbox.create()` forks when it is given none: Debian 12 + Python 3.12 (pip, venv, uv),
+ * Node 24 (npm), Bun, Go 1.27, Docker, git, Git LFS, the GitHub CLI, curl, jq, ripgrep, rsync, gcc/make,
+ * and the Claude Code, Codex, Gemini CLI and OpenCode agents, `small` tier (built in, not verified). It
+ * is always ready to start. The template name `'base'` means the same thing.
+ */
+export declare const DEFAULT_SNAPSHOT = "promigence/base";
+/**
+ * `opts.spendCap` > `PROMIGENCE_SPEND_CAP`, or `undefined` for "the org default".
+ *
+ * Deliberately no `GET /me`: the API already applies the org's `default_spend_cap` to a run that
+ * names none, so asking first would only add a round trip to every `Sandbox.create()`.
+ */
+export declare function spendCapFromEnv(spendCap?: number): number | undefined;
+/** `opts.spendCap` > `PROMIGENCE_SPEND_CAP` > `GET /me.default_spend_cap`; none → InvalidArgumentError. */
+export declare function resolveSpendCap(client: PromigenceClient, spendCap?: number): Promise<number>;
+export declare class Sandbox {
+    #private;
+    readonly sandboxId: string;
+    /** The run this sandbox belongs to (`promigence run report <run_id>`). */
+    readonly runId: string;
+    /** The snapshot this sandbox was forked from — the origin for `fork()`. */
+    readonly snapshot: string;
+    /** Not `readonly`: `setTimeout` moves it, and later `commands.run` calls inherit it. */
+    private timeoutMs;
+    /** Any exec / write makes the sandbox dirty: `fork()` then needs `{fromOrigin: true}`. */
+    private dirty;
+    readonly commands: {
+        run(cmd: string, opts: BackgroundRunOpts): Promise<CommandHandle>;
+        /**
+         * Run `cmd` and resolve with its result. A non-zero exit throws `CommandExitError`; a command
+         * killed at its own `timeoutMs` throws `CommandTimeoutError` (a `CommandExitError` too).
+         */
+        run(cmd: string, opts?: ForegroundRunOpts): Promise<CommandResult>;
+        /** Background commands in this sandbox (running and ended, until killed with forget). */
+        list(): Promise<ProcessInfo[]>;
+        /** SIGKILL a background command. `false` if it had already ended. */
+        kill(pid: string): Promise<boolean>;
+        /** Re-attach to a background command; output is replayed from its first byte. */
+        connect(pid: string, opts?: Pick<BackgroundRunOpts, "onStdout" | "onStderr">): Promise<CommandHandle>;
+        /**
+         * Write to a background command's stdin, by pid. The handle's own `sendStdin` is the same
+         * call; this spelling exists because a caller who only kept the pid should not have to
+         * `connect()` first just to write a line.
+         */
+        sendStdin(pid: string, data: string | Uint8Array): Promise<number>;
+        /** Close its stdin (EOF). `sort`, `cat` and every REPL do nothing until this arrives. */
+        closeStdin(pid: string): Promise<void>;
+    };
+    /**
+     * Interactive terminals (`sandbox.pty`). `create` resolves once the terminal exists;
+     * the returned session's `pid` is what `sendInput` / `resize` / `kill` address.
+     */
+    readonly pty: {
+        create(opts?: PtyCreateOpts): Promise<PtySession>;
+        sendInput(pid: number, data: Uint8Array | string): Promise<void>;
+        resize(pid: number, size: PtySize): Promise<void>;
+        kill(pid: number): Promise<boolean>;
+    };
+    /** Preview URLs for ports inside the sandbox (`getHost` gives the address alone). */
+    readonly ports: {
+        expose(port: number): Promise<PortRecord>;
+        list(): Promise<PortRecord[]>;
+        /** A token revokes that URL; a port number every URL for it. Returns the revoked tokens. */
+        revoke(tokenOrPort: string | number): Promise<string[]>;
+    };
+    /** Terminals opened from this object, by pid: a terminal belongs to its connection. */
+    private readonly terminals;
+    readonly files: {
+        read(path: string, opts?: {
+            format?: "text";
+        }): Promise<string>;
+        read(path: string, opts: {
+            format: "bytes";
+        }): Promise<Uint8Array>;
+        /**
+         * Text is written as UTF-8; bytes as they are (a typed array, an `ArrayBuffer` or a `Blob`).
+         * A file that already exists keeps its mode, as a shell `>` or an editor's save does; a new
+         * one is `0o644`. `{ mode: 0o755 }` sets the mode either way.
+         */
+        write(path: string, data: string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob, opts?: {
+            mode?: number;
+        }): Promise<void>;
+        remove(path: string, opts?: {
+            recursive?: boolean;
+        }): Promise<void>;
+        exists(path: string): Promise<boolean>;
+        list(path?: string, opts?: DirListOpts): Promise<EntryInfo[]>;
+        mkdir(path: string, opts?: {
+            mode?: number | string;
+            parents?: boolean;
+        }): Promise<EntryInfo>;
+        move(from: string, to: string, opts?: {
+            overwrite?: boolean;
+        }): Promise<EntryInfo>;
+        /** Another name for `move`. Same call. */
+        rename(from: string, to: string, opts?: {
+            overwrite?: boolean;
+        }): Promise<EntryInfo>;
+        copy(from: string, to: string, opts?: {
+            recursive?: boolean;
+            overwrite?: boolean;
+        }): Promise<EntryInfo>;
+        chmod(path: string, opts: {
+            mode?: number | string;
+            uid?: number;
+            gid?: number;
+            recursive?: boolean;
+        }): Promise<EntryInfo>;
+        search(path: string, opts: SearchOpts): Promise<FileMatch[]>;
+        downloadDir(path: string, opts?: {
+            exclude?: string[];
+        }): Promise<Uint8Array>;
+        uploadDir(tar: Uint8Array, into: string, opts?: {
+            strip?: number;
+        }): Promise<ExtractResult>;
+    };
+    protected constructor(init: SandboxInit);
+    /**
+     * Fork of 1 from a snapshot (`snap_<id>` | `<alias>` | `<alias>@<commit7>`), or from the
+     * snapshot of an image: `Sandbox.create({ image: 'python:3.12', allowBuild: true })` builds it
+     * on first use (a new build billed per second at its tier's rate, bounded by `buildTimeoutMs`, default 15 min) and reuses it
+     * free after. An image needs `allowBuild: true` and a tag or digest; without either it is
+     * refused before any request.
+     *
+     * A create still queued when `waitTimeoutMs` runs out throws `TimeoutError` and leaves nothing
+     * behind: its run is cancelled, so the sandbox cannot start later with nobody holding it. Any
+     * other failure of the wait cancels the run the same way and throws what the wait threw.
+     */
+    static create(opts?: SandboxCreateOpts): Promise<Sandbox>;
+    static create(snapshotIdOrAlias?: string, opts?: SandboxCreateOpts): Promise<Sandbox>;
+    /** `Sandbox.fork(snapshot, {count})` — resolves when every handle is ready. */
+    static fork(snapshotIdOrAlias: string, opts?: SandboxForkOpts): Promise<Sandbox[]>;
+    /**
+     * Native form of `fork`: `POST /runs` returns immediately and each handle resolves as its
+     * sandbox becomes ready.
+     */
+    static forkHandles(snapshotIdOrAlias: string, opts?: SandboxForkOpts): Promise<{
+        runId: string;
+        handles: Array<Promise<Sandbox>>;
+    }>;
+    /**
+     * `forkHandles`, plus what `create` needs to end a run it was interrupted starting: the key the
+     * create is sent under, a signal for it and its waits, and the start options as sent.
+     */
+    private static forkHandlesWith;
+    /** Attach to a running sandbox (`GET /sandboxes/:id`). */
+    static connect(sandboxId: string, opts?: SandboxCreateOpts): Promise<Sandbox>;
+    /**
+     * `GET /sandboxes?limit=[&labels=][&state=][&cursor=]` — this org's sandboxes, newest first.
+     *
+     * A plain array: every caller iterates it, and that is the shape that keeps working. The page
+     * behind it — the cursor to the next one — is [`listPage`].
+     */
+    static list(opts?: SandboxListStaticOpts): Promise<SandboxRecord[]>;
+    /**
+     * One page, with the cursor that follows it: `{ items, nextCursor, limit }`.
+     *
+     * `nextCursor` is `null` on the last page and **that is the only stop condition** — a short
+     * page is not one, because `labels` and `state` are filtered server-side and can empty a page
+     * that still has successors. `labels` filtering is why this exists at all: `limit` bounds the
+     * rows the server *reads*, so filtering the returned array cannot see a session's sandbox
+     * older than the first page, which is what made "find it or fork it" unwritable against us.
+     */
+    static listPage(opts?: SandboxListStaticOpts): Promise<Page<SandboxRecord>>;
+    /**
+     * Forks the **origin snapshot** this sandbox started from. To fork the sandbox as it is now,
+     * take a live snapshot (`client.sandboxes.snapshot(sandboxId)`) and `Sandbox.fork()` that.
+     */
+    fork(opts?: SandboxInstanceForkOpts): Promise<Sandbox[]>;
+    /**
+     * What `JSON.stringify` shows: the ids. The client, its API key and the create-time `envs` are
+     * private fields, so a logger, an error tracker or a tool result that serialises the sandbox
+     * never carries them.
+     */
+    toJSON(): {
+        sandboxId: string;
+        runId: string;
+        snapshot: string;
+    };
+    /** What `console.log` / `util.inspect` show: the same as `toJSON`. */
+    [inspect.custom](_depth: number, opts: InspectOptions): string;
+    /** `DELETE /sandboxes/:id`. */
+    /** End the sandbox. `false` when it had already ended (the API answers `already_ended`). */
+    kill(): Promise<boolean>;
+    /** `GET /sandboxes/:id`. */
+    getInfo(): Promise<SandboxRecord>;
+    /**
+     * `POST /sandboxes/:id/probe` — is this environment still the one that was verified?
+     *
+     * `first_bad_path` is the **first differing path**, which is the only actionable part.
+     */
+    probe(opts?: {
+        paths?: string[];
+    }): Promise<{
+        sandbox_id: string;
+        ok: boolean;
+        ms: number;
+        checked: string | string[];
+        first_bad_path?: string | null;
+    }>;
+    isRunning(): Promise<boolean>;
+    /**
+     * `PATCH /sandboxes/:id` — extend this sandbox's timeout.
+     *
+     * The timeout is the sandbox's total lifetime, not "from now", and the difference is billing:
+     * commits *seconds* up front and `billable_seconds <= committed_seconds`, so an extension is a new
+     * commitment that has to fit under the spend cap you set (the run's, or the org default). It throws
+     * `SpendCapError` (409) rather than silently extending — which is the behaviour a spend
+     * cap exists to produce, and the one difference here worth a caller knowing about.
+     */
+    setTimeout(ms: number): Promise<void>;
+    /**
+     * Pause this sandbox once it has been idle for `seconds`; `0` means it never does.
+     *
+     * It is the cheap half of a spend cap: the timeout is the bound you committed to, this is what
+     * stops you spending it on a session nobody is driving. A command still running counts as
+     * busy, so a long build is never cut short by it, and the server keeps a floor under how short
+     * the window may be. Bring it back with `resume()`, which is the warm path.
+     *
+     * `mode: "activity"` is for an agent that runs inside the sandbox on its own: it also waits
+     * until nothing inside has used CPU, moved a byte or held a connection open for the window
+     * (`AutoPauseMode`). Omitted, the mode is left as it is (`"requests"` unless set).
+     */
+    setAutoPause(seconds: number, mode?: AutoPauseMode): Promise<void>;
+    /** The idle rule in force: seconds before it pauses itself, `0` when it never does. */
+    getAutoPause(): Promise<number>;
+    /**
+     * Cut this sandbox's egress, now. Nothing it runs afterwards can reach the network.
+     *
+     * The sequence this is for: fork with the network on, install what the task needs, call this,
+     * *then* let the agent run. The policy used to be fixed at fork, so an eval harness that wanted
+     * a network for setup and none for the rollout had to choose one of the two.
+     *
+     * There is no matching `enableInternet`. Egress goes one way — a sandbox that could re-open
+     * its own network on request is not one whose egress you can reason about.
+     */
+    disableInternet(): Promise<void>;
+    /**
+     * The preview address for `port`, **without a scheme**, so callers write
+     * `` `https://${host}` ``. The address may be plain `http://`; `ports.expose(port)` returns the
+     * full `url` with its scheme.
+     *
+     * Async, because the address is a capability minted on demand rather than
+     * a hostname derived from the id. An existing URL for the port is reused, not re-minted.
+     */
+    getHost(port: number): Promise<string>;
+    /**
+     * Pause this sandbox. From the answer on it bills no seconds and holds no capacity. Its files
+     * and memory are kept until `resume()` or `kill()`, and `resume()` brings it back as it was.
+     *
+     * Background execs (started with `background: true`) end at the pause: their exec ids answer
+     * not found after `resume()`, and `backgroundExecsKilled` says how many. Anything else you
+     * started keeps running when the sandbox resumes.
+     *
+     * A pause can take seconds on a large, busy sandbox and under a second on a small, quiet one;
+     * `pauseMs` (also `tookMs`) is how long it took. `resume()` is the fast half; its `resumeMs`
+     * (also `tookMs`) is how long that took.
+     */
+    pause(): Promise<{
+        pausedId: string;
+        tookMs?: number;
+        pauseMs?: number;
+        bytes?: {
+            allocated: number;
+        };
+        alreadyPaused?: boolean;
+        backgroundExecsKilled?: number;
+        warnings?: string[];
+    }>;
+    /**
+     * Bring a paused sandbox back, as it was when it was paused. Typically well under a second.
+     * `optimizeFor` left out keeps the sandbox's own setting.
+     */
+    resume(opts?: {
+        optimizeFor?: OptimizeFor;
+    }): Promise<{
+        tookMs?: number;
+        resumeMs?: number;
+    }>;
+}
+export {};