@namzu/sandbox 14.0.0 → 15.0.0

package/dist/backends/firecracker/transport.d.ts

@@ -52,8 +52,8 @@
  * socket to be silently severed by a resume), which makes the
  * transport resume-survivable by construction.
  */
-import type { OpenTerminalOptions, SandboxExecOptions, SandboxExecResult, SandboxTcpConnectOptions, SandboxTcpConnection, TerminalSession } from '@namzu/sdk';
-import { type AgentRequestCredential, type ExecRequest, type ReadFileRequest, type TcpConnectRequest, type TerminalOpenRequest, type WriteFileRequest } from './protocol.js';
+import type { OpenTerminalOptions, SandboxExecOptions, SandboxExecResult, SandboxReadFileOptions, SandboxTcpConnectOptions, SandboxTcpConnection, TerminalSession } from '@namzu/sdk';
+import { type AgentRequestCredential, type AttachSessionRequest, type ExecRequest, type FlushRequest, type GuestReplyIdentity, type KillSessionRequest, type QuiesceRequest, type ReadFileRequest, type ReadFileStreamRequest, type StartDetachedRequest, type TcpConnectRequest, type TerminalOpenRequest, type TerminalReadyEvent, type WriteFileRequest } from './protocol.js';
 /**
  * An addressable agent endpoint. The orchestrator hands one of these
  * back per sandbox (`create()` response → `vsock endpoint`).
@@ -164,23 +164,52 @@ export type AgentRequest = ({
     readonly body: ExecRequest;
 } | {
     readonly op: 'reserve-execution';
+    readonly body?: {
+        readonly executionId: string;
+    };
 } | {
     readonly op: 'cancel-execution';
     readonly body: {
         readonly executionId: string;
     };
+} | {
+    readonly op: 'attach-execution';
+    readonly body: {
+        readonly executionId: string;
+        readonly fromOffset?: number;
+    };
 } | {
     readonly op: 'read-file';
     readonly body: ReadFileRequest;
+} | {
+    readonly op: 'read-file-stream';
+    readonly body: ReadFileStreamRequest;
 } | {
     readonly op: 'write-file';
     readonly body: WriteFileRequest;
 } | {
     readonly op: 'terminal';
     readonly body: TerminalOpenRequest;
+} | {
+    readonly op: 'attach-session';
+    readonly body: AttachSessionRequest;
+} | {
+    readonly op: 'start-detached';
+    readonly body: StartDetachedRequest;
+} | {
+    readonly op: 'list-sessions';
+} | {
+    readonly op: 'kill-session';
+    readonly body: KillSessionRequest;
 } | {
     readonly op: 'tcp-connect';
     readonly body: TcpConnectRequest;
+} | {
+    readonly op: 'quiesce';
+    readonly body: QuiesceRequest;
+} | {
+    readonly op: 'flush';
+    readonly body: FlushRequest;
 } | {
     readonly op: 'healthz';
 }) & AgentRequestCredential;
@@ -199,6 +228,23 @@ export interface VsockTransportOptions {
      * against the agent's fresh listen socket. Default 60000ms.
      */
     readonly readIdleTimeoutMs?: number;
+    /**
+     * Interval, in milliseconds, of the per-stream liveness heartbeat on
+     * `openTerminal` and `openTcpConnection`. See `protocol.ts`'s
+     * `StreamHeartbeat` for the negotiation and what a heartbeat does and
+     * does not prove.
+     *
+     * **Undefined by default, and deliberately so.** This transport is
+     * shared with the Firecracker tier, where a default would force-close an
+     * existing consumer's quiet-but-alive terminal after three intervals —
+     * a changed default for a tier that asked for nothing. The Kubernetes
+     * backend opts in (`backends/kubernetes/index.ts`'s
+     * `DEFAULT_STREAM_HEARTBEAT_MS`); every other caller that passes nothing
+     * sends and expects exactly the frames it always did.
+     *
+     * A value of `0` or less is the same as leaving it out.
+     */
+    readonly heartbeatMs?: number;
     /**
      * Fires once per successful dial with how long the connect took, in
      * milliseconds. Never fires with the handle's `token` or any request
@@ -208,6 +254,92 @@ export interface VsockTransportOptions {
      * vsock/mtls/unix arms are free to ignore it.
      */
     readonly onDial?: (durationMs: number) => void;
+    /**
+     * Fires once per connect ATTEMPT, immediately before it is made, and
+     * carries nothing at all.
+     *
+     * {@link onDial} above only ever fires for an attempt that SUCCEEDED, and
+     * a caller that has to know a socket was never established cannot learn
+     * it from the attempt's error either: an attempt can be aborted — by its
+     * caller, or by a deadline shorter than {@link connectTimeoutMs} — before
+     * it has failed, and the abort is what the caller is then holding. Paired
+     * with `onDial`, this says "a dial was attempted and none of them handed
+     * back a socket", which on the `tcp` arm is exactly "nothing reached the
+     * guest": that arm resolves only on the socket's own `connect` event, so
+     * no byte can have been sent before `onDial` fired.
+     *
+     * Used by the kubernetes backend's `KubernetesAgentTransport` to decide
+     * whether a failed `exec()` may be retried against a replaced pod. The
+     * vsock/mtls/unix arms are free to ignore it.
+     */
+    readonly onDialAttempt?: () => void;
+    /**
+     * Fires once for every reply this transport reads that the guest
+     * answered on an AUTHENTICATED basis — one control/file reply per
+     * `request`, and the opening `ready` frame of a terminal, a session
+     * attachment or a TCP stream.
+     *
+     * It carries the reply itself, read only for the optional identity
+     * fields `protocol.ts` documents ({@link GUEST_BOOT_ID_FEATURE}), and it
+     * is an OBSERVER: it cannot change the reply, it is called after the
+     * reply has been accepted, and a listener that throws is that listener's
+     * problem — never the caller's, whose result is already decided.
+     *
+     * Absent by default, which is what keeps this shared transport's
+     * behaviour identical for the Firecracker tier. The kubernetes backend
+     * sets it to follow the guest PROCESS behind a handle whose pod uid — its
+     * bind token — cannot change when the container is restarted in place.
+     */
+    readonly onGuestReply?: (reply: GuestReplyIdentity) => void;
+    /**
+     * The largest `writeFile` body this transport will accept, in raw
+     * bytes. Default {@link DEFAULT_MAX_WRITE_FILE_BYTES} (1 GiB).
+     *
+     * A body above one frame is written in parts (see
+     * {@link VsockAgentTransport.writeFile}), so nothing about the wire
+     * stops a caller handing over a body larger than the guest's disk or
+     * this process's heap. This is the bound that says no first, by a
+     * number the caller chose, with {@link AgentWriteFileTooLargeError}
+     * naming it — rather than by an out-of-memory or an ENOSPC halfway
+     * through a sequence of parts.
+     *
+     * Checked before the route is chosen, so it caps EVERY body — a value
+     * set below what one frame carries caps the small single-frame writes
+     * too, which is the range a host capping what a caller may push into a
+     * workspace would most plausibly set it to.
+     */
+    readonly maxWriteFileBytes?: number;
+    /**
+     * Raw bytes per part when a `writeFile` body is written in parts.
+     * Defaults to the largest part one frame can carry, and is clamped
+     * DOWN to that: a value above what a frame admits is not a way to
+     * send a bigger frame.
+     *
+     * Setting it also lowers the size at which a body is split at all,
+     * so a suite can exercise a multi-part write without allocating one.
+     * Leave it unset in production: the default is the fewest round trips
+     * the pre-auth ceiling allows.
+     */
+    readonly writeFilePartBytes?: number;
+    /**
+     * Say that a failed connect attempt will NOT fix itself, so the retry
+     * budget above is not worth spending on it.
+     *
+     * Absent by default, which keeps every dial retrying for the whole budget
+     * exactly as it always has — the budget exists because the common connect
+     * failure IS transient (an agent re-listening after a resume answers
+     * `ECONNREFUSED` for a moment). The exception is a failure that is about
+     * the CALLER's own environment rather than the guest's: the kubernetes
+     * backend's Service FQDN does not resolve on a host with no cluster DNS,
+     * and re-asking the same resolver the same question for half a minute
+     * only ensures the caller's own deadline expires first and reports a
+     * timeout in place of the diagnosis.
+     *
+     * Called with each attempt's error, before the backoff. Returning true
+     * ends the loop; the error thrown is the same wrapper as an exhausted
+     * budget, carrying that attempt's failure as its `cause`.
+     */
+    readonly permanentDialFailure?: (error: unknown) => boolean;
 }
 /**
  * The guest agent's default pre-auth frame ceiling for a routed (`tcp`)
@@ -228,6 +360,23 @@ export interface VsockTransportOptions {
  * implemented by this transport.
  */
 export declare const TCP_PREAUTH_FRAME_LIMIT_BYTES: number;
+/**
+ * The guest agent's default ceiling on ANY frame, pre-auth or not —
+ * mirrors `agent.cjs`'s `MAX_FRAME_BYTES` (`NAMZU_AGENT_MAX_FRAME_BYTES`,
+ * default 256 MiB). It is the budget the `unix`/`vsock`/`mtls` arms are
+ * bounded by, since none of them runs a credential gate and so none of
+ * them ever pays the smaller pre-auth price.
+ */
+export declare const GUEST_FRAME_LIMIT_BYTES: number;
+/** Default {@link VsockTransportOptions.maxWriteFileBytes} — 1 GiB. */
+export declare const DEFAULT_MAX_WRITE_FILE_BYTES: number;
+/**
+ * Idle time before the kernel sends its first TCP keepalive probe on a
+ * `tcp`-arm connection, host side. 15 s, matching the Kubernetes backend's
+ * default heartbeat interval, so the two bounds do not disagree about how
+ * long a silent connection is allowed to look healthy.
+ */
+export declare const TCP_KEEPALIVE_INITIAL_DELAY_MS = 15000;
 /**
  * Thrown when a `tcp`-handle request's framed envelope (op + body +
  * token) would exceed {@link TCP_PREAUTH_FRAME_LIMIT_BYTES}. Named so a
@@ -237,6 +386,96 @@ export declare const TCP_PREAUTH_FRAME_LIMIT_BYTES: number;
 export declare class AgentPreauthFrameTooLargeError extends Error {
     constructor(message: string);
 }
+/**
+ * Thrown when a `writeFile` body exceeds
+ * {@link VsockTransportOptions.maxWriteFileBytes}. Distinct from
+ * {@link AgentPreauthFrameTooLargeError}: that one says the WIRE cannot
+ * carry this in one frame (and, since the part protocol, only ever fires
+ * when the guest cannot carry it in several either), this one says the
+ * HOST was configured not to send a body this large at all.
+ */
+export declare class AgentWriteFileTooLargeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a read this transport cannot serve on the old whole-file op
+ * is asked of a guest that does not advertise
+ * {@link READ_FILE_STREAM_FEATURE} — a ranged `readFile`, or any
+ * `readFileStream`.
+ *
+ * A refusal rather than a fallback, and that is the whole point of the
+ * class: an agent that predates the feature IGNORES `offset`/`length` and
+ * answers with the WHOLE file, so silently taking the old path would hand
+ * a caller the entire file where it asked for a slice — a wrong answer
+ * dressed as a degraded one. Named so a host can tell "rebuild the guest
+ * image" apart from "that file is not there".
+ */
+export declare class AgentReadFileStreamUnsupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown by {@link VsockAgentTransport}'s dial when it gives up without a
+ * socket — the retry budget spent, or the failure declared one waiting cannot
+ * cure. The underlying connect failure is its `cause`.
+ *
+ * A class, and not only a phrase in the message, because callers classify on
+ * it: "the failure came out of the dial" means NOTHING was sent to the guest,
+ * which is what makes a retry against a replaced pod safe (the kubernetes
+ * backend's `agentAddress: 'pod-ip'` re-read). A message a guest can quote
+ * back — a command's stderr, a path, a proxy's own error — cannot be allowed
+ * to claim that.
+ */
+/**
+ * The two fields that turn a connection-bound terminal into a session, on
+ * the host's side of {@link VsockAgentTransport.openTerminal}.
+ *
+ * Both are optional and both are ignored by a guest that predates the
+ * session registry, which is why the caller — never this transport — is the
+ * one that checks the guest advertises the capability first.
+ */
+export interface SessionTerminalOpen {
+    readonly sessionId?: string;
+    readonly persistent?: boolean;
+}
+/**
+ * One open terminal stream, plus what only a SESSION's reader needs: the
+ * guest's opening frame, the byte offset to come back at, and a way to stop
+ * reading without signalling the program.
+ */
+export interface AgentTerminalStream {
+    readonly session: TerminalSession;
+    /** The guest's `ready` frame. Carries the session fields, when there are any. */
+    readonly ready: TerminalReadyEvent;
+    /** One past the newest retained byte this stream has delivered, if any. */
+    nextOffset(): number | undefined;
+    /**
+     * End this attachment locally. Nothing is signalled in the guest: the
+     * program goes on running and its output goes on filling the retained
+     * log, which is the entire difference between this and `kill`.
+     */
+    detach(): void;
+}
+/**
+ * Thrown — as the rejection of a session terminal's `exited` — when the
+ * attachment ended and the program did not.
+ *
+ * `exited` may not RESOLVE here: a resolved `exited` says the program is
+ * over, and reporting `exitCode: -1` for a shell that is still running in
+ * the pod is exactly the confusion this whole feature exists to remove. The
+ * offset is carried because it is what the next attach resumes from.
+ */
+export declare class AgentSessionDetachedError extends Error {
+    readonly nextOffset: number | undefined;
+    readonly name = "AgentSessionDetachedError";
+    constructor(nextOffset: number | undefined, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class AgentDialFailedError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /** Exact guest wire version accepted by this Firecracker transport. */
 export declare const FIRECRACKER_AGENT_PROTOCOL_VERSION: 2;
 declare function frame(payload: string): Buffer;
@@ -244,11 +483,28 @@ declare function frame(payload: string): Buffer;
  * Incremental frame reader. Feed it socket chunks; it yields complete
  * payloads. A zero-length frame is the exec stream terminator and is
  * surfaced as an empty string so the caller can stop.
+ *
+ * It accumulates into ONE buffer it grows geometrically, with a read
+ * cursor, rather than re-`concat`ing every arriving chunk onto a fresh
+ * allocation. The distinction only matters for a large frame, where it is
+ * the difference between linear and quadratic: a `read-file` reply for a
+ * 64 MiB file arrives as ~1400 socket chunks, and copying everything
+ * received so far onto each one of them spent half a minute of memcpy on
+ * a reply the socket delivered in under a second. Identical framing,
+ * identical errors, identical `bufferedBytes` — only the copying changes.
  */
 declare class FrameReader {
     private buf;
+    /** First byte not yet handed out as part of a frame. */
+    private start;
+    /** One past the last byte received. */
+    private end;
     push(chunk: Buffer): string[];
     get bufferedBytes(): number;
+    /** Copy `chunk` in, growing (and first compacting) only when needed. */
+    private append;
+    /** Mark `bytes` from the read cursor as consumed. */
+    private consume;
 }
 /**
  * The transport. One instance per sandbox handle; every request opens
@@ -262,14 +518,31 @@ export declare class VsockAgentTransport {
     private readonly connectRetryBudgetMs;
     private readonly connectRetryIntervalMs;
     private readonly readIdleTimeoutMs;
+    /** Undefined → this transport negotiates no heartbeat at all. */
+    private readonly heartbeatMs?;
     private readonly onDial?;
+    private readonly onDialAttempt?;
+    private readonly onGuestReply?;
+    private readonly maxWriteFileBytes;
+    private readonly writeFilePartBytes?;
+    /**
+     * What the guest advertised in `healthz`, cached for this handle's
+     * lifetime. A pod does not swap its agent binary while it is running,
+     * so the probe is asked once per transport and only when something
+     * actually depends on a capability — an ordinary write, exec, read or
+     * terminal pays nothing for it.
+     */
+    private guestFeatureList?;
+    private readonly permanentDialFailure?;
     private readonly executionController;
     constructor(handle: SandboxAgentHandle, options?: VsockTransportOptions);
     /**
      * Dial the agent with the resume-survival retry budget. Resolves a
      * connected, post-handshake socket. Retries connect/handshake
      * failures (ECONNREFUSED while the agent re-listens after a resume,
-     * a dropped CONNECT ack) until the budget is exhausted.
+     * a dropped CONNECT ack) until the budget is exhausted — or until
+     * {@link VsockTransportOptions.permanentDialFailure} says this particular
+     * failure is not one waiting will cure.
      */
     private dial;
     private connectOnce;
@@ -317,6 +590,16 @@ export declare class VsockAgentTransport {
      * handle kind, which the guest never gates on frame size pre-auth.
      */
     private assertPreauthBudget;
+    /**
+     * Hand one accepted reply to {@link VsockTransportOptions.onGuestReply},
+     * and never let the listener's failure reach the caller.
+     *
+     * The caller's result is already decided by the time this runs — the
+     * reply parsed, the frame accounted for — so a hook that throws must not
+     * turn a successful read into a failed one. Swallowing is the only
+     * behaviour that keeps an optional observer optional.
+     */
+    private observeGuestReply;
     /**
      * Send one framed request and read one framed JSON reply (file-IO +
      * healthz). Applies the read-idle timeout so a post-resume hung read
@@ -362,8 +645,210 @@ export declare class VsockAgentTransport {
      * post-create readiness fence.
      */
     waitForReady(timeoutMs: number, pollIntervalMs: number, signal?: AbortSignal): Promise<void>;
-    writeFile(path: string, content: Buffer): Promise<void>;
-    readFile(path: string): Promise<Buffer>;
+    /**
+     * Write a whole file into the guest workspace.
+     *
+     * A body that fits one frame goes as it always has: a single
+     * `write-file` envelope carrying the base64 content, one round trip,
+     * byte-for-byte the request this transport has always sent.
+     *
+     * A body that does NOT fit is the case this exists for. On the `tcp`
+     * arm every request dials a fresh connection, so every request is that
+     * connection's first, not-yet-authenticated frame (the credential
+     * rides in the envelope) and is bounded by
+     * {@link TCP_PREAUTH_FRAME_LIMIT_BYTES} — about 5.9 MiB of file
+     * content — on EVERY call, not once. Raising the guest's
+     * `NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES` trades away the pre-auth
+     * budget that ceiling exists to bound, so the fix is on this side:
+     * split the body into parts that each fit, append them to a temporary
+     * SIBLING of the target inside the same workspace jail, and finish
+     * with an atomic `rename` onto the target.
+     *
+     * What that buys, and why the shape is what it is:
+     *
+     *  - **A reader never sees a half-written file.** The target changes
+     *    exactly once, in the final part's `rename`. A sequence that dies
+     *    at part 3 of 9 leaves the target exactly as it was — including
+     *    not existing.
+     *  - **A lost or duplicated part is detected, not written.** Each part
+     *    names the offset it starts at and the guest refuses it unless
+     *    that equals the temp file's current size.
+     *  - **An abandoned sequence cleans up after itself.** An abort or a
+     *    transport failure removes the temp file (best effort — a peer
+     *    that has gone away cannot be asked to) and rejects.
+     *  - **Parts go out sequentially on fresh connections**, which is what
+     *    the offset check assumes and what keeps the guest's pre-auth
+     *    connection pool holding one of this caller's sockets at a time.
+     *
+     * The guest must ADVERTISE the capability (`${WRITE_FILE_PARTS_FEATURE}`
+     * in its `healthz` reply) before a single part is sent. An agent that
+     * predates the part protocol would read a part's `content` as a whole
+     * file; it never receives one, and an oversized body against such a
+     * guest still fails with the named
+     * {@link AgentPreauthFrameTooLargeError} it always did.
+     *
+     * {@link VsockTransportOptions.maxWriteFileBytes} is checked FIRST, on
+     * every body and before anything about the wire is considered: it is a
+     * bound on what a caller may push into a workspace, not a bound on
+     * multi-part writes, so a host that lowers it below the frame budget
+     * gets the cap it asked for rather than none.
+     */
+    writeFile(path: string, content: Buffer, signal?: AbortSignal): Promise<void>;
+    /** Today's single-frame write, unchanged — see {@link writeFile}. */
+    private writeFileWhole;
+    /**
+     * The frame budget one request has on this handle: the pre-auth
+     * ceiling on the credentialed `tcp` arm, the guest's global frame
+     * ceiling on the host-local arms, which authenticate nothing and so
+     * never pay the smaller price.
+     */
+    private singleFrameBudgetBytes;
+    /**
+     * Exact framed size of a `write-file` envelope whose `content` field
+     * holds `contentBytes` raw bytes base64-encoded — WITHOUT encoding
+     * them, so sizing a 1 GiB body costs nothing and never builds a string
+     * longer than V8 permits.
+     *
+     * Exact rather than approximate because the base64 alphabet contains
+     * no character `JSON.stringify` escapes, so the encoded content
+     * contributes precisely its own length to the envelope and the rest of
+     * the envelope (paths, the token, the part fields) is measured as it
+     * will actually be serialized.
+     */
+    private writeFileEnvelopeBytes;
+    /**
+     * Ask the guest whether it implements the part protocol. Cached for
+     * the transport's lifetime; a transport failure propagates rather than
+     * reading as "not supported", because answering a broken connection
+     * with a too-large error would name the wrong cause.
+     */
+    private guestSupportsWriteFileParts;
+    /**
+     * The capability strings this guest advertises in `healthz`, cached for
+     * this transport's lifetime.
+     *
+     * One list, asked once, for every optional op: the write-file part
+     * protocol and the execution-attach ops both read it, and a second
+     * cache would mean a second probe against a guest that answers both
+     * questions in one reply. A transport FAILURE propagates rather than
+     * reading as "not supported", because answering a broken connection
+     * with a capability refusal would name the wrong cause.
+     */
+    guestFeatures(signal?: AbortSignal): Promise<readonly string[]>;
+    /**
+     * Send one framed request and read a STREAM of framed JSON events until
+     * the agent's zero-length terminator, handing each event to `onEvent`.
+     *
+     * The generic half of what {@link executeRaw} does, without any of its
+     * opinions about what the events mean: `executeRaw` owns the exec
+     * NDJSON union and the {@link ExecResultAccumulator}, and this owns
+     * dial, framing, the terminator, the observation bound and the
+     * post-terminator close. Additive — nothing already shipped calls it —
+     * so the Firecracker tier's behaviour is untouched and a later streamed
+     * op reuses it rather than writing a fourth copy of this loop.
+     *
+     * There is deliberately NO read-idle timeout. A stream that exists to
+     * follow a long, quiet command must not be torn down for being quiet;
+     * the whole observation is bounded by `observationTimeoutMs` instead,
+     * exactly as an `execute` stream is.
+     */
+    streamFramedRequest(req: AgentRequest, onEvent: (event: Record<string, unknown>) => void, options: {
+        readonly observationTimeoutMs: number;
+    }, signal?: AbortSignal): Promise<void>;
+    /** The refusal for a body no frame can carry and no guest can take in parts. */
+    private oversizedWriteFileError;
+    /**
+     * Write `content` to `target` as a sequence of parts. See
+     * {@link writeFile} for why this shape.
+     */
+    private writeFileInParts;
+    /**
+     * Remove an abandoned part file. Best effort BY CONTRACT: the reason
+     * the sequence failed is frequently that the guest is unreachable, and
+     * a cleanup that threw would replace the caller's real error — the one
+     * that says why the write failed — with a second one about tidying up.
+     */
+    private discardWriteFileTemp;
+    /**
+     * Read a file out of the guest.
+     *
+     * Three shapes, decided by what the guest advertises and what the
+     * caller asked for:
+     *
+     *  - **No options, guest advertises {@link READ_FILE_STREAM_FEATURE}** —
+     *    served by {@link readFileStream} and concatenated here. Neither
+     *    side ever holds the base64 form or the JSON envelope whole, so the
+     *    ~384 MiB ceiling (V8 refuses a string longer than `0x1fffffe8`
+     *    characters, which is what a base64-encoded file of that size
+     *    needs) is gone and the guest's peak stops tracking the file's
+     *    size. The result is still one `Buffer`, because that is what this
+     *    method returns; a caller that must not hold even that iterates
+     *    {@link readFileStream} directly.
+     *  - **No options, guest does not advertise it** — today's single
+     *    whole-file reply, byte for byte, with today's ceiling.
+     *  - **`offset` and `length`** — one ranged `read-file`: a single round
+     *    trip for a single slice, which is the point of asking for one.
+     *    `offset` WITHOUT `length` is an unbounded tail, so it goes through
+     *    the stream instead; the guest refuses an uncapped range on
+     *    `read-file` for exactly that reason.
+     *
+     * A ranged read against a guest that does not advertise the feature is
+     * REFUSED with {@link AgentReadFileStreamUnsupportedError} rather than
+     * downgraded: such an agent ignores `offset`/`length` and answers with
+     * the whole file, which the caller would read as its slice.
+     */
+    readFile(path: string, options?: SandboxReadFileOptions): Promise<Buffer>;
+    /** Today's single whole-file reply, unchanged — see {@link readFile}. */
+    private readFileWhole;
+    /**
+     * One bounded slice, in one round trip.
+     *
+     * The guest's own ceiling on a range (`NAMZU_AGENT_READ_FILE_RANGE_BYTES`,
+     * 1 MiB by default) is not mirrored here and deliberately so: it is the
+     * DEPLOYMENT's number, a host that guessed it would refuse ranges the
+     * guest would have served, and the guest's refusal already names the
+     * variable that raises it.
+     */
+    private readFileRange;
+    /**
+     * Read a file as an ordered sequence of chunks, so neither side holds
+     * the whole of it.
+     *
+     * The guest sends `meta`, then `data` frames, then `end`, then the
+     * zero-length terminator — the same terminated-stream shape `execute`
+     * uses. Two bounds keep this side's heap flat while the guest's stays
+     * flat on its own: the socket is PAUSED once
+     * {@link READ_FILE_STREAM_HIGH_WATER_BYTES} of decoded chunks are
+     * waiting for a slow consumer, and the guest itself waits for each
+     * `data` frame to drain before it reads the next one.
+     *
+     * Leaving the loop early — `break`, an exception, an aborted
+     * `options.signal` — destroys the socket in the generator's `finally`,
+     * which is what makes the guest close its fd: it sees the connection go
+     * and releases the descriptor rather than leaking one per abandoned
+     * read.
+     *
+     * Refuses a guest that does not advertise
+     * {@link READ_FILE_STREAM_FEATURE} before dialing, with
+     * {@link AgentReadFileStreamUnsupportedError}.
+     */
+    readFileStream(path: string, options?: SandboxReadFileOptions): AsyncGenerator<Buffer, void, undefined>;
+    /**
+     * The stream itself. Private, and one argument wider than
+     * {@link readFileStream}: `onMeta` fires once, with the guest's `meta`
+     * frame, before the first chunk is yielded, which is how
+     * {@link readFile} sizes its destination buffer without a second round
+     * trip and without a public parameter nobody outside this class should
+     * pass.
+     */
+    private readFileFrames;
+    /**
+     * Ask the guest whether it implements ranged and streamed reads.
+     * Cached for the transport's lifetime, exactly as
+     * {@link guestSupportsWriteFileParts} is, and for the same reason: a
+     * pod does not swap its agent binary while it is running.
+     */
+    private guestSupportsReadFileStream;
     /**
      * Open a real PTY owned by the in-VM agent.
      *
@@ -373,7 +858,55 @@ export declare class VsockAgentTransport {
      * browser never reaches this transport directly; the runtime gateway owns
      * the session and its authenticated WebSocket attachment.
      */
-    openTerminal(options: OpenTerminalOptions): Promise<TerminalSession>;
+    openTerminal(options: OpenTerminalOptions & SessionTerminalOpen): Promise<TerminalSession>;
+    /**
+     * The same open, handing back the session's own handles as well as the
+     * `TerminalSession` — the offset to come back at, and the detach that
+     * ends the attachment without signalling the program.
+     *
+     * Exactly one code path serves both: a persistent terminal is not a
+     * second kind of terminal, it is the same stream with a different answer
+     * to "what does a closed connection mean".
+     */
+    openSessionTerminal(options: OpenTerminalOptions & SessionTerminalOpen): Promise<AgentTerminalStream>;
+    /**
+     * The framed, bidirectional stream behind every terminal this transport
+     * opens — the one the `terminal` op starts, and the one `attach-session`
+     * joins to a terminal that is already running.
+     *
+     * Parameterised rather than copied, because the two differ in exactly two
+     * places and everything else — the dial, the framing, the ready
+     * handshake, the read-idle timer that is cleared once a shell may
+     * legitimately go quiet, the heartbeat, the output buffering before the
+     * first listener, the kill grace — has to behave identically or a
+     * reattached terminal is a second terminal implementation with its own
+     * bugs. The two differences:
+     *
+     *  - **`detachable`.** For a connection-bound terminal a lost stream IS
+     *    the end of the program, and `exited` resolves with `exitCode: -1`
+     *    exactly as it always has. For a session attachment it is not: the
+     *    program is still running in the pod, so `exited` REJECTS with
+     *    {@link AgentSessionDetachedError} rather than reporting an exit that
+     *    did not happen. The rejection is pre-handled here so a caller that
+     *    only reads output cannot take the host process down with an
+     *    unhandled rejection.
+     *  - **the offsets.** A session stream's frames carry their place in the
+     *    guest's retained log, and {@link AgentTerminalStream.nextOffset} is
+     *    what a reattach resumes from. It is never computed from the decoded
+     *    text: a chunk that ends mid-character decodes wider than the bytes
+     *    it replaced.
+     */
+    private openTerminalStream;
+    /**
+     * Join a terminal session that is already running in the guest, replaying
+     * what it printed from `fromOffset` before following it live.
+     *
+     * The guest allows ONE attachment per session and ends the previous one
+     * by name, so two host processes cannot interleave keystrokes into one
+     * shell. Nothing here signals the program: releasing this stream is a
+     * detach, and ending the session is `kill-session`.
+     */
+    attachSessionTerminal(request: AttachSessionRequest): Promise<AgentTerminalStream>;
     /** Open one TCP stream to a service listening on guest loopback. */
     openTcpConnection(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection>;
 }