@aerol-ai/aerolvm-sdk 0.8.1 → 0.8.3

package/dist/internal/client.js

@@ -1,12 +1,21 @@
-import { basename } from "node:path";
+import { lstat, readdir, readFile, readlink, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { gzipSync } from "node:zlib";
+import { tarArchive } from "./tar.js";
 import { PATH_PREFIX as V1_PATH_PREFIX, ingressDNSPath as v1IngressDNSPath, sandboxCustomDomainDNSPath as v1SandboxCustomDomainDNSPath, sandboxCustomDomainPath as v1SandboxCustomDomainPath, sandboxCustomDomainsPath as v1SandboxCustomDomainsPath, } from "./api/v1/paths.js";
-import { MicroVMApiError } from "../errors.js";
+import { MicroVMApiError, MicroVMConflictError, MicroVMFileTooLargeError, MicroVMNotFoundError, MicroVMUnsupportedFeatureError, apiErrorFor, } from "../errors.js";
 import { Image } from "../Image.js";
 /**
  * The request header that selects which of a credential's teams a request
  * acts for. Keep in sync with pkg/api.HeaderTeam on the server.
  */
 export const TEAM_HEADER = "X-AerolVM-Team";
+/**
+ * The response header a 421 carries when the sandbox lives in another cell
+ * (a separate AerolVM install in the same federation): that cell's base URL.
+ * Keep in sync with models.CellEndpointHeader on the server.
+ */
+export const CELL_ENDPOINT_HEADER = "X-Aerolvm-Cell-Endpoint";
 const DEFAULT_API_VERSION = "v1";
 const PATH_PREFIXES = {
     v1: V1_PATH_PREFIX,
@@ -36,6 +45,18 @@ function fromApiAPIToken(t) {
         expired: t.expired === true,
     };
 }
+function fromApiTeamQuota(q) {
+    const out = { team: q.team, generation: q.generation, createdAt: q.created_at, updatedAt: q.updated_at };
+    if (q.max_sandboxes)
+        out.maxSandboxes = q.max_sandboxes;
+    if (q.max_cpu)
+        out.maxCPU = q.max_cpu;
+    if (q.max_memory_mb)
+        out.maxMemoryMB = q.max_memory_mb;
+    if (q.usage)
+        out.usage = { sandboxes: q.usage.sandboxes, cpu: q.usage.cpu, memoryMB: q.usage.memory_mb };
+    return out;
+}
 function fromApiEgressProfile(p) {
     const out = {
         name: p.name,
@@ -48,12 +69,74 @@ function fromApiEgressProfile(p) {
         out.description = p.description;
     return out;
 }
+function fromApiWarmPool(p) {
+    const out = {
+        image: p.image,
+        depth: p.depth,
+        onImageChange: (p.on_image_change || "replace_now"),
+        generation: p.generation,
+        createdAt: p.created_at,
+        updatedAt: p.updated_at,
+    };
+    if (p.min_depth)
+        out.minDepth = p.min_depth;
+    if (p.max_depth)
+        out.maxDepth = p.max_depth;
+    if (p.status) {
+        const status = { ready: p.status.ready, target: p.status.target, outdated: p.status.outdated ?? 0, servers: [] };
+        for (const s of p.status.servers ?? []) {
+            const server = { nodeId: s.node_id, ready: s.ready, target: s.target, outdated: s.outdated ?? 0 };
+            if (s.stale)
+                server.stale = true;
+            status.servers.push(server);
+        }
+        out.status = status;
+    }
+    return out;
+}
+// An image is the rest of the warm-pool path. Each segment is escaped and the
+// slashes are kept, so ghcr.io/acme/agent:1 reaches the server as written and
+// no proxy has an encoded slash to rewrite.
+function warmPoolPath(image) {
+    return `/warm-pools/${image.split("/").map(encodeURIComponent).join("/")}`;
+}
 function toApiEgressRule({ inject, ...rule }) {
     return inject ? { ...rule, inject: { header: inject.header, secret_ref: inject.secretRef } } : rule;
 }
 function fromApiEgressRule({ inject, ...rule }) {
     return inject ? { ...rule, inject: { header: inject.header, secretRef: inject.secret_ref } } : rule;
 }
+function fromApiIdentityRole(r) {
+    const out = { tag: r.tag, minRole: r.min_role, createdAt: r.created_at, updatedAt: r.updated_at };
+    if (r.team)
+        out.team = r.team;
+    return out;
+}
+function fromApiSandboxIdentity(i) {
+    if (!i)
+        return undefined;
+    const out = { roleTag: i.role_tag, audience: i.audience, subject: i.subject, tokenFile: i.token_file };
+    if (i.aws_role_arn)
+        out.awsRoleArn = i.aws_role_arn;
+    if (i.azure_client_id)
+        out.azureClientId = i.azure_client_id;
+    if (i.azure_tenant_id)
+        out.azureTenantId = i.azure_tenant_id;
+    if (i.token_expires_at)
+        out.tokenExpiresAt = i.token_expires_at;
+    if (i.last_error)
+        out.lastError = i.last_error;
+    return out;
+}
+function toApiIdentity(i) {
+    return {
+        role_tag: i.roleTag,
+        audience: i.audience,
+        aws_role_arn: i.awsRoleArn,
+        azure_client_id: i.azureClientId,
+        azure_tenant_id: i.azureTenantId,
+    };
+}
 /** HTTP status codes the retry loop considers transient. */
 // 421 Misdirected Request: an owner answered for a sandbox it doesn't hold
 // (HTTP/2 connection coalescing, or a stale ingress route after failover).
@@ -68,6 +151,65 @@ const RETRYABLE_STATUS_CODES = new Set([421, 429, 502, 503, 504]);
 // over its share, 503 when the node sheds load. A Retry-After on a 421, 502 or
 // 504 is a hop's, not the server's, so those use the normal backoff.
 const REFUSED_STATUS_CODES = new Set([429, 503]);
+// Bounds the sandbox-to-cell map, so a long-lived client that touches many
+// sandboxes in other cells cannot grow without end. A dropped entry costs
+// only one more 421 the next time.
+const MAX_REMEMBERED_CELLS = 10_000;
+/**
+ * A 421 that names a cell is the cell router's answer, which sending to the
+ * same place again cannot change. The retry loop hands it back at once and
+ * {@link APIClient.request} decides whether to follow it.
+ */
+function isCellAnswer(response) {
+    return response.status === 421 && (response.headers.get(CELL_ENDPOINT_HEADER) ?? "").trim() !== "";
+}
+// fetch reads a stream while it sends it, so only a body held whole in
+// memory can go out a second time.
+function isReplayableBody(body) {
+    return (body == null ||
+        typeof body === "string" ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        body instanceof Blob ||
+        body instanceof FormData ||
+        body instanceof URLSearchParams);
+}
+/** The sandbox ID a per-sandbox path names: the segment right after `prefix` (".../sandboxes/"). */
+function sandboxIDInPath(path, prefix) {
+    if (!path.startsWith(prefix))
+        return undefined;
+    const rest = path.slice(prefix.length);
+    const end = rest.search(/[/?#]/);
+    const segment = end === -1 ? rest : rest.slice(0, end);
+    if (segment === "")
+        return undefined;
+    // Some call sites escape the ID and some do not; decoding keys both alike.
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/**
+ * The toolboxd feature (on /version) behind the file verbs' options: list
+ * depth and cap, the move and copy overwrite guard, mkdir without parents and
+ * the copy route. An older agent ignores those options (overwrite=false would
+ * overwrite), so the calls that send them check first.
+ */
+const FEATURE_FILE_VERBS = "files.verbs";
+/**
+ * The toolboxd feature behind upload's write options. An older agent ignores
+ * them: createOnly would replace an existing file.
+ */
+const FEATURE_WRITE_OPTIONS = "files.write_options";
+/**
+ * The toolboxd feature behind upload's extract=true (uploadDir). An older
+ * agent ignores extract and would store the archive itself as a file.
+ */
+const FEATURE_EXTRACT = "files.extract";
+/** The entry cap `listFiles` sends when the caller gives none. */
+export const DEFAULT_LIST_LIMIT = 10_000;
 /**
  * The header a sandbox create carries so the server can recognise a retry of
  * it. Keep in sync with clustercreate.HeaderIdempotencyKey on the server.
@@ -223,6 +365,21 @@ export function stripTrailingSlashes(value) {
     }
     return value.slice(0, end);
 }
+/** A signal that aborts when any of `signals` does, with that one's reason. */
+function anySignal(signals) {
+    const native = AbortSignal.any;
+    if (typeof native === "function")
+        return native.call(AbortSignal, signals);
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+    }
+    return controller.signal;
+}
 /** Waits `ms`, or rejects with the signal's reason as soon as it aborts. */
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -244,15 +401,30 @@ function sleep(ms, signal) {
 export class APIClient {
     baseURL;
     apiVersion;
-    patToken;
     team;
     fetchFn;
     versionPrefix;
     retryConfig;
     signal;
+    /** The client a {@link withSignal} view was made from; unset on a real client. */
+    root;
+    /**
+     * Features each sandbox's agent listed on /version (requireToolboxFeatures).
+     * Refreshed on a miss, because a restart can bring a newer agent.
+     */
+    toolboxFeatures = new Map();
+    /**
+     * The base URL of the cell each sandbox in another cell lives in, learned
+     * from a 421 that named it, oldest first. Shared with {@link withSignal}
+     * views, so what one call learns routes the next. Entries are dropped only
+     * on a 404 from that cell (the sandbox may be gone) or past
+     * {@link MAX_REMEMBERED_CELLS}: the cell is minted into the ID, so it
+     * never changes.
+     */
+    sandboxCells = new Map();
     constructor(config) {
         this.baseURL = stripTrailingSlashes(config.baseURL);
-        this.patToken = config.patToken ?? "";
+        Object.defineProperty(this, "patToken", { value: config.patToken ?? "", enumerable: false });
         this.team = (config.team ?? "").trim();
         this.fetchFn = config.fetch ?? fetch;
         this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
@@ -274,6 +446,22 @@ export class APIClient {
     versioned(suffix) {
         return `${this.versionPrefix}${suffix}`;
     }
+    /**
+     * This client with `signal` added to its own: either one aborting ends a
+     * request and any retry wait. A per-call signal (plan S6) rides on a view
+     * like this rather than a parameter on every internal method. The view
+     * shares everything else, the per-sandbox feature cache included, and the
+     * sandboxes it returns hold the real client, so the call's signal never
+     * outlives the call. Without a signal it is this client.
+     */
+    withSignal(signal) {
+        if (!signal)
+            return this;
+        const view = Object.create(this);
+        Object.defineProperty(view, "signal", { value: this.signal ? anySignal([this.signal, signal]) : signal });
+        Object.defineProperty(view, "root", { value: this.root ?? this });
+        return view;
+    }
     async create(options) {
         const resolved = await this.resolveImage(options);
         // One key per call, sent unchanged on each of its automatic retries: a
@@ -392,6 +580,40 @@ export class APIClient {
         }
         return this.wrap(items[0]);
     }
+    /**
+     * The caller's sandbox called `name`, created from `options` when there is
+     * none; `created` is true only when this call made it. Safe to retry and to
+     * run concurrently: names are unique per owner, so a caller that loses a
+     * race to create the name gets a 409 and reads the winner's sandbox.
+     */
+    async getOrCreate(name, options) {
+        const wanted = name.trim();
+        if (wanted === "") {
+            throw new Error("sandbox name is required");
+        }
+        const given = options.name?.trim() ?? "";
+        if (given !== "" && given !== wanted) {
+            throw new Error(`options name "${given}" differs from "${wanted}"`);
+        }
+        const existing = await this.getByName(wanted);
+        if (existing !== null) {
+            return { sandbox: existing, created: false };
+        }
+        try {
+            return { sandbox: await this.create({ ...options, name: wanted }), created: true };
+        }
+        catch (err) {
+            if (!(err instanceof MicroVMConflictError))
+                throw err;
+            // Another caller created the name after the lookup. A 409 whose name
+            // still cannot be found is a conflict on something else, so the
+            // create's own error stands.
+            const winner = await this.getByName(wanted);
+            if (winner === null)
+                throw err;
+            return { sandbox: winner, created: false };
+        }
+    }
     async get(id, options) {
         const q = buildIncludeEnvQuery(options?.includeEnv);
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}${q}`);
@@ -464,6 +686,32 @@ export class APIClient {
     async destroy(id) {
         await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}`);
     }
+    /**
+     * Deletes every sandbox carrying all of `tags`, one at a time, after
+     * listing every page; returns the IDs now gone. A 404 counts as deleted,
+     * so the call is safe to repeat. Any other failure stops it and is thrown.
+     */
+    async destroyAll(tags) {
+        if (!tags || Object.keys(tags).length === 0) {
+            throw new Error("destroyAll needs at least one tag; with none it would delete every sandbox you own");
+        }
+        const ids = [];
+        for await (const page of this.listPages({ tags })) {
+            ids.push(...page.map((sandbox) => sandbox.id));
+        }
+        const gone = [];
+        for (const id of ids) {
+            try {
+                await this.destroy(id);
+            }
+            catch (err) {
+                if (!(err instanceof MicroVMNotFoundError))
+                    throw err;
+            }
+            gone.push(id);
+        }
+        return gone;
+    }
     async resize(id, options) {
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/resize`, toApiResizeOptions(options));
         return this.wrap(response);
@@ -472,13 +720,105 @@ export class APIClient {
         const response = await this.doJSON("PUT", `${this.versionPrefix}/sandboxes/${id}/lifecycle`, toApiLifecycle(lifecycle));
         return this.wrap(response);
     }
+    /**
+     * Fails closed unless the sandbox's agent lists every feature. toolboxd
+     * ignores request options it does not know, so sending a newer option to an
+     * older agent would silently skip it.
+     */
+    async requireToolboxFeatures(id, ...features) {
+        if (features.length === 0) {
+            return;
+        }
+        let have = this.toolboxFeatures.get(id);
+        let version = "";
+        let runtime = "";
+        if (!have || !features.every((feature) => have.has(feature))) {
+            const info = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/toolbox/version`);
+            have = new Set(Array.isArray(info?.features) ? info.features.map(String) : []);
+            this.toolboxFeatures.set(id, have);
+            version = typeof info?.version === "string" ? info.version : "";
+            runtime = typeof info?.runtime === "string" ? info.runtime : "";
+        }
+        const missing = features.filter((feature) => !have.has(feature));
+        if (missing.length > 0) {
+            throw new MicroVMUnsupportedFeatureError(id, missing, version, runtime);
+        }
+    }
     async exec(id, request) {
+        // An older agent ignores the caps and returns all output, and refuses
+        // argv with a confusing "command is required"; check first.
+        const features = [];
+        if (request.maxStdoutBytes || request.maxStderrBytes) {
+            features.push("exec.max_output_bytes");
+        }
+        if (request.argv?.length) {
+            features.push("exec.argv");
+        }
+        await this.requireToolboxFeatures(id, ...features);
         // Not idempotent: a re-sent exec runs the caller's command a second time.
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/process/execute`, toApiExecRequest(request), { idempotent: false });
         return fromApiExecResult(response);
     }
     execStream(id, options) {
-        return openExecStream(this.baseURL, this.versionPrefix, this.patToken, id, options);
+        if (options.command?.trim() && options.argv?.length) {
+            throw new Error("set command or argv, not both");
+        }
+        // argv waits for the feature check: the start message goes out only once
+        // the agent has listed exec.argv, so an older one never receives it.
+        const ready = options.argv?.length ? this.requireToolboxFeatures(id, "exec.argv") : undefined;
+        return openExecStream(this.baseURLFor(id), this.versionPrefix, this.patToken, id, options, ready);
+    }
+    /**
+     * Watch a folder in the sandbox for changes. Resolves once the watch is in
+     * place, so a change made after it resolves is reported. gVisor and
+     * Firecracker sandboxes only: the others answer 501. Not retried: a stream
+     * is opened once.
+     */
+    async watchFiles(id, path, onEvent, options = {}) {
+        const query = `path=${encodeURIComponent(path)}${options.recursive ? "&recursive=true" : ""}`;
+        const routePath = `${this.versioned(`/sandboxes/${encodeURIComponent(id)}/toolbox/files/watch`)}?${query}`;
+        return openFileWatch(this.baseURLFor(id), routePath, this.patToken, onEvent, (detail) => this.fileWatchRefusal(id, routePath, detail));
+    }
+    /**
+     * Explains a watch whose WebSocket handshake failed. The WebSocket API
+     * hides a refused handshake's status and body, so the same request is sent
+     * again as plain HTTP: toolboxd checks the runtime, the path and its limits
+     * before the upgrade, so it answers with the real reason (501 on Docker or
+     * containerd, 404 for a missing folder, 429 at the watch limit). That GET
+     * is a diagnosis, sent once, never a retry of the stream.
+     */
+    async fileWatchRefusal(id, routePath, detail) {
+        const fallback = new Error(`file watch failed to start${detail}`);
+        let response;
+        let text;
+        try {
+            response = await this.fetchFn(`${this.baseURLFor(id)}${routePath}`, {
+                method: "GET",
+                headers: this.authHeaders(),
+                ...(this.signal ? { signal: this.signal } : {}),
+            });
+            text = await response.text();
+        }
+        catch {
+            return fallback;
+        }
+        let message;
+        try {
+            message = JSON.parse(text).error;
+        }
+        catch {
+            // Not JSON: a proxy's error page, or the upgrade's own refusal.
+        }
+        // An agent that predates file watching has no such route.
+        if (response.status === 404 && (response.headers.get(TOOLBOX_ROUTE_HEADER) === "none" || message === "not found")) {
+            return new MicroVMUnsupportedFeatureError(id, [FILE_WATCH_FEATURE]);
+        }
+        // toolboxd accepted the watch and only refused the plain-HTTP upgrade:
+        // the stream failed for some other reason, which `detail` holds.
+        if (response.ok || response.headers.has("sec-websocket-version")) {
+            return fallback;
+        }
+        return decodeError(new Response(text, { status: response.status, headers: response.headers }));
     }
     async createSession(id, options) {
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/sessions`, toApiCreateSessionOptions(options));
@@ -508,23 +848,258 @@ export class APIClient {
         return this.doBytes(`${this.versionPrefix}/sandboxes/${id}/sessions/${sessionID}/recording`);
     }
     attachSession(id, sessionID, options = {}) {
-        return openSessionAttach(this.baseURL, this.versionPrefix, this.patToken, id, sessionID, options);
+        return openSessionAttach(this.baseURLFor(id), this.versionPrefix, this.patToken, id, sessionID, options);
     }
-    async uploadFile(id, targetPath, data) {
+    /**
+     * Plain and atomic uploads retry on 421/429/502/503/504; `append` and
+     * `createOnly` only on 429/503, because a second send would append twice
+     * or find the first one's file.
+     */
+    async uploadFile(id, targetPath, data, options = {}) {
+        const path = await this.uploadPath(id, options);
         const form = new FormData();
         form.set("path", targetPath);
         form.set("file", toBlob(data), basename(targetPath));
-        const response = await this.request("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/files/upload`, { body: form });
+        const response = await this.request("POST", path, { body: form }, { idempotent: !(options.append || options.createOnly) });
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+    }
+    /** The upload route with the write options as query, after the /version check they need. */
+    async uploadPath(id, options) {
+        const query = new URLSearchParams();
+        if (options.append)
+            query.set("append", "true");
+        if (options.createOnly)
+            query.set("create_only", "true");
+        if (options.atomic)
+            query.set("atomic", "true");
+        if (options.mode !== undefined)
+            query.set("mode", options.mode.toString(8));
+        if (query.size > 0) {
+            // An older agent ignores these; createOnly would replace a file.
+            await this.requireToolboxFeatures(id, FEATURE_WRITE_OPTIONS);
+        }
+        return `${this.versionPrefix}/sandboxes/${id}/toolbox/files/upload${query.size > 0 ? `?${query.toString()}` : ""}`;
+    }
+    /**
+     * Upload from a stream a piece at a time, so a large file never sits in
+     * memory. The options are {@link uploadFile}'s. The data is read as it is
+     * sent, so the request is sent once and never retried. Needs a `fetch` that
+     * can send a streamed body (Node.js 18 and later).
+     */
+    async uploadFileStream(id, targetPath, data, options = {}) {
+        const path = await this.uploadPath(id, options);
+        const boundary = `----aerolvm-${newIdempotencyKey()}`;
+        const encoder = new TextEncoder();
+        const head = encoder.encode(`--${boundary}\r\nContent-Disposition: form-data; name="path"\r\n\r\n${targetPath}\r\n` +
+            `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${basename(targetPath)}"\r\n` +
+            "Content-Type: application/octet-stream\r\n\r\n");
+        const tail = encoder.encode(`\r\n--${boundary}--\r\n`);
+        const parts = (async function* () {
+            yield head;
+            if (data instanceof ReadableStream) {
+                const reader = data.getReader();
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    yield value;
+                }
+            }
+            else {
+                yield* data;
+            }
+            yield tail;
+        })();
+        const body = new ReadableStream({
+            async pull(controller) {
+                const next = await parts.next();
+                if (next.done)
+                    controller.close();
+                else
+                    controller.enqueue(next.value);
+            },
+        });
+        const init = {
+            body,
+            // Node's fetch sends a streamed body only with duplex "half".
+            duplex: "half",
+            headers: { "Content-Type": `multipart/form-data; boundary=${boundary}` },
+        };
+        const response = await this.request("POST", path, init, { idempotent: false, sendOnce: true });
         if (!response.ok) {
             throw await decodeError(response);
         }
     }
-    async downloadFile(id, targetPath) {
+    /**
+     * Copy the local folder `localDir` into `remoteDir` in the sandbox (made if
+     * missing). The folder is packed as a gzipped tar and the sandbox unpacks it
+     * safely: no entry can land outside `remoteDir`. Symlinks are sent as links,
+     * hard-linked files as separate files; devices, pipes and sockets are
+     * skipped. The archive is built in memory and sent once, never retried.
+     * Node.js only.
+     */
+    async uploadDir(id, localDir, remoteDir) {
+        if (!(await stat(localDir)).isDirectory()) {
+            throw new Error(`${localDir} is not a folder`);
+        }
+        await this.requireToolboxFeatures(id, FEATURE_EXTRACT);
+        const archive = gzipSync(tarArchive(await folderEntries(localDir, "")));
+        const form = new FormData();
+        form.set("path", remoteDir);
+        form.set("file", new Blob([archive]), "upload.tar.gz");
+        const response = await this.request("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/files/upload?extract=true`, { body: form }, { idempotent: false, sendOnce: true });
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+    }
+    async downloadFile(id, targetPath, options = {}) {
+        const stream = await this.downloadFileStream(id, targetPath, options);
+        return new Uint8Array(await new Response(stream).arrayBuffer());
+    }
+    /**
+     * Open a file for reading a piece at a time, so a large file never sits in
+     * memory. With `maxBytes`, a larger file is refused before reading when the
+     * server states the size, and otherwise the stream errors as soon as more
+     * arrives. The request retries until the file starts to arrive.
+     */
+    async downloadFileStream(id, targetPath, options = {}) {
         const response = await this.request("GET", `${this.versionPrefix}/sandboxes/${id}/toolbox/files/download?path=${encodeURIComponent(targetPath)}`);
         if (!response.ok) {
             throw await decodeError(response);
         }
-        return new Uint8Array(await response.arrayBuffer());
+        const body = response.body ?? new Response(new Uint8Array()).body;
+        const max = options.maxBytes;
+        if (max === undefined) {
+            return body;
+        }
+        const length = response.headers.get("content-length");
+        if (length !== null && Number(length) > max) {
+            await body.cancel().catch(() => undefined);
+            throw new MicroVMFileTooLargeError(targetPath, max);
+        }
+        let seen = 0;
+        return body.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                if (seen + chunk.length > max) {
+                    controller.enqueue(chunk.subarray(0, max - seen));
+                    controller.error(new MicroVMFileTooLargeError(targetPath, max));
+                    return;
+                }
+                seen += chunk.length;
+                controller.enqueue(chunk);
+            },
+        }));
+    }
+    // File verbs beyond upload and download (plans/agent-sandbox-feature-
+    // parity.md, F1), through the sandbox's toolbox. A sandbox whose agent
+    // predates them fails closed with MicroVMUnsupportedFeatureError instead of
+    // ignoring a safety option; WASM and V8 isolate sandboxes answer 501.
+    //
+    // Retries: listFiles, getFileInfo, fileExists, searchFiles, findInFiles,
+    // deleteFile and makeDir are safe to re-send and retry on 421, 429, 502,
+    // 503 and 504 (a retried delete or mkdir whose work is already done counts
+    // as success). moveFile and copyFile retry only on 429 and 503, because a
+    // lost reply may hide a move that happened.
+    toolboxPath(id, route, query) {
+        return `${this.versionPrefix}/sandboxes/${encodeURIComponent(id)}/toolbox${route}?${new URLSearchParams(query).toString()}`;
+    }
+    /** Sends a body-less file call and discards a success reply. */
+    async fileCall(method, path, options) {
+        const response = await this.request(method, path, {}, options);
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+        await response.body?.cancel().catch(() => undefined);
+    }
+    async listFiles(id, path, options = {}) {
+        const depth = options.depth ?? 1;
+        const limit = options.limit ?? DEFAULT_LIST_LIMIT;
+        if (depth < 1 || limit < 1) {
+            throw new Error("depth and limit must be at least 1");
+        }
+        await this.requireToolboxFeatures(id, FEATURE_FILE_VERBS);
+        const response = await this.request("GET", this.toolboxPath(id, "/files", { path, depth: String(depth), limit: String(limit), extended: "true" }));
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+        const items = ((await response.json()) ?? []);
+        const base = path.replace(/\/+$/, "");
+        return {
+            entries: items.map((item) => fromApiFileInfo(item, `${base}/${item.name ?? ""}`)),
+            truncated: response.headers.get("x-toolbox-truncated") === "true",
+        };
+    }
+    async getFileInfo(id, path) {
+        // extended=true only adds fields; an older agent that ignores it answers
+        // fields this still reads, so no /version check.
+        const item = await this.doJSON("GET", this.toolboxPath(id, "/files/info", { path, extended: "true" }));
+        return fromApiFileInfo(item ?? {}, path);
+    }
+    async fileExists(id, path) {
+        try {
+            await this.getFileInfo(id, path);
+            return true;
+        }
+        catch (err) {
+            if (isMissingFile(err)) {
+                return false;
+            }
+            throw err;
+        }
+    }
+    async deleteFile(id, path, options = {}) {
+        const query = { path };
+        if (options.recursive) {
+            query.recursive = "true";
+        }
+        await this.fileCall("DELETE", this.toolboxPath(id, "/files", query), { doneCode: "file_not_found" });
+    }
+    async makeDir(id, path, options = {}) {
+        const parents = options.parents ?? false;
+        if (!parents) {
+            // An older agent ignores parents=false and makes them anyway.
+            await this.requireToolboxFeatures(id, FEATURE_FILE_VERBS);
+        }
+        const query = { path, parents: String(parents) };
+        if (options.mode !== undefined) {
+            query.mode = options.mode.toString(8);
+        }
+        await this.fileCall("POST", this.toolboxPath(id, "/files/folder", query), { doneCode: "folder_exists" });
+    }
+    async moveFile(id, source, destination, options = {}) {
+        const overwrite = options.overwrite ?? false;
+        if (!overwrite) {
+            // An older agent ignores overwrite=false and replaces the destination.
+            await this.requireToolboxFeatures(id, FEATURE_FILE_VERBS);
+        }
+        await this.fileCall("POST", this.toolboxPath(id, "/files/move", { source, destination, overwrite: String(overwrite) }), { idempotent: false });
+    }
+    async copyFile(id, source, destination, options = {}) {
+        await this.requireToolboxFeatures(id, FEATURE_FILE_VERBS);
+        const query = {
+            source,
+            destination,
+            overwrite: String(options.overwrite ?? false),
+            recursive: String(options.recursive ?? false),
+        };
+        await this.fileCall("POST", this.toolboxPath(id, "/files/copy", query), { idempotent: false });
+    }
+    async searchFiles(id, path, pattern) {
+        const response = await this.doJSON("GET", this.toolboxPath(id, "/files/search", { path, pattern }));
+        return Array.isArray(response?.files) ? response.files.map(String) : [];
+    }
+    async findInFiles(id, path, text) {
+        const response = await this.doJSON("GET", this.toolboxPath(id, "/files/find", { path, pattern: text }));
+        if (!Array.isArray(response)) {
+            return [];
+        }
+        return response.map((m) => ({
+            file: String(m.file ?? ""),
+            line: Number(m.line ?? 0),
+            content: String(m.content ?? ""),
+        }));
     }
     /**
      * Publish a sandbox container port. The chosen wire protocol is selected by
@@ -540,13 +1115,60 @@ export class APIClient {
      * variant carries `host` / `hostPort` — everything else is in `url`.
      */
     async exposePort(id, port, options = {}) {
-        const body = options.protocol ? { protocol: options.protocol } : undefined;
+        // Only what the caller set: an omitted visibility keeps an exposed
+        // port's gate, so a plain retry never opens a token port.
+        const fields = {};
+        if (options.protocol) {
+            fields.protocol = options.protocol;
+        }
+        if (options.visibility) {
+            fields.visibility = options.visibility;
+        }
+        const body = Object.keys(fields).length > 0 ? fields : undefined;
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/ports/${port}`, body);
         return fromApiExposePortResponse(response);
     }
     async unexposePort(id, port) {
         await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}/ports/${port}`);
     }
+    /**
+     * Issue a signed token scoped to one sandbox (POST /v1/sandboxes/{id}/tokens).
+     * Not idempotent by nature: every call makes a new token, and the server
+     * stores none. It uses the normal retry tier: a retry after a lost answer
+     * makes a second token that nobody holds, which simply expires.
+     */
+    async createSandboxToken(id, options) {
+        const body = { expires_in: options.expiresIn };
+        if (options.port !== undefined && options.port !== 0) {
+            body.port = options.port;
+        }
+        if (options.pathPrefix) {
+            body.path_prefix = options.pathPrefix;
+        }
+        if (options.methods && options.methods.length > 0) {
+            body.methods = options.methods;
+        }
+        const r = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/tokens`, body);
+        return {
+            token: r.token,
+            tokenID: r.token_id,
+            sandboxID: r.sandbox_id,
+            ...(r.port ? { port: r.port } : {}),
+            ...(r.path_prefix ? { pathPrefix: r.path_prefix } : {}),
+            ...(r.methods && r.methods.length > 0 ? { methods: r.methods } : {}),
+            expiresAt: r.expires_at,
+        };
+    }
+    /**
+     * Make every token issued for one sandbox so far stop working
+     * (POST /v1/sandboxes/{id}/tokens/revoke). A token issued after it works.
+     * Safe to retry: a repeated call refuses the same tokens again (plus any
+     * issued in between), so it uses the normal retry tier.
+     */
+    async revokeSandboxTokens(id) {
+        const r = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/tokens/revoke`);
+        return { sandboxID: r.sandbox_id, tokensNotBefore: r.tokens_not_before };
+    }
     /**
      * Bind a custom hostname to a sandbox. The server lowercases the hostname
      * and returns the post-add list of bindings (sorted by hostname). Calling
@@ -628,6 +1250,8 @@ export class APIClient {
             params.set("cursor", options.cursor);
         if (options.incarnationID)
             params.set("incarnation_id", options.incarnationID);
+        if (options.caller)
+            params.set("caller", options.caller);
         const query = params.toString();
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/audit${query ? `?${query}` : ""}`);
         return fromApiAuditPage(response);
@@ -698,6 +1322,68 @@ export class APIClient {
     async deleteEgressProfile(name) {
         await this.doJSON("DELETE", this.versioned(`/egress-profiles/${encodeURIComponent(name)}`));
     }
+    // Warm pools are PUT/GET/DELETE of one entry: every call is safe to retry,
+    // so they keep the default (idempotent) retry tier.
+    async putWarmPool(image, options) {
+        return fromApiWarmPool(await this.doJSON("PUT", this.versioned(warmPoolPath(image)), {
+            depth: options.depth ?? 0,
+            min_depth: options.minDepth,
+            max_depth: options.maxDepth,
+            on_image_change: options.onImageChange,
+        }));
+    }
+    async getWarmPool(image) {
+        return fromApiWarmPool(await this.doJSON("GET", this.versioned(warmPoolPath(image))));
+    }
+    async listWarmPools() {
+        const response = await this.doJSON("GET", this.versioned("/warm-pools"));
+        return (response.pools ?? []).map(fromApiWarmPool);
+    }
+    async deleteWarmPool(image) {
+        await this.doJSON("DELETE", this.versioned(warmPoolPath(image)));
+    }
+    async putIdentityRole(tag, options) {
+        const response = await this.doJSON("PUT", this.identityRolePath(tag, options.team), {
+            min_role: options.minRole,
+        });
+        return fromApiIdentityRole(response);
+    }
+    async listIdentityRoles(options = {}) {
+        const params = new URLSearchParams();
+        if (options.team)
+            params.set("team", options.team);
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        if (options.limit)
+            params.set("limit", String(options.limit));
+        const query = params.toString();
+        const response = await this.doJSON("GET", this.versioned(`/identity/roles${query ? `?${query}` : ""}`));
+        const list = { roles: (response.roles ?? []).map(fromApiIdentityRole) };
+        if (response.next_cursor)
+            list.nextCursor = response.next_cursor;
+        return list;
+    }
+    async deleteIdentityRole(tag, options = {}) {
+        await this.doJSON("DELETE", this.identityRolePath(tag, options.team));
+    }
+    identityRolePath(tag, team) {
+        const path = `/identity/roles/${encodeURIComponent(tag)}`;
+        return this.versioned(team ? `${path}?team=${encodeURIComponent(team)}` : path);
+    }
+    async putTeamQuota(team, options) {
+        const response = await this.doJSON("PUT", this.versioned(`/teams/${encodeURIComponent(team)}/quota`), {
+            max_sandboxes: options.maxSandboxes,
+            max_cpu: options.maxCPU,
+            max_memory_mb: options.maxMemoryMB,
+        });
+        return fromApiTeamQuota(response);
+    }
+    async getTeamQuota(team) {
+        return fromApiTeamQuota(await this.doJSON("GET", this.versioned(`/teams/${encodeURIComponent(team)}/quota`)));
+    }
+    async deleteTeamQuota(team) {
+        await this.doJSON("DELETE", this.versioned(`/teams/${encodeURIComponent(team)}/quota`));
+    }
     async createTemplate(options) {
         const response = await this.doJSON("POST", this.versioned("/templates"), {
             id: options.id,
@@ -785,7 +1471,7 @@ export class APIClient {
         await this.doJSON("DELETE", this.versioned(`/tokens/${encodeURIComponent(trimmed)}`));
     }
     wrap(sandbox) {
-        return new SandboxResource(this, fromApiSandbox(sandbox));
+        return new SandboxResource(this.root ?? this, fromApiSandbox(sandbox));
     }
     async doJSON(method, path, body, options) {
         const init = { headers: { ...options?.headers } };
@@ -809,6 +1495,16 @@ export class APIClient {
         }
         return new Uint8Array(await response.arrayBuffer());
     }
+    authHeaders(base) {
+        const headers = new Headers(base);
+        if (this.patToken !== "") {
+            headers.set("Authorization", `Bearer ${this.patToken}`);
+        }
+        if (this.team !== "") {
+            headers.set(TEAM_HEADER, this.team);
+        }
+        return headers;
+    }
     /**
      * Low-level HTTP request with automatic retry for transient failures.
      *
@@ -827,27 +1523,105 @@ export class APIClient {
      * A 429 or 503 waits as long as its `Retry-After` asks (see
      * {@link retryDelayMs}). The client's `signal` ends the request and any
      * wait.
+     *
+     * A 421 that names another cell ({@link CELL_ENDPOINT_HEADER}) is not
+     * retried in place: the same request goes once to that cell instead, and
+     * later requests for that sandbox go straight there.
      */
     async request(method, path, init = {}, options = {}) {
-        const headers = new Headers(init.headers);
-        if (this.patToken !== "") {
-            headers.set("Authorization", `Bearer ${this.patToken}`);
-        }
-        if (this.team !== "") {
-            headers.set(TEAM_HEADER, this.team);
-        }
-        const url = `${this.baseURL}${path}`;
+        const headers = this.authHeaders(init.headers);
         const signal = init.signal ?? this.signal;
         const requestInit = { ...init, method, headers, ...(signal ? { signal } : {}) };
-        const { maxRetries } = this.retryConfig;
+        const sandboxID = sandboxIDInPath(path, this.versioned("/sandboxes/"));
+        let base = this.baseURLFor(sandboxID);
+        let response = await this.send(`${base}${path}`, requestInit, options);
+        const cell = this.cellEndpoint(response);
+        if (cell !== undefined) {
+            // Remembered even when the body cannot go again, so the caller's own
+            // retry goes to the right cell.
+            if (sandboxID !== undefined)
+                this.rememberCell(sandboxID, cell);
+            // The cell router answers before any work is done, so even an exec or
+            // a folder upload may go again; only a body that fetch has already
+            // read cannot.
+            if (!isReplayableBody(init.body))
+                return response;
+            response.body?.cancel().catch(() => undefined);
+            base = cell;
+            // send hands back a second 421 naming a cell as it is, and nothing
+            // follows it: two cells that disagree cannot bounce a request between
+            // them.
+            response = await this.send(`${base}${path}`, requestInit, options);
+        }
+        // A 404 from the remembered cell may mean the sandbox was deleted, so the
+        // next call asks the configured server again. A missing file says nothing
+        // about the sandbox, and forgetting on it would add a 421 to every poll.
+        if (response.status === 404 &&
+            sandboxID !== undefined &&
+            this.sandboxCells.get(sandboxID) === base &&
+            !isMissingFile(await decodeError(response.clone()))) {
+            this.sandboxCells.delete(sandboxID);
+        }
+        return response;
+    }
+    /** Where requests for sandbox `id` go: the cell it was found in, else the configured server. */
+    baseURLFor(id) {
+        return (id !== undefined && this.sandboxCells.get(id)) || this.baseURL;
+    }
+    rememberCell(id, cell) {
+        // Re-inserted so a re-learned entry counts as the newest.
+        this.sandboxCells.delete(id);
+        this.sandboxCells.set(id, cell);
+        if (this.sandboxCells.size > MAX_REMEMBERED_CELLS) {
+            const oldest = this.sandboxCells.keys().next().value;
+            if (oldest !== undefined)
+                this.sandboxCells.delete(oldest);
+        }
+    }
+    /**
+     * The cell base URL a 421 names, or `undefined` when it names none this
+     * client may send its token to: not an absolute http(s) URL, or plain http
+     * while the client was configured for https, which would let one bad
+     * answer move the token to clear text.
+     */
+    cellEndpoint(response) {
+        if (!isCellAnswer(response))
+            return undefined;
+        let url;
+        try {
+            url = new URL((response.headers.get(CELL_ENDPOINT_HEADER) ?? "").trim());
+        }
+        catch {
+            return undefined;
+        }
+        if (url.host === "" || (url.protocol !== "https:" && (url.protocol !== "http:" || /^https:/i.test(this.baseURL)))) {
+            return undefined;
+        }
+        // Built like the configured base URL: the cell's own path prefix stays,
+        // so /v1/... lands under it. A query, fragment or userinfo has no place
+        // in a base URL and is dropped.
+        return url.origin + stripTrailingSlashes(url.pathname);
+    }
+    /** One request to `url` with the retry loop described on {@link request}. */
+    async send(url, requestInit, options) {
+        const signal = requestInit.signal ?? undefined;
+        const maxRetries = options.sendOnce ? 0 : this.retryConfig.maxRetries;
         const idempotent = options.idempotent ?? true;
         const retryableStatusCodes = idempotent ? RETRYABLE_STATUS_CODES : REFUSED_STATUS_CODES;
         const isRetryableError = idempotent ? isTransientTransportError : isUnsentTransportError;
+        let mayHaveRun = false;
         for (let attempt = 0;; attempt++) {
             let retryAfter = null;
             try {
                 const response = await this.fetchFn(url, requestInit);
-                if (!retryableStatusCodes.has(response.status) || attempt >= maxRetries) {
+                if (mayHaveRun && options.doneCode && !response.ok && (await errorCode(response)) === options.doneCode) {
+                    response.body?.cancel().catch(() => undefined);
+                    return new Response(null, { status: 204 });
+                }
+                if (response.status === 502 || response.status === 504) {
+                    mayHaveRun = true;
+                }
+                if (!retryableStatusCodes.has(response.status) || attempt >= maxRetries || isCellAnswer(response)) {
                     return response;
                 }
                 if (REFUSED_STATUS_CODES.has(response.status)) {
@@ -862,24 +1636,56 @@ export class APIClient {
                 if (signal?.aborted || !isRetryableError(error) || attempt >= maxRetries) {
                     throw error;
                 }
+                mayHaveRun ||= !isUnsentTransportError(error);
             }
             await sleep(retryDelayMs(this.retryConfig, attempt, retryAfter, Date.now(), Math.random()), signal);
         }
     }
 }
 export class SandboxResource {
-    client;
+    /**
+     * When true, leaving an `await using` block deletes the sandbox (see
+     * `[Symbol.asyncDispose]`). Off by default, so the block ends without
+     * touching it; set it here or with `destroyOnExit` on `create` and
+     * `getOrCreate`.
+     */
+    destroyOnExit = false;
+    disposed = false;
+    /** The client for one call: the real one, or a view carrying the call's signal. */
+    api(call) {
+        return this.client.withSignal(call?.signal);
+    }
     constructor(client, sandbox) {
-        this.client = client;
+        // Not enumerable: it holds the token, so it must never reach toJSON,
+        // JSON.stringify or a log of the sandbox.
+        Object.defineProperty(this, "client", { value: client, enumerable: false });
         this.apply(sandbox);
     }
-    async refresh() {
-        const updated = await this.client.get(this.id);
+    /**
+     * Called when an `await using` block holding this sandbox ends. Deletes the
+     * sandbox only when {@link destroyOnExit} is true; otherwise does nothing.
+     * A sandbox that is already gone counts as deleted, and a second call does
+     * nothing.
+     */
+    async [Symbol.asyncDispose]() {
+        if (!this.destroyOnExit || this.disposed)
+            return;
+        try {
+            await this.client.destroy(this.id);
+        }
+        catch (err) {
+            if (!(err instanceof MicroVMNotFoundError))
+                throw err;
+        }
+        this.disposed = true;
+    }
+    async refresh(call) {
+        const updated = await this.api(call).get(this.id);
         this.apply(updated.toJSON());
         return this;
     }
-    async exec(command) {
-        return this.client.exec(this.id, typeof command === "string" ? { command } : command);
+    async exec(command, call) {
+        return this.api(call).exec(this.id, typeof command === "string" ? { command } : command);
     }
     /**
      * Read this sandbox's clone-generation token. The token changes whenever the
@@ -887,50 +1693,122 @@ export class SandboxResource {
      * clone (e.g. to re-run setup). It does NOT reseed in-guest PRNGs — see the
      * "Randomness in cloned sandboxes" docs page for the in-guest pattern.
      */
-    async cloneGeneration() {
-        return this.client.cloneGeneration(this.id);
+    async cloneGeneration(call) {
+        return this.api(call).cloneGeneration(this.id);
     }
     execStream(options) {
         return this.client.execStream(this.id, options);
     }
-    async createSession(options) {
-        return this.client.createSession(this.id, options);
+    /**
+     * Watch a folder in this sandbox for changes; see
+     * {@link APIClient.watchFiles}. gVisor and Firecracker sandboxes only.
+     */
+    async watchFiles(path, onEvent, options = {}) {
+        return this.client.watchFiles(this.id, path, onEvent, options);
+    }
+    async createSession(options, call) {
+        return this.api(call).createSession(this.id, options);
     }
-    async listSessions() {
-        return this.client.listSessions(this.id);
+    async listSessions(call) {
+        return this.api(call).listSessions(this.id);
     }
-    async getSession(sessionID) {
-        return this.client.getSession(this.id, sessionID);
+    async getSession(sessionID, call) {
+        return this.api(call).getSession(this.id, sessionID);
     }
-    async deleteSession(sessionID) {
-        await this.client.deleteSession(this.id, sessionID);
+    async deleteSession(sessionID, call) {
+        await this.api(call).deleteSession(this.id, sessionID);
     }
-    async signalSession(sessionID, signal) {
-        await this.client.signalSession(this.id, sessionID, signal);
+    async signalSession(sessionID, signal, call) {
+        await this.api(call).signalSession(this.id, sessionID, signal);
     }
-    async resizeSession(sessionID, cols, rows) {
-        await this.client.resizeSession(this.id, sessionID, cols, rows);
+    async resizeSession(sessionID, cols, rows, call) {
+        await this.api(call).resizeSession(this.id, sessionID, cols, rows);
     }
-    async sessionLog(sessionID) {
-        return this.client.sessionLog(this.id, sessionID);
+    async sessionLog(sessionID, call) {
+        return this.api(call).sessionLog(this.id, sessionID);
     }
-    async sessionRecording(sessionID) {
-        return this.client.sessionRecording(this.id, sessionID);
+    async sessionRecording(sessionID, call) {
+        return this.api(call).sessionRecording(this.id, sessionID);
     }
     attachSession(sessionID, options = {}) {
         return this.client.attachSession(this.id, sessionID, options);
     }
-    async uploadFile(targetPath, data) {
-        await this.client.uploadFile(this.id, targetPath, data);
+    /** Copy a local folder into the sandbox (Node.js only). See {@link APIClient.uploadDir}. */
+    async uploadDir(localDir, remoteDir, call) {
+        await this.api(call).uploadDir(this.id, localDir, remoteDir);
+    }
+    /** Upload a file. See {@link UploadFileOptions} for append, create-only, atomic and mode. */
+    async uploadFile(targetPath, data, options = {}, call) {
+        await this.api(call).uploadFile(this.id, targetPath, data, options);
+    }
+    async downloadFile(targetPath, options = {}, call) {
+        return this.api(call).downloadFile(this.id, targetPath, options);
+    }
+    /** Read a file as a stream. See {@link APIClient.downloadFileStream}. */
+    async downloadFileStream(targetPath, options = {}, call) {
+        return this.api(call).downloadFileStream(this.id, targetPath, options);
+    }
+    /** Upload from a stream, sent once. See {@link APIClient.uploadFileStream}. */
+    async uploadFileStream(targetPath, data, options = {}, call) {
+        await this.api(call).uploadFileStream(this.id, targetPath, data, options);
     }
-    async downloadFile(targetPath) {
-        return this.client.downloadFile(this.id, targetPath);
+    /** List a folder. See {@link ListFilesOptions}; `truncated` means more entries exist. */
+    async listFiles(path, options = {}, call) {
+        return this.api(call).listFiles(this.id, path, options);
     }
-    async exposePort(port, options) {
-        return this.client.exposePort(this.id, port, options);
+    /** Describe one path. A symlink is followed. */
+    async getFileInfo(path, call) {
+        return this.api(call).getFileInfo(this.id, path);
     }
-    async unexposePort(port) {
-        await this.client.unexposePort(this.id, port);
+    /** Whether a path exists. A missing sandbox throws; it is not `false`. */
+    async fileExists(path, call) {
+        return this.api(call).fileExists(this.id, path);
+    }
+    /** Delete a file, or a folder and its contents with `recursive: true`. */
+    async deleteFile(path, options = {}, call) {
+        await this.api(call).deleteFile(this.id, path, options);
+    }
+    /** Make a folder; with `parents: true`, like `mkdir -p`. */
+    async makeDir(path, options = {}, call) {
+        await this.api(call).makeDir(this.id, path, options);
+    }
+    /** Move or rename a file or folder. Without `overwrite`, an existing destination is refused (409). */
+    async moveFile(source, destination, options = {}, call) {
+        await this.api(call).moveFile(this.id, source, destination, options);
+    }
+    /** Copy a file, or a folder with `recursive: true`. */
+    async copyFile(source, destination, options = {}, call) {
+        await this.api(call).copyFile(this.id, source, destination, options);
+    }
+    /** Paths under `path` whose name matches a glob such as `*.ts`. */
+    async searchFiles(path, pattern, call) {
+        return this.api(call).searchFiles(this.id, path, pattern);
+    }
+    /** Each line under `path` that contains `text` (plain text). */
+    async findInFiles(path, text, call) {
+        return this.api(call).findInFiles(this.id, path, text);
+    }
+    async exposePort(port, options, call) {
+        return this.api(call).exposePort(this.id, port, options);
+    }
+    async unexposePort(port, call) {
+        await this.api(call).unexposePort(this.id, port);
+    }
+    /**
+     * Issue a signed token for this sandbox only, to hand to a browser or an
+     * end user. See {@link CreateSandboxTokenOptions}. Each call makes a new
+     * token; the server keeps no copy.
+     */
+    async createToken(options, call) {
+        return this.api(call).createSandboxToken(this.id, options);
+    }
+    /**
+     * Make every token issued for this sandbox so far stop working, toolbox
+     * and port tokens alike. A token made after the call works. Safe to call
+     * again.
+     */
+    async revokeTokens(call) {
+        return this.api(call).revokeSandboxTokens(this.id);
     }
     /**
      * Per-sandbox custom-hostname bindings. Exposed as a namespaced accessor
@@ -944,51 +1822,51 @@ export class SandboxResource {
         const client = this.client;
         const id = this.id;
         return {
-            add: (hostname, options) => client.addCustomDomain(id, hostname, options),
-            remove: (hostname) => client.removeCustomDomain(id, hostname),
-            list: () => client.listCustomDomains(id),
-            dns: () => client.customDomainDNS(id),
+            add: (hostname, options, call) => client.withSignal(call?.signal).addCustomDomain(id, hostname, options),
+            remove: (hostname, call) => client.withSignal(call?.signal).removeCustomDomain(id, hostname),
+            list: (call) => client.withSignal(call?.signal).listCustomDomains(id),
+            dns: (call) => client.withSignal(call?.signal).customDomainDNS(id),
         };
     }
-    async createSnapshot(name, options = {}) {
-        return this.client.createSnapshot(this.id, name, options);
+    async createSnapshot(name, options = {}, call) {
+        return this.api(call).createSnapshot(this.id, name, options);
     }
-    async start() {
-        const updated = await this.client.start(this.id);
+    async start(call) {
+        const updated = await this.api(call).start(this.id);
         this.apply(updated.toJSON());
         return this;
     }
-    async stop() {
-        const updated = await this.client.stop(this.id);
+    async stop(call) {
+        const updated = await this.api(call).stop(this.id);
         this.apply(updated.toJSON());
         return this;
     }
-    async destroy() {
-        await this.client.destroy(this.id);
+    async destroy(call) {
+        await this.api(call).destroy(this.id);
     }
-    async resize(options) {
-        const updated = await this.client.resize(this.id, options);
+    async resize(options, call) {
+        const updated = await this.api(call).resize(this.id, options);
         this.apply(updated.toJSON());
         return this;
     }
-    async updateLifecycle(lifecycle) {
-        const updated = await this.client.updateLifecycle(this.id, lifecycle);
+    async updateLifecycle(lifecycle, call) {
+        const updated = await this.api(call).updateLifecycle(this.id, lifecycle);
         this.apply(updated.toJSON());
         return this;
     }
-    async getNetworkUsage() {
-        return this.client.getNetworkUsage(this.id);
+    async getNetworkUsage(call) {
+        return this.api(call).getNetworkUsage(this.id);
     }
-    async setNetworkLimits(options) {
-        return this.client.setNetworkLimits(this.id, options);
+    async setNetworkLimits(options, call) {
+        return this.api(call).setNetworkLimits(this.id, options);
     }
     /**
      * Replaces this sandbox's egress policy while it runs. The call returns
      * once the new policy is enforced; sending the same policy again is a
      * no-op, so it is safe to retry.
      */
-    async setNetworkPolicy(options) {
-        const policy = await this.client.setNetworkPolicy(this.id, options);
+    async setNetworkPolicy(options, call) {
+        const policy = await this.api(call).setNetworkPolicy(this.id, options);
         this.networkBlockAll = policy.networkBlockAll;
         this.egressStatus = policy.egressStatus;
         this.egressProfiles = policy.egressProfiles.length ? policy.egressProfiles : undefined;
@@ -1001,19 +1879,21 @@ export class SandboxResource {
      * would have allowed it. A recording stays readable after the sandbox
      * switches to enforce, until it is destroyed.
      */
-    async learned() {
-        return this.client.getNetworkLearned(this.id);
+    async learned(call) {
+        return this.api(call).getNetworkLearned(this.id);
     }
     /**
      * Reads this sandbox's audit log: outbound connections and egress denials
      * (`kind: "egress"`), and secret reads. Denials carry `result: "failure"`
      * and the policy `reason`.
      */
-    async audit(options) {
-        return this.client.getAudit(this.id, options);
+    async audit(options, call) {
+        return this.api(call).getAudit(this.id, options);
     }
     toJSON() {
-        return cloneSandbox(this);
+        // Only the sandbox's own fields, not the SDK's flags on this object.
+        const { destroyOnExit: _destroyOnExit, disposed: _disposed, ...data } = this;
+        return cloneSandbox(data);
     }
     apply(sandbox) {
         Object.assign(this, cloneSandbox(sandbox));
@@ -1045,6 +1925,7 @@ function toApiCreateOptions(options) {
         platform_volumes: options.platformVolumes?.map(toApiPlatformVolumeMount),
         lifecycle: options.lifecycle ? toApiLifecycle(options.lifecycle) : undefined,
         failover: options.failover ? toApiFailover(options.failover) : undefined,
+        placement: options.placement ? { zone: options.placement.zone, labels: options.placement.labels } : undefined,
         runtime: options.runtime,
         durability: options.durability,
         module_ref: options.moduleRef,
@@ -1052,6 +1933,7 @@ function toApiCreateOptions(options) {
         custom_domains: options.customDomains,
         gpus: options.gpus ? toApiGPUOptions(options.gpus) : undefined,
         template_id: options.templateId,
+        identity: options.identity ? toApiIdentity(options.identity) : undefined,
     };
 }
 function toApiGPUOptions(gpus) {
@@ -1085,9 +1967,12 @@ function toApiResizeOptions(options) {
 function toApiExecRequest(request) {
     return {
         command: request.command,
+        argv: request.argv,
         workdir: request.workDir,
         env: request.env,
         timeout_seconds: request.timeoutSeconds,
+        max_stdout_bytes: request.maxStdoutBytes,
+        max_stderr_bytes: request.maxStderrBytes,
     };
 }
 function toApiCreateSessionOptions(options) {
@@ -1109,6 +1994,9 @@ function toApiLifecycle(lifecycle) {
         stop_at_age: lifecycle.stopAtAge,
         destroy_at_age: lifecycle.destroyAtAge,
         serverless: lifecycle.serverless,
+        restart_on_failure: lifecycle.restartOnFailure,
+        destroy_after_exit_for: lifecycle.destroyAfterExitFor,
+        destroy_at: lifecycle.destroyAt instanceof Date ? lifecycle.destroyAt.toISOString() : lifecycle.destroyAt,
     };
 }
 function toApiFailover(failover) {
@@ -1144,6 +2032,9 @@ function fromApiSandbox(sandbox) {
         updatedAt: sandbox.updated_at,
         lastActiveAt: sandbox.last_active_at,
         lastError: sandbox.last_error,
+        statusReason: (sandbox.status_reason || undefined),
+        // 0 is a real exit code; only an absent or null one is left out.
+        exitCode: sandbox.exit_code ?? undefined,
         containerCommand: sandbox.container_command,
         lifecycle: fromApiLifecycle(sandbox.lifecycle),
         failover: fromApiFailover(sandbox.failover),
@@ -1152,6 +2043,7 @@ function fromApiSandbox(sandbox) {
         moduleRef: sandbox.module_ref,
         moduleDigest: sandbox.module_digest,
         tenantId: sandbox.tenant_id,
+        identity: fromApiSandboxIdentity(sandbox.identity),
     };
 }
 // normalizeRuntime narrows the wire-level string to the union we expose, while
@@ -1257,6 +2149,7 @@ function fromApiExposedPort(port) {
         port: port.port,
         publicURL: port.public_url,
         createdAt: port.created_at,
+        ...(port.visibility === "token" ? { visibility: "token" } : {}),
     };
 }
 function fromApiExposePortResponse(response) {
@@ -1271,7 +2164,9 @@ function fromApiExposePortResponse(response) {
         case "tls":
             return { protocol: "tls", url: response.public_url };
         case "http":
-            return { protocol: "http", url: response.public_url };
+            return response.visibility === "token"
+                ? { protocol: "http", url: response.public_url, visibility: "token" }
+                : { protocol: "http", url: response.public_url };
     }
 }
 function fromApiExecResult(result) {
@@ -1280,6 +2175,10 @@ function fromApiExecResult(result) {
         stderr: result.stderr,
         exitCode: result.exit_code,
         durationMS: result.duration_ms,
+        timedOut: result.timed_out ?? false,
+        stdoutTruncated: result.stdout_truncated ?? false,
+        stderrTruncated: result.stderr_truncated ?? false,
+        signal: result.signal || undefined,
     };
 }
 function fromApiHealthStatus(status) {
@@ -1313,6 +2212,7 @@ function toApiPlatformVolumeMount(volume) {
         name: volume.name,
         path: volume.path,
         read_only: volume.readOnly,
+        delete_with_sandbox: volume.deleteWithSandbox,
     };
 }
 function fromApiMountSpecRedacted(mount) {
@@ -1385,6 +2285,12 @@ function fromApiLifecycle(lifecycle) {
     if (lifecycle?.serverless) {
         result.serverless = true;
     }
+    if (lifecycle?.restart_on_failure) {
+        result.restartOnFailure = true;
+    }
+    if (lifecycle?.destroy_after_exit_for !== undefined) {
+        result.destroyAfterExitFor = lifecycle.destroy_after_exit_for;
+    }
     return result;
 }
 function fromApiFailover(failover) {
@@ -1439,6 +2345,7 @@ function cloneSandbox(sandbox) {
         containerCommand: sandbox.containerCommand ? [...sandbox.containerCommand] : undefined,
         lifecycle: { ...sandbox.lifecycle },
         failover: sandbox.failover ? { ...sandbox.failover } : undefined,
+        identity: sandbox.identity ? { ...sandbox.identity } : undefined,
     };
 }
 function toBlob(data) {
@@ -1453,23 +2360,91 @@ function toBlob(data) {
     }
     return new Blob([Uint8Array.from(data)]);
 }
+/** The folder's contents as tar entries, names relative to it, sorted. */
+async function folderEntries(root, prefix) {
+    const entries = [];
+    const names = (await readdir(join(root, prefix))).sort();
+    for (const name of names) {
+        const rel = prefix === "" ? name : `${prefix}/${name}`;
+        const full = join(root, rel);
+        const info = await lstat(full);
+        const base = { name: rel, mode: info.mode & 0o7777, mtime: Math.floor(info.mtimeMs / 1000) };
+        if (info.isSymbolicLink()) {
+            entries.push({ ...base, type: "symlink", linkname: await readlink(full) });
+        }
+        else if (info.isDirectory()) {
+            entries.push({ ...base, type: "dir" }, ...(await folderEntries(root, rel)));
+        }
+        else if (info.isFile()) {
+            entries.push({ ...base, type: "file", data: await readFile(full) });
+        }
+        // Devices, pipes and sockets are skipped: the sandbox refuses them.
+    }
+    return entries;
+}
+/** The `code` of a JSON error reply, read from a clone so the body stays readable. */
+async function errorCode(response) {
+    try {
+        const payload = (await response.clone().json());
+        return typeof payload.code === "string" ? payload.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A missing file, not a missing sandbox (also a 404). Current agents say
+ * file_not_found; older ones send no code, but their message is the OS
+ * error, which ends "no such file or directory".
+ */
+function isMissingFile(err) {
+    if (!(err instanceof MicroVMApiError) || err.status !== 404) {
+        return false;
+    }
+    return err.code === "file_not_found" || (err.code === undefined && err.message.endsWith("no such file or directory"));
+}
+/**
+ * An older agent ignores extended=true and sends only Daytona's fields (a
+ * 32-bit size, no path), so each extended field falls back.
+ */
+function fromApiFileInfo(item, fallbackPath) {
+    const info = {
+        name: item.name ?? "",
+        path: item.path || fallbackPath,
+        isDir: item.isDir ?? false,
+        size: item.size_bytes ?? item.size ?? 0,
+        mode: item.mode ?? "",
+        permissions: item.permissions ?? "",
+        owner: item.owner ?? "",
+        group: item.group ?? "",
+        modTime: item.modTime ?? "",
+    };
+    if (typeof item.symlink_target === "string") {
+        info.symlinkTarget = item.symlink_target;
+    }
+    return info;
+}
 async function decodeError(response) {
     const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"), Date.now());
     try {
         const payload = (await response.json());
         if (typeof payload.error === "string" && payload.error !== "") {
             const code = typeof payload.code === "string" && payload.code !== "" ? payload.code : undefined;
-            return new MicroVMApiError(response.status, payload.error, { code, retryAfterMs });
+            return apiErrorFor(response.status, payload.error, { code, retryAfterMs });
         }
     }
     catch {
         // Not JSON (a proxy's error page) or no body: fall through to the
         // status-based message, with no code.
     }
-    return new MicroVMApiError(response.status, `request failed with status ${response.status}`, { retryAfterMs });
+    return apiErrorFor(response.status, `request failed with status ${response.status}`, { retryAfterMs });
 }
 const STREAM_PREFIX_STDOUT = 0x01;
 const STREAM_PREFIX_STDERR = 0x02;
+// toolboxd marks a 404 that means "no such route" with this header, as
+// opposed to a route that answered 404 for a missing file.
+const TOOLBOX_ROUTE_HEADER = "x-toolbox-route";
+const FILE_WATCH_FEATURE = "files.watch";
 // Pull whatever diagnostic detail the runtime gave us off a WebSocket "error"
 // event. Node 22's native WebSocket fires an ErrorEvent with `.error` /
 // `.message`; browsers' base WebSocket fires a bare Event. Returns "" when
@@ -1505,7 +2480,7 @@ function toWebSocketBinaryFrame(data) {
     frame.set(bytes);
     return frame;
 }
-function openExecStream(baseURL, versionPrefix, patToken, sandboxID, options) {
+function openExecStream(baseURL, versionPrefix, patToken, sandboxID, options, ready) {
     const wsURL = baseURL.replace(/^http/, "ws") + `${versionPrefix}/sandboxes/${encodeURIComponent(sandboxID)}/toolbox/process/exec/stream`;
     const WS = globalThis.WebSocket;
     if (!WS) {
@@ -1537,17 +2512,51 @@ function openExecStream(baseURL, versionPrefix, patToken, sandboxID, options) {
         if (resolved)
             return;
         resolved = true;
-        exitReject?.(new Error(msg));
+        exitReject?.(typeof msg === "string" ? new Error(msg) : msg);
     };
-    ws.addEventListener("open", () => {
+    // Frames the caller sends after the socket opened but before a delayed
+    // start message (argv's feature check) wait here, so the start message is
+    // always first. Before the socket opens, send fails as it always has.
+    let started = false;
+    const pending = [];
+    const send = (data) => {
+        if (!started && ws.readyState === 1) {
+            pending.push(data);
+            return;
+        }
+        ws.send(data);
+    };
+    const sendStart = () => {
         ws.send(JSON.stringify({
             command: options.command,
+            argv: options.argv,
             workdir: options.workdir,
             env: options.env,
             tty: options.tty ?? false,
             cols: options.cols ?? 0,
             rows: options.rows ?? 0,
         }));
+        started = true;
+        for (const data of pending.splice(0)) {
+            ws.send(data);
+        }
+    };
+    // The check can fail before the socket opens; mark it handled now so
+    // Node does not report an unhandled rejection, and act on it at "open".
+    ready?.catch(() => undefined);
+    ws.addEventListener("open", () => {
+        if (!ready) {
+            sendStart();
+            return;
+        }
+        ready.then(() => {
+            if (!resolved) {
+                sendStart();
+            }
+        }, (err) => {
+            failWith(err instanceof Error ? err : new Error(String(err)));
+            ws.close();
+        });
     });
     ws.addEventListener("message", (event) => {
         if (typeof event.data === "string") {
@@ -1595,18 +2604,18 @@ function openExecStream(baseURL, versionPrefix, patToken, sandboxID, options) {
         failWith(detail !== "" ? `websocket error: ${detail}` : "websocket error");
     });
     const sendBinary = (data) => {
-        ws.send(toWebSocketBinaryFrame(data));
+        send(toWebSocketBinaryFrame(data));
     };
     return {
         write: sendBinary,
         resize(cols, rows) {
-            ws.send(JSON.stringify({ type: "resize", cols, rows }));
+            send(JSON.stringify({ type: "resize", cols, rows }));
         },
         signal(name) {
-            ws.send(JSON.stringify({ type: "signal", signal: name }));
+            send(JSON.stringify({ type: "signal", signal: name }));
         },
         close() {
-            ws.send(JSON.stringify({ type: "close" }));
+            send(JSON.stringify({ type: "close" }));
         },
         done,
     };
@@ -1711,3 +2720,152 @@ function openSessionAttach(baseURL, versionPrefix, patToken, sandboxID, sessionI
         done,
     };
 }
+function fromApiFileEvent(raw) {
+    const e = (raw ?? {});
+    const event = {
+        type: typeof e.type === "string" ? e.type : "",
+        path: typeof e.path === "string" ? e.path : "",
+        isDir: e.is_dir === true,
+    };
+    if (typeof e.reason === "string" && e.reason !== "") {
+        event.reason = e.reason;
+    }
+    return event;
+}
+// openFileWatch opens toolboxd's /files/watch stream and resolves with its
+// handle once the "start" frame says the watch is in place. `refusal`
+// explains a handshake that never opened.
+// How long a file watch waits for the agent to say the watch is armed.
+export const WATCH_START_TIMEOUT_MS = 60_000;
+function openFileWatch(baseURL, routePath, patToken, onEvent, refusal) {
+    const WS = globalThis.WebSocket;
+    if (!WS) {
+        return Promise.reject(new Error("WebSocket is not available in this runtime — Node 22+ or a browser is required"));
+    }
+    // The PAT rides the subprotocol, as on execStream: browsers cannot set
+    // Authorization on a WebSocket handshake.
+    const ws = new WS(baseURL.replace(/^http/, "ws") + routePath, ["sandbox.bearer", patToken]);
+    let startResolve;
+    let startReject;
+    const started = new Promise((resolve, reject) => {
+        startResolve = resolve;
+        startReject = reject;
+    });
+    let endResolve;
+    let endReject;
+    const ended = new Promise((resolve, reject) => {
+        endResolve = resolve;
+        endReject = reject;
+    });
+    // A caller that never calls wait() must not see an unhandled rejection.
+    ended.catch(() => undefined);
+    let opened = false;
+    let isStarted = false;
+    let startFailed = false;
+    let settled = false;
+    let lastErrorDetail = "";
+    const finish = (err) => {
+        if (settled)
+            return;
+        settled = true;
+        if (err) {
+            endReject(err);
+        }
+        else {
+            endResolve();
+        }
+    };
+    const handle = {
+        stop() {
+            finish();
+            ws.close();
+        },
+        wait() {
+            return ended;
+        },
+    };
+    const fail = (detail) => {
+        clearTimeout(startTimer);
+        if (isStarted) {
+            finish(new Error(`file watch stream closed${detail}`));
+            return;
+        }
+        if (startFailed)
+            return;
+        startFailed = true;
+        if (opened) {
+            startReject(new Error(`file watch closed before it started${detail}`));
+            return;
+        }
+        void refusal(detail).then(startReject, startReject);
+    };
+    // The wait for "start" is bounded: a proxy that accepts the upgrade and
+    // then goes quiet would otherwise leave the caller waiting forever. Later
+    // frames are not bounded, since a quiet folder sends nothing.
+    const startTimer = setTimeout(() => {
+        if (isStarted || startFailed)
+            return;
+        startFailed = true;
+        startReject(new Error(`file watch did not start within ${WATCH_START_TIMEOUT_MS / 1000}s`));
+        ws.close();
+    }, WATCH_START_TIMEOUT_MS);
+    // In Node, the pending wait alone must not keep the process alive.
+    startTimer.unref?.();
+    ws.addEventListener("open", () => {
+        opened = true;
+    });
+    ws.addEventListener("message", (event) => {
+        if (typeof event.data !== "string")
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(event.data);
+        }
+        catch {
+            return;
+        }
+        switch (msg.type) {
+            case "start":
+                clearTimeout(startTimer);
+                if (!isStarted && !startFailed) {
+                    isStarted = true;
+                    startResolve(handle);
+                }
+                return;
+            case "events":
+                if (!Array.isArray(msg.events))
+                    return;
+                for (const raw of msg.events) {
+                    // stop() inside the callback ends delivery at once.
+                    if (settled)
+                        return;
+                    try {
+                        onEvent(fromApiFileEvent(raw));
+                    }
+                    catch (err) {
+                        // A throwing callback ends the watch; wait() reports why.
+                        finish(err instanceof Error ? err : new Error(String(err)));
+                        ws.close();
+                        return;
+                    }
+                }
+                return;
+            case "end":
+                finish(new Error(typeof msg.reason === "string" && msg.reason !== "" ? msg.reason : "file watch ended"));
+                ws.close();
+                return;
+        }
+    });
+    ws.addEventListener("close", (event) => {
+        const parts = [lastErrorDetail, describeWSClose(event)].filter((s) => s !== "");
+        fail(parts.length > 0 ? ` (${parts.join("; ")})` : "");
+    });
+    ws.addEventListener("error", (event) => {
+        const detail = describeWSError(event);
+        if (detail !== "") {
+            lastErrorDetail = detail;
+        }
+        fail(detail !== "" ? ` (${detail})` : "");
+    });
+    return started;
+}