withruntime 0.14.0 → 0.16.1

package/dist/cli.js

@@ -24,7 +24,7 @@ Usage: runtime <product> <command> [options]      runtime <command> [options]
 
 Start
   sandboxes run [--keep] [create options] -- <command>
-                                               A fresh sandbox runs one command, then stops
+                                               A fresh sandbox runs one command, then is deleted
 
 Account
   login [--agent-name <name>] [--no-browser] [--wait]
@@ -88,6 +88,8 @@ Account
 Connect
   sandboxes ssh <id|name> [-- <command...>]    Log in over SSH; \`runtime sandboxes ssh help\` for editors
   sandboxes ssh config [--install]             Make \`ssh <id|name>.runtime\` work (VS Code, JetBrains)
+  sandboxes code <id|name> [--editor vscode|cursor|windsurf]
+                                               Open it in VS Code, Cursor or Windsurf over SSH
   sandboxes port-forward <id|name> <port|local:remote>...
                                                Forward local ports to ports in a sandbox
 
@@ -122,14 +124,17 @@ const SANDBOX_HELP = `runtime sandboxes <command>
 
   Every <id> below can also be the sandbox's name.
 
-  run [--keep] [create options] -- <command>                  A fresh sandbox runs one command, then stops
+  run [--keep] [create options] -- <command>                  A fresh sandbox runs one command, then is deleted
   ssh <id|name> [-- <command...>] | ssh config [--install]    Log in over SSH, also from VS Code and JetBrains
+  code <id|name> [--editor vscode|cursor|windsurf] [--path /workspace] [--print]
+                                                              Open it in your editor over SSH, in one step
   port-forward <id|name> <port|local:remote>...               Forward local ports to ports in it
   create [--name n] [--label k=v]... [--env K=V]... [--vcpu 2] [--memory 4096] [--disk 4096]
          [--cpu shared|reserved] [--cpu-floor <thousandths>] [--max-cost <usd>] [--max-total-cost <usd>]
          [--timeout <60-86400>] [--on-timeout pause|stop|delete] [--no-wait]
          [--no-internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
          [--image <name:tag|imageId> | --snapshot <snapshotId>] [--volume <volumeId>:/data[:snapshot]]...
+         [--spread-from <id>]...
          [--idle-pause <seconds>] [--no-auto-wake] [--persistent] [--get-or-create]
                                                               Create one; prints its id
   ls [--all] [--label k=v]... [--state running]               List (live ones unless --all)
@@ -156,12 +161,14 @@ const SANDBOX_HELP = `runtime sandboxes <command>
   switch-image <id> <image> --keep-workspace  Move it to another image, keeping /workspace (your home),
                                               volumes, env and previews; processes restart, the rest of
                                               its disk is lost (snapshot it first to keep everything)
-  resize <id> [--vcpu 2] [--memory 4096] --restart
-                                              Change its size by a restart: the whole disk stays,
-                                              programs stop (snapshot it first to keep memory)
+  resize <id> [--vcpu 2] [--memory 4096] [--disk 20480] --restart
+                                              Change its size by a restart: the whole disk stays and
+                                              --disk only grows it; programs stop (snapshot it first
+                                              to keep memory)
   extend <id> <seconds>                       Move a time limit on (one with none needs nothing)
   update <id> [--name n] [--label k=v]... [--env K=V]... [--unset-env K]... [--idle-pause <seconds>] [--auto-wake on|off]
               [--persistent on|off] [--max-total-cost <usd>|none]
+              [--timeout <60-86400 from now>|0] [--on-timeout pause|stop|delete]
                                               Change its settings; persistent keeps it running until stopped
   snapshot <id> [--name n] [--retention days|credit] Keep its whole machine; prints the snapshot id
   mount <id> <s3|r2|gcs>://<bucket>[/prefix] <path> [--secret NAME] [--region r]
@@ -179,8 +186,9 @@ const SANDBOX_HELP = `runtime sandboxes <command>
                                               Print file changes as they happen, until Ctrl-C
   mcp catalog                                 MCP servers a sandbox can run (licence, settings, hosts)
   mcp <id> start <server>... [--secret SERVER.SETTING=SECRET]... [--env SERVER.NAME=value]...
-                             [--option SERVER.NAME=value]... [--port 8765] [--replace]
+                             [--option SERVER.NAME=value]... [--port 8765] [--replace] [--public]
                                               Start them; prints each URL and the header to send
+                                              (--public: URLs that never expire, paid only)
   mcp <id> [status] | mcp <id> stop           Their state and fresh URLs; stop them
   preview <id> <port> [--public] [--ttl <s>]  Share a port at an HTTPS address (--public: paid only)
   preview rotate <id> <port>                  Refuse every token given out for a private port so
@@ -254,7 +262,7 @@ commandAfter) {
         if (arg.startsWith("--") || (arg.startsWith("-") && arg.length === 2 && !/^-\d/.test(arg))) {
             const [typed, inline] = arg.replace(/^-+/, "").split(/=(.*)/s, 2);
             // A plural of an option is the option once per comma: --hosts a,b is
-            // --host a --host b (13 October 2026: Marc's first try at a secret).
+            // --host a --host b (13 October 2026: a user's first try at a secret).
             const plural = !known.has(typed) &&
                 typed.endsWith("s") &&
                 LISTS.has(typed.slice(0, -1)) &&
@@ -428,6 +436,7 @@ const SANDBOX_MOVED = ["run", "ssh", "port-forward", "forward"];
 const SANDBOX_VERBS = [
     "run",
     "ssh",
+    "code",
     "port-forward",
     "create",
     "ls",
@@ -585,12 +594,12 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         out.error(`Warning: ${named(words.warning)}`);
     const [first, ...remaining] = words.argv;
     // Sandbox is one product of several, so its commands live under it
-    // (AGENTS.md, 23 September 2026): `runtime sandboxes run`, `sandbox ssh` and
+    // (23 September 2026): `runtime sandboxes run`, `sandbox ssh` and
     // `sandbox port-forward`. The old top-level forms were removed, not aliased.
     if (first && SANDBOX_MOVED.includes(first))
         throw usage(`\`${me} ${first}\` is now \`${me} sandboxes ${first === "forward" ? "port-forward" : first}\`.`);
     const nested = (first === "sandbox" || first === "sandboxes" || first === "sbx") &&
-        SANDBOX_MOVED.includes(remaining[0] ?? "");
+        [...SANDBOX_MOVED, "code"].includes(remaining[0] ?? "");
     const command = nested ? remaining[0] : first;
     const rest = nested ? remaining.slice(1) : remaining;
     // `runtime sandboxes create --help` is how an agent asks what a command takes:
@@ -627,7 +636,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             : `Runtime Cloud ${VERSION}. ${start}
 
   ${me} sandboxes run -- python3 < invoice.py
-                                   Run a local invoice script, then stop the sandbox
+                                   Run a local invoice script, then delete the sandbox
   ${me} sandboxes create                 A sandbox that stays; prints its id
   ${me} sandboxes exec <id> -- <command> Run in it
   ${me} help                             Everything else
@@ -649,24 +658,23 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         const onCapacityWait = waiting(out);
         const sbx = await withVolumeRelease((options) => runtime.sandboxes.create(input, { ...options, onCapacityWait }), out);
         let cleanup;
-        // SIGINT and normal completion share one stop. Keep an absolute deadline
-        // across the stop retries and final state check, so cleanup cannot hang.
+        // SIGINT and normal completion share one delete, with an absolute
+        // deadline across its retries, so cleanup cannot hang. A delete, not a
+        // stop: a stopped sandbox keeps its disk, billed, and an account without
+        // credit keeps at most 10, so ten runs that only stopped refused the
+        // eleventh (no_credit_kept_limit, 0685). --keep is how to keep one.
         const stop = () => (cleanup ??= (async () => {
             const signal = AbortSignal.timeout(30_000);
             try {
-                await sbx.stop({ wait: false, signal });
-                if (sbx.state !== "stopped")
-                    await sbx.waitFor("stopped", { timeoutSeconds: 25, signal });
-                if (sbx.state !== "stopped")
-                    throw new Error(`Sandbox is still ${sbx.state}.`);
+                await sbx.delete({ signal });
                 return true;
             }
             catch (error) {
                 out.error(describeError(new RuntimeError({
                     code: "cleanup_failed",
                     status: 0,
-                    message: `Could not confirm that sandbox ${sbx.id} stopped. ${error instanceof Error ? error.message : String(error)}`,
-                    hint: `Check it and retry cleanup with: ${me} sandboxes stop ${sbx.id}`,
+                    message: `Could not confirm that sandbox ${sbx.id} was deleted. ${error instanceof Error ? error.message : String(error)}`,
+                    hint: `Check it and retry cleanup with: ${me} sandboxes rm ${sbx.id}`,
                     cause: error,
                 }), out.json));
                 return false;
@@ -1035,6 +1043,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "ssh";
         return (await import("./ssh.js")).sshCommand(rest, env, out, () => client(env), me);
     }
+    if (nested && command === "code") {
+        product = "ssh";
+        return (await import("./ssh.js")).editorCommand(rest, env, out, () => client(env), me);
+    }
     if (command === "port-forward" || command === "forward") {
         product = "ssh";
         return (await import("./ssh.js")).portForwardCommand(rest, out, () => client(env), me);
@@ -1707,13 +1719,14 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "resize": {
-            const args = parse(rest, ["restart"], ["vcpu", "memory"]);
+            const args = parse(rest, ["restart"], ["vcpu", "memory", "disk"]);
             const sbx = await use(need(args.positional[0], `a sandbox, e.g. ${me} sandboxes resize <id> --memory 4096 --restart`));
             const size = {
                 ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
                 ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
+                ...(integer(args, "disk") !== undefined ? { diskMiB: integer(args, "disk") } : {}),
             };
-            if (size.vcpu === undefined && size.memoryMiB === undefined)
+            if (size.vcpu === undefined && size.memoryMiB === undefined && size.diskMiB === undefined)
                 throw usage(`Name a new size, e.g. ${me} sandboxes resize ${sbx.id} --memory 4096 --restart`);
             if (!args.flags.has("restart"))
                 throw usage(`A resize restarts it: its whole disk stays and its programs stop. Add --restart to say so, or snapshot it first (${me} sandboxes snapshot ${sbx.id}) to keep its memory too.`);
@@ -1852,6 +1865,8 @@ async function sandbox(argv, env, out) {
                 "auto-wake",
                 "persistent",
                 "max-total-cost",
+                "timeout",
+                "on-timeout",
             ]);
             const sbx = await get(args.positional[0]);
             const onOff = (name) => {
@@ -1862,6 +1877,9 @@ async function sandbox(argv, env, out) {
                     throw usage(`--${name} takes on or off.`);
                 return value === "on";
             };
+            const onTimeout = flag(args, "on-timeout")
+                ? oneOf(args, "on-timeout", ["pause", "stop", "delete"])
+                : undefined;
             const cost = flag(args, "max-total-cost");
             if (cost !== undefined && cost !== "none" && !/^\d+(\.\d{1,6})?$/.test(cost))
                 throw usage("--max-total-cost takes dollars, such as 25 or 2.50, or none.");
@@ -1883,9 +1901,13 @@ async function sandbox(argv, env, out) {
                     : {
                         maxTotalCostMicros: cost === "none" ? null : usdMicros(args, "max-total-cost"),
                     }),
+                ...(integer(args, "timeout") !== undefined
+                    ? { timeoutSeconds: integer(args, "timeout") }
+                    : {}),
+                ...(onTimeout === undefined ? {} : { onTimeout }),
             };
             if (!Object.keys(settings).length)
-                throw usage("Say what to change: --name, --label, --env, --unset-env, --idle-pause, --auto-wake, --persistent or --max-total-cost.");
+                throw usage("Say what to change: --name, --label, --env, --unset-env, --idle-pause, --auto-wake, --persistent, --max-total-cost, --timeout or --on-timeout.");
             await sbx.update(settings);
             print(describe(sbx.info), sbx.info);
             return 0;
@@ -2191,7 +2213,7 @@ function attachment(spec) {
  * A terminal: one line, not shown. */
 /** A pasted secret as the header it becomes: no line breaks (a token copied
  * from a terminal arrives wrapped), no bracketed-paste markers, no space at
- * either end. 13 October 2026: Marc's pasted Claude token was refused as
+ * either end. 13 October 2026: a user's pasted Claude token was refused as
  * "not visible ASCII". A header cannot hold a line break, so none is lost. */
 export function cleanSecret(raw) {
     return raw
@@ -2603,8 +2625,8 @@ Making, listing and revoking keys with a key needs one an owner or admin made.
 Every key is also at https://withruntime.com/account/keys.
 `;
 /* `runtime keys`: a key made from the terminal, by this machine's key with no
-   browser (Marc, 14 October 2026, agent swarms), or approved in the browser
-   (Marc, 23 September 2026; ARCHITECTURE.md section 10, "Keys from the
+   browser (14 October 2026), or approved in the browser
+   (23 September 2026; ARCHITECTURE.md section 10, "Keys from the
    terminal"). Only the options the keys page offers. */
 /* `runtime account`: the accounts this machine is connected to, and which one
    every command uses (ARCHITECTURE.md section 3.9). Each is its own saved
@@ -2787,7 +2809,7 @@ async function keys(argv, env, out) {
         dailyLimitMicros: limit === undefined ? null : dailyLimitMicros(limit),
     };
     /* A key on this machine makes the new one itself, with no browser: an
-       agent with no person, a swarm's coordinator (Marc, 14 October 2026). */
+       agent with no person, a swarm's coordinator (14 October 2026). */
     const saved = has(args, "browser")
         ? null
         : env.RUNTIME_API_KEY || (await connectionStore(env).read())?.key || null;
@@ -3701,6 +3723,7 @@ const CREATE_VALUES = [
     "connect",
     "image",
     "snapshot",
+    "spread-from",
     "volume",
     "env",
 ];
@@ -3728,6 +3751,18 @@ function createInput(args) {
     return {
         ...(flag(args, "image") ? { image: flag(args, "image") } : {}),
         ...(flag(args, "snapshot") ? { snapshot: flag(args, "snapshot") } : {}),
+        ...(args.flags.has("spread-from")
+            ? {
+                spreadFrom: args.flags
+                    .get("spread-from")
+                    .flatMap((value) => value.split(","))
+                    .map((id) => {
+                    if (!id.trim())
+                        throw usage("--spread-from needs a non-empty value.");
+                    return id.trim();
+                }),
+            }
+            : {}),
         ...(args.flags.has("volume") ? { volumes: args.flags.get("volume").map(attachment) } : {}),
         ...(has(args, "no-internet") || rules.length
             ? {

package/dist/client.d.ts

@@ -6,7 +6,7 @@ import { Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
 import { Transport, type RequestOptions } from "./transport.js";
 import type { CreateSandbox, DeletedSandbox, FeedbackKind, SandboxInfo, Usage } from "./types.js";
-export type { CreateOptions } from "./machine.js";
+export type { CreateOptions, LifecycleOptions } from "./machine.js";
 export type RuntimeOptions = {
     /** Default: the RUNTIME_API_KEY environment variable. */
     apiKey?: string;

package/dist/daytona/client.d.ts

@@ -40,5 +40,9 @@ export interface DaytonaConfig {
 export declare function pickKey(explicit?: string): string | undefined;
 /** The Runtime client for this configuration. */
 export declare function clientFor(config?: DaytonaConfig): Runtime;
+/** Runtime runs in one US region: a Daytona target (the client's, or a
+ * create's own since @daytona/sdk 0.224) other than "us" is refused, and
+ * none or "" means that region. */
+export declare function refuseTarget(target: string | undefined): void;
 /** Test hook: forget the cached clients. */
 export declare function resetClients(): void;

package/dist/daytona/client.js

@@ -21,9 +21,7 @@ const clients = new Map();
 export function clientFor(config = {}) {
     if (config.jwtToken !== undefined || (config.organizationId !== undefined && !config.apiKey))
         throw new NotSupportedError("Daytona JWT sign-in (jwtToken, organizationId)", "Use a Runtime key: set RUNTIME_API_KEY, or run `npx withruntime login` once.");
-    const target = config.target ?? env("DAYTONA_TARGET");
-    if (target !== undefined && target !== "" && target !== "us")
-        throw new NotSupportedError(`The Daytona target "${target}"`, 'Runtime runs in one US region; remove target or use "us".');
+    refuseTarget(config.target ?? env("DAYTONA_TARGET"));
     if (config.withruntime?.client)
         return config.withruntime.client;
     const key = pickKey(config.apiKey);
@@ -34,6 +32,13 @@ export function clientFor(config = {}) {
     }
     return client;
 }
+/** Runtime runs in one US region: a Daytona target (the client's, or a
+ * create's own since @daytona/sdk 0.224) other than "us" is refused, and
+ * none or "" means that region. */
+export function refuseTarget(target) {
+    if (target !== undefined && target !== "" && target !== "us")
+        throw new NotSupportedError(`The Daytona target "${target}"`, 'Runtime runs in one US region; remove target or use "us".');
+}
 /** Test hook: forget the cached clients. */
 export function resetClients() {
     clients.clear();

package/dist/daytona/daytona.d.ts

@@ -62,6 +62,9 @@ export type CreateSandboxBaseParams = {
     spot?: boolean;
     linkedSandbox?: string;
     secrets?: Record<string, string>;
+    /** The region for this create, over the client's target: "us" (Runtime's
+     * one region) or none; any other is refused. */
+    target?: string;
     /** Runtime-only: an explicit client, or fields for this create. */
     withruntime?: WithRuntime;
 };

package/dist/daytona/daytona.js

@@ -1,4 +1,4 @@
-import { clientFor, } from "./client.js";
+import { clientFor, refuseTarget, } from "./client.js";
 import { DaytonaError, DaytonaInvalidArgumentError, DaytonaNotFoundError, DaytonaQueueTimeoutError, guard, NotSupportedError, } from "./errors.js";
 import { RuntimeError } from "../errors.js";
 import { LEASE_MAX_SECONDS } from "../compat/lease.js";
@@ -433,6 +433,7 @@ function refuseCreate(params) {
             gpuType !== "" &&
             (!Array.isArray(gpuType) || gpuType.length > 0)))
         throw new NotSupportedError("GPUs", "Runtime runs sandboxes on CPUs; remove gpu and gpuType from resources.");
+    refuseTarget(params.target);
     if (params.volumes?.some((mount) => mount.subpath))
         throw new NotSupportedError("Mounting part of a volume (subpath)", "Mount the whole volume.");
     if (params.kvm)

package/dist/e2b/sandbox.d.ts

@@ -148,11 +148,12 @@ export declare class Sandbox {
      * deleted. */
     static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>;
     kill(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
-    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours, as E2B
-     * does; the server keeps the deadline. Runtime cannot bring an end
-     * sooner, so that is refused. A sandbox with no time limit (one on a pilot
-     * account, kept running by the server) has no end to move, and nothing
-     * changes. */
+    /** Sets the sandbox to end `timeoutMs` from now, sooner or later, up to 24
+     * hours, as E2B does: the server keeps the new time limit (an update's
+     * timeoutSeconds), and what the end does stays as created. Under a minute
+     * is a minute, Runtime's shortest limit. A sandbox with no time limit gets
+     * one; a persistent one (a pilot's, kept running by the server) has none to
+     * set, and nothing changes. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise<void>;
     setTimeout(timeoutMs: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>;
     static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>;

package/dist/e2b/sandbox.js

@@ -414,11 +414,12 @@ export class Sandbox {
             throw error;
         }
     }
-    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours, as E2B
-     * does; the server keeps the deadline. Runtime cannot bring an end
-     * sooner, so that is refused. A sandbox with no time limit (one on a pilot
-     * account, kept running by the server) has no end to move, and nothing
-     * changes. */
+    /** Sets the sandbox to end `timeoutMs` from now, sooner or later, up to 24
+     * hours, as E2B does: the server keeps the new time limit (an update's
+     * timeoutSeconds), and what the end does stays as created. Under a minute
+     * is a minute, Runtime's shortest limit. A sandbox with no time limit gets
+     * one; a persistent one (a pilot's, kept running by the server) has none to
+     * set, and nothing changes. */
     static async setTimeout(sandboxId, timeoutMs, opts = {}) {
         const client = clientFor(opts);
         const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
@@ -617,14 +618,10 @@ function secondsLater(runtime, timeoutMs) {
     return (Date.now() + timeoutMs - end) / 1000;
 }
 async function extendTo(runtime, timeoutMs, opts) {
-    checkTimeout(timeoutMs);
-    if (runtime.info.endsAt === null)
+    const seconds = timeoutSeconds(timeoutMs);
+    if (runtime.info.persistent === true)
         return;
-    const later = secondsLater(runtime, timeoutMs);
-    if (later < -1)
-        throw new NotSupportedError("Ending a sandbox sooner than its time limit (a shorter setTimeout)", "Runtime cannot bring a time limit forward. Call kill() when the work is done.");
-    if (later > 1)
-        await guard("sandbox", () => runtime.extend(Math.ceil(later), request(opts)));
+    await guard("sandbox", () => runtime.update({ timeoutSeconds: seconds }, request(opts)));
 }
 async function pause(runtime, opts) {
     if (snapshotMemory("mode", opts.mode, opts.keepMemory) === false)

package/dist/freestyle/index.d.ts

@@ -1,5 +1,5 @@
 import type { Runtime } from "../client.js";
-import type { Sandbox, Terminal } from "../sandbox.js";
+import type { Sandbox } from "../sandbox.js";
 import type { Snapshot } from "../snapshots.js";
 import { CompatibilityError, type ClientOptions, type Refused, type RefusedAsync } from "../compat/core.js";
 export { CompatibilityError };
@@ -341,7 +341,30 @@ export interface PtyAttachOptions {
     session: PtySessionSelector;
     linuxUser?: string;
 }
+export type PtyConnectionState = "connecting" | "connected" | "reconnecting" | "closed" | "exited";
+export interface PtyReconnectOptions {
+    /** Total time to recover one dropped connection. Default: five minutes. */
+    timeoutMs?: number;
+    /** Initial backoff, with 30% jitter. Default: 400ms. */
+    initialDelayMs?: number;
+    /** Backoff ceiling before jitter. Default: 10 seconds. */
+    maxDelayMs?: number;
+}
 export interface PtySessionEvents {
+    /** Reattach by itself after a dropped connection (Freestyle 0.2.18). */
+    reconnect?: boolean | PtyReconnectOptions;
+    /** Longest wait for each connection's terminal. Recovery waits at most 15
+     * seconds by default; a first connection, only when this is given. */
+    connectTimeoutMs?: number;
+    onStateChange?: (state: PtyConnectionState) => void;
+    /** Freestyle's exact replay boundaries. A Runtime terminal replays the
+     * session's output from its start on each connection without marking where
+     * the replay ends, as Freestyle's older guest agents do, so these never
+     * fire: the replay begins at the "connected" state. */
+    onReplayStart?: (info: {
+        exact: boolean;
+    }) => void;
+    onReplayEnd?: () => void;
     onData?: (data: Uint8Array) => void;
     onExit?: (exitCode: number) => void;
     onClose?: (info: {
@@ -353,25 +376,37 @@ export interface PtySessionEvents {
 }
 /** A session's number: FNV-1a of its process id, 31 bits, never 0. */
 export declare function sessionNumber(processId: string): number;
+/** A stable handle across reattachments; input is never retried or buffered.
+ * Each connection is a Runtime terminal attached to the session's process. */
 export declare class PtySession {
     #private;
-    private readonly terminal;
     private readonly sandbox;
     private readonly processId;
     readonly sessionId: number;
     readonly slug: string | undefined;
     readonly created: boolean;
-    constructor(terminal: Terminal, sandbox: Sandbox, processId: string, sessionId: number, slug: string | undefined, created: boolean, events: PtySessionEvents);
-    private readonly onError;
+    private readonly events;
+    /** Resolves once the first connection is up. */
+    readonly ready: Promise<void>;
+    constructor(sandbox: Sandbox, processId: string, sessionId: number, slug: string | undefined, created: boolean, events: PtySessionEvents, dimensions?: {
+        cols: number;
+        rows: number;
+    });
+    /** Retry now after a network change or a spent retry budget. Never opens a new shell. */
+    reconnect(): void;
+    /** Send input once. Throws while disconnected; uncertain keystrokes are never replayed. */
     write(data: Uint8Array | string): void;
+    /** Remembers the size and applies it again after a reattachment. */
     resize(options: {
         cols: number;
         rows: number;
     }): void;
     signal(sig: "sigint" | "sigkill"): void;
-    /** Closes the connection; the shell keeps running and attach() finds it. */
+    /** Cancels recovery and closes the connection; the shell keeps running and
+     * attach() finds it. */
     detach(): void;
     get readyState(): number;
+    get state(): PtyConnectionState;
 }
 export declare class VmPty {
     private readonly get;
@@ -414,6 +449,43 @@ export declare class VmLinuxUserPty {
         exitCode?: undefined;
     }>;
 }
+interface XtermDisposable {
+    dispose(): void;
+}
+interface XtermSequence {
+    prefix?: string;
+    intermediates?: string;
+    final: string;
+}
+/** The xterm.js surface connectXterm uses; xterm itself is not a dependency. */
+export interface XtermTerminal {
+    cols: number;
+    rows: number;
+    write(data: string | Uint8Array, callback?: () => void): void;
+    onData(listener: (data: string) => void): XtermDisposable;
+    onResize(listener: (size: {
+        cols: number;
+        rows: number;
+    }) => void): XtermDisposable;
+    parser: {
+        registerCsiHandler(id: XtermSequence, handler: () => boolean): XtermDisposable;
+        registerDcsHandler(id: XtermSequence, handler: () => boolean): XtermDisposable;
+    };
+}
+export type ConnectXtermOptions = PtyOpenOptions & PtySessionEvents & {
+    pty: VmPty | VmLinuxUserPty;
+    terminal: XtermTerminal;
+    slug: string;
+};
+/** Freestyle 0.2.18's connectXterm: xterm.js on a named session that
+ * reattaches by itself unless `reconnect: false`. Each connection replays the
+ * session's output from its start, so the screen is reset first and the
+ * replay's terminal queries go unanswered until it has been written (150ms
+ * quiet, at most 2 seconds). dispose() detaches; the shell keeps running. */
+export declare function connectXterm({ pty, terminal, ...options }: ConnectXtermOptions): Promise<{
+    session: PtySession;
+    dispose(): void;
+}>;
 export declare class VmLinuxUser {
     private readonly vm;
     private readonly linuxUser;