@namzu/sandbox 13.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 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`).
@@ -79,6 +79,18 @@ import { type ExecRequest, type ReadFileRequest, type TcpConnectRequest, type Te
  *    (`tls.TLSSocket` is a `net.Socket`). The container-app NEVER sees
  *    a host-local `udsPath`; the cert material is injected by the
  *    Vandal host layer, never returned by the orchestrator.
+ *  - `tcp`   — the guest agent listening directly on a routed pod
+ *    network (the kubernetes backend). The dialer does a plain
+ *    `net.connect({ host, port })` — no relay, no routing preamble, no
+ *    ack: there is nothing between the host and the guest's own listen
+ *    socket to route through, so the framing loop starts on the very
+ *    first byte, exactly as the `unix` arm's does. `host` may be a
+ *    Service FQDN rather than a literal IP; every call dials fresh (see
+ *    `dial()` below), so DNS is re-resolved on every request and a
+ *    resumed pod's new address is picked up for free. `token` rides in
+ *    each request envelope (see `AgentRequestCredential` in
+ *    `protocol.ts`) because a routed listener authenticates what the
+ *    vsock/unix control channel never had to.
  */
 export type SandboxAgentHandle = {
     readonly kind: 'unix';
@@ -98,6 +110,11 @@ export type SandboxAgentHandle = {
         readonly key: string | Buffer;
         readonly servername?: string;
     };
+} | {
+    readonly kind: 'tcp';
+    readonly host: string;
+    readonly port: number;
+    readonly token?: string;
 };
 /**
  * The mTLS cert material the consumer injects onto a wire `mtls` handle (the
@@ -112,12 +129,17 @@ export interface MtlsClientMaterial {
     readonly servername?: string;
 }
 /**
- * The WIRE shape of an agent handle as the orchestrator returns it. Identical
- * to {@link SandboxAgentHandle} EXCEPT the `mtls` arm omits the `tls` cert
- * block: the orchestrator returns only host/port/sandboxId, and the consumer
- * (Vandal host layer) merges the cert material in (see `normalizeHandle`)
- * before constructing the transport. The `unix`/`vsock` arms are unchanged
- * (they carry no cert material).
+ * The WIRE shape of an agent handle as the FIRECRACKER orchestrator
+ * returns it. Identical to {@link SandboxAgentHandle} EXCEPT the `mtls`
+ * arm omits the `tls` cert block: the orchestrator returns only
+ * host/port/sandboxId, and the consumer (Vandal host layer) merges the
+ * cert material in (see `normalizeHandle`) before constructing the
+ * transport. The `unix`/`vsock` arms are unchanged (they carry no cert
+ * material). There is deliberately no `tcp` arm here: that kind belongs
+ * to the kubernetes backend, which builds its {@link SandboxAgentHandle}
+ * directly (host/port from the claimed Sandbox's status, token from the
+ * pod's own identity) and never goes through this orchestrator wire
+ * shape or `normalizeHandle`.
  */
 export type WireSandboxAgentHandle = {
     readonly kind: 'unix';
@@ -137,31 +159,60 @@ export type WireSandboxAgentHandle = {
  * used the URL path (`/execute`, `/read-file`, `/write-file`,
  * `/healthz`) — over vsock the same selector rides in the framed JSON.
  */
-export type AgentRequest = {
+export type AgentRequest = ({
     readonly op: 'execute';
     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;
 export interface VsockTransportOptions {
     /** Per-attempt connect + handshake timeout. Default 5000ms. */
     readonly connectTimeoutMs?: number;
@@ -177,6 +228,253 @@ 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
+     * content — a bare number. Used by callers that build their own
+     * `RemoteExecutionAdapter` on top of this transport (the kubernetes
+     * backend's `KubernetesAgentTransport`) to attribute wall time; the
+     * 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`)
+ * connection — mirrors `agent.cjs`'s `MAX_PREAUTH_FRAME_BYTES`
+ * (`NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES`, default 8 MiB). The gate on
+ * that side cannot run until a whole frame is parsed (the credential
+ * rides inside the envelope), so it bounds what an UNAUTHENTICATED
+ * connection's first frame may announce. This transport dials fresh per
+ * call — there is no persistent, already-authenticated connection to
+ * reuse — so EVERY `tcp` request is that connection's first frame, and
+ * this ceiling is therefore the effective per-request budget, not just
+ * a one-time cost paid on first use.
+ *
+ * Checked here, client-side, BEFORE dialing: an oversized request fails
+ * fast with a clear error instead of opening a connection the guest is
+ * going to refuse anyway. Chunking a `write-file` body across multiple
+ * frames would lift this ceiling; it is a documented follow-up, not
+ * 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
+ * caller can distinguish "this body needs chunking" from every other
+ * transport failure.
+ */
+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;
@@ -185,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
@@ -203,13 +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;
@@ -236,6 +569,37 @@ export declare class VsockAgentTransport {
      * CONNECT-ack path) before resolving — today it does not.
      */
     private connectOnceMtls;
+    /**
+     * Dial a `tcp` handle: a plain `net.connect({ host, port })`. NO
+     * routing preamble and NO ack — there is no relay to route through
+     * and no handshake line the guest expects, so the socket is handed
+     * to the framing loop the instant it connects, exactly like the
+     * `unix` arm above (whose body this deliberately does not touch).
+     */
+    private connectOnceTcp;
+    /**
+     * Fold the handle's credential into a request envelope. Only the
+     * `tcp` arm carries a token — the vsock/unix/mtls control channels
+     * are host↔guest only and the agent authenticates nothing there, so
+     * a request built for those arms passes through unchanged.
+     */
+    private withCredential;
+    /**
+     * Refuse an oversized `tcp` envelope BEFORE dialing. See
+     * {@link TCP_PREAUTH_FRAME_LIMIT_BYTES}. A no-op for every other
+     * 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
@@ -256,6 +620,20 @@ export declare class VsockAgentTransport {
      */
     execute(body: ExecRequest, opts?: SandboxExecOptions, signal?: AbortSignal): Promise<SandboxExecResult>;
     exec(command: string, argv?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>;
+    /**
+     * The raw `/execute` primitive with NO admission/reservation
+     * semantics: dial, send one framed request, accumulate the streamed
+     * NDJSON reply. Public (unlike the identical-in-spirit
+     * {@link reserveExecution}/{@link cancelExecution}, reached through
+     * the already-public {@link request}) so a caller running its OWN
+     * {@link RemoteExecutionController} — the kubernetes backend's
+     * adapter — can reuse this exact dial + framing rather than
+     * reimplementing it, while still supplying that controller its own
+     * `reserve`/`cancel`/`execute` triple as {@link RemoteExecutionAdapter}
+     * requires. Callers that just want a reserve-before-admission `exec`
+     * should use {@link execute} or {@link exec} instead.
+     */
+    executeStreamed(body: ExecRequest, opts?: SandboxExecOptions, signal?: AbortSignal): Promise<SandboxExecResult>;
     private reserveExecution;
     private cancelExecution;
     /** Readiness probe. A healthy guest must also speak the exact host protocol. */
@@ -267,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.
      *
@@ -278,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>;
 }