@aerol-ai/aerolvm-sdk 0.5.4 → 0.7.0

package/dist/internal/client.js

@@ -1,23 +1,134 @@
 import { basename } from "node:path";
 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 { 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";
 const DEFAULT_API_VERSION = "v1";
 const PATH_PREFIXES = {
     v1: V1_PATH_PREFIX,
 };
+function fromApiWhoAmI(w) {
+    const out = {
+        principal: { kind: w.principal.kind, id: w.principal.id },
+        role: w.role,
+    };
+    if (w.principal.name)
+        out.principal.name = w.principal.name;
+    if (w.team)
+        out.team = w.team;
+    if (w.expires_at)
+        out.expiresAt = w.expires_at;
+    return out;
+}
+function fromApiAPIToken(t) {
+    return {
+        id: t.id,
+        name: t.name,
+        role: t.role,
+        team: t.team,
+        createdBy: t.created_by,
+        createdAt: t.created_at,
+        expiresAt: t.expires_at,
+        expired: t.expired === true,
+    };
+}
+function fromApiEgressProfile(p) {
+    const out = {
+        name: p.name,
+        allowOut: p.allow_out ?? [],
+        generation: p.generation,
+        createdAt: p.created_at,
+        updatedAt: p.updated_at,
+    };
+    if (p.description)
+        out.description = p.description;
+    return out;
+}
+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;
+}
 /** HTTP status codes the retry loop considers transient. */
-const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+// 421 Misdirected Request: an owner answered for a sandbox it doesn't hold
+// (HTTP/2 connection coalescing, or a stale ingress route after failover).
+// The server closes the connection, so the retry reconnects and the ingress
+// re-routes it (plans/ingress-proxy-routing.md, review 2A).
+const RETRYABLE_STATUS_CODES = new Set([421, 429, 502, 503, 504]);
+// The subset a non-idempotent request (exec) may retry: 429 and 503 are the
+// server turning the request away before doing any work. 421, 502 and 504 come
+// from forwarding/proxy hops, and the status alone can't prove that no hop
+// already handed the command to the sandbox, so exec surfaces them. They are
+// also the statuses whose Retry-After paces clients: 429 when this caller is
+// 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]);
 /** Default retry settings when the caller doesn't supply a RetryConfig. */
 const DEFAULT_RETRY = {
     maxRetries: 3,
     baseDelayMs: 200,
     maxDelayMs: 5_000,
+    // An overloaded node asks for about a second, so the cap only bites on a
+    // long ask (maintenance, a misconfigured proxy), which should not hold a
+    // call for minutes per retry.
+    maxRetryAfterMs: 30_000,
 };
+// IMF-fixdate, the HTTP-date form servers send ("Sun, 06 Nov 1994 08:49:37
+// GMT"). Date.parse alone would also take "1" or a date with no zone, read in
+// local time.
+const IMF_FIXDATE = /^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+/**
+ * Reads a `Retry-After` value in either form RFC 9110 allows: delta-seconds
+ * (`"120"`) or an HTTP date. Returns the wait in milliseconds (0 for a date
+ * already past), or `undefined` for an absent or malformed value.
+ */
+export function parseRetryAfter(value, nowMs) {
+    const trimmed = (value ?? "").trim();
+    if (/^[0-9]+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    if (!IMF_FIXDATE.test(trimmed)) {
+        return undefined;
+    }
+    const when = Date.parse(trimmed);
+    return Number.isNaN(when) ? undefined : Math.max(when - nowMs, 0);
+}
+/**
+ * How long {@link APIClient.request} waits before re-sending. `attempt`
+ * counts from 0, `retryAfter` is a 429/503's `Retry-After` header (null
+ * otherwise) and `random` is uniform in [0, 1).
+ *
+ * Without a usable header it is the exponential backoff ±25%. With one, it
+ * never retries sooner than the server asked (nor sooner than the backoff)
+ * and adds up to a fifth so clients told the same value spread out.
+ * `maxRetryAfterMs` is a hard ceiling: when the server asks for at least
+ * that long the client is early anyway, so the spread goes below it instead.
+ */
+export function retryDelayMs(config, attempt, retryAfter, nowMs, random) {
+    const backoff = Math.min(config.baseDelayMs * 2 ** attempt, config.maxDelayMs);
+    const limit = config.maxRetryAfterMs;
+    const hint = limit > 0 ? parseRetryAfter(retryAfter, nowMs) : undefined;
+    if (hint === undefined) {
+        return backoff * (0.75 + 0.5 * random);
+    }
+    const target = Math.max(hint, backoff);
+    if (target >= limit) {
+        return limit - limit * 0.2 * random;
+    }
+    const upper = Math.min(target * 1.2, limit);
+    return target + (upper - target) * random;
+}
 /**
  * Returns `true` when the thrown `error` looks like a transport-level failure
  * that vanishes on retry (connection reset, socket closed by peer, DNS
  * blip). `undici` and Node core use several `cause.code` values; we check
- * the full cause chain.
+ * the full cause chain. A reset, EPIPE, read/headers/body timeout or "other
+ * side closed" can fire after the server already received the request, so
+ * this classification is only safe for idempotent requests.
  */
 function isTransientTransportError(error) {
     const codes = new Set([
@@ -47,6 +158,45 @@ function isTransientTransportError(error) {
     }
     return false;
 }
+/**
+ * Returns `true` only for transport failures that prove the request never
+ * left the client: the connection was refused, did not open before the
+ * connect timeout, or the host name did not resolve (transiently; ENOTFOUND
+ * is not retried for any request). Any other code in the cause chain means
+ * bytes may have reached the server, so the answer is `false`.
+ */
+function isUnsentTransportError(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current instanceof Error; depth++) {
+        const err = current;
+        switch (err.code) {
+            case undefined:
+                break;
+            case "ECONNREFUSED":
+            case "EAI_AGAIN":
+            case "UND_ERR_CONNECT_TIMEOUT":
+                return true;
+            case "ETIMEDOUT":
+                // Node uses ETIMEDOUT both for a connect that never completed and for
+                // an open socket that stopped answering; only the first is unsent.
+                return failedWhileConnecting(err);
+            default:
+                return false;
+        }
+        current = err.cause;
+    }
+    return false;
+}
+function failedWhileConnecting(err) {
+    if (err.syscall === "connect")
+        return true;
+    // With autoSelectFamily (Node's default), a host with several addresses
+    // fails with an AggregateError holding one error per connect attempt and no
+    // syscall of its own.
+    return (err instanceof AggregateError &&
+        err.errors.length > 0 &&
+        err.errors.every((inner) => inner?.syscall === "connect"));
+}
 /**
  * Trim trailing slashes from a URL without a backtracking regex. The natural
  * `value.replace(/\/+$/, "")` is an anchored `+` quantifier — a polynomial
@@ -59,21 +209,37 @@ export function stripTrailingSlashes(value) {
     }
     return value.slice(0, end);
 }
-/** Sleep with ±25% jitter so concurrent callers don't thundering-herd. */
-function jitteredDelay(baseMs) {
-    const jitter = 1 + (Math.random() - 0.5) * 0.5; // 0.75 – 1.25
-    return new Promise((resolve) => setTimeout(resolve, Math.round(baseMs * jitter)));
+/** Waits `ms`, or rejects with the signal's reason as soon as it aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
 }
 export class APIClient {
     baseURL;
     apiVersion;
     patToken;
+    team;
     fetchFn;
     versionPrefix;
     retryConfig;
+    signal;
     constructor(config) {
         this.baseURL = stripTrailingSlashes(config.baseURL);
         this.patToken = config.patToken ?? "";
+        this.team = (config.team ?? "").trim();
         this.fetchFn = config.fetch ?? fetch;
         this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
         this.versionPrefix = PATH_PREFIXES[this.apiVersion];
@@ -81,7 +247,9 @@ export class APIClient {
             maxRetries: config.retry?.maxRetries ?? DEFAULT_RETRY.maxRetries,
             baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
             maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_RETRY.maxDelayMs,
+            maxRetryAfterMs: config.retry?.maxRetryAfterMs ?? DEFAULT_RETRY.maxRetryAfterMs,
         };
+        this.signal = config.signal;
     }
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
@@ -151,12 +319,62 @@ export class APIClient {
         return { ...options, image: result.image };
     }
     async list(options) {
-        const path = this.versioned("/sandboxes") + buildTagQuery(options?.tags);
-        const response = await this.doJSON("GET", path);
-        return response.map((item) => this.wrap(item));
+        const items = [];
+        for await (const page of this.listPages(options)) {
+            items.push(...page);
+        }
+        return items;
+    }
+    /** Streams bounded cluster-list pages and never accumulates the full fleet. */
+    async *listPages(options) {
+        const basePath = this.versioned("/sandboxes") + buildSandboxListQuery(options);
+        let pageToken = "";
+        for (let page = 0; page < 100000; page++) {
+            const path = appendQueryParam(basePath, "page_token", pageToken);
+            const response = await this.request("GET", path);
+            if (!response.ok) {
+                throw await decodeError(response);
+            }
+            const partial = response.headers.get("X-Cluster-List-Partial");
+            const placementReady = response.headers.get("X-Cluster-List-Placement-Ready");
+            if (partial === "true" || placementReady === "false") {
+                throw new Error("incomplete cluster list");
+            }
+            const body = (await response.json());
+            yield (body ?? []).map((item) => this.wrap(item));
+            pageToken = (response.headers.get("X-Cluster-List-Next-Page-Token") ?? "").trim();
+            if (pageToken === "") {
+                return;
+            }
+        }
+        throw new Error("incomplete cluster list: exceeded max pages");
     }
-    async get(id) {
-        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}`);
+    /**
+     * Looks up the caller's sandbox by name with one request. The reply is only
+     * trusted when it holds at most one sandbox and that sandbox carries the
+     * requested name: a server that predates `?name=` ignores the filter and
+     * returns an ordinary list page, and acting on its first row would target
+     * the wrong sandbox.
+     */
+    async getByName(name, options) {
+        const trimmed = name.trim();
+        if (trimmed === "") {
+            throw new Error("sandbox name is required");
+        }
+        const path = this.versioned("/sandboxes") + buildSandboxListQuery({ name: trimmed, includeEnv: options?.includeEnv });
+        const body = await this.doJSON("GET", path);
+        const items = body ?? [];
+        if (items.length === 0) {
+            return null;
+        }
+        if (items.length > 1 || items[0].name !== trimmed) {
+            throw new Error(`${this.baseURL} does not support sandbox name lookup; use the sandbox ID or upgrade the server`);
+        }
+        return this.wrap(items[0]);
+    }
+    async get(id, options) {
+        const q = buildIncludeEnvQuery(options?.includeEnv);
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}${q}`);
         return this.wrap(response);
     }
     async start(id) {
@@ -200,6 +418,25 @@ export class APIClient {
             dockerfileContent: image.dockerfile,
         });
     }
+    async getSnapshot(name) {
+        return fromApiSandboxSnapshot(await this.doJSON("GET", this.versioned(`/snapshots/${encodeURIComponent(name)}`)));
+    }
+    async listSnapshots(options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit)
+            params.set("limit", String(options.limit));
+        if (options.startingAfter)
+            params.set("starting_after", options.startingAfter);
+        const query = params.toString();
+        const response = await this.doJSON("GET", this.versioned(`/snapshots${query ? `?${query}` : ""}`));
+        return {
+            snapshots: (response.snapshots ?? []).map(fromApiSandboxSnapshot),
+            hasMore: response.has_more ?? false,
+        };
+    }
+    async deleteSnapshot(name) {
+        await this.doJSON("DELETE", this.versioned(`/snapshots/${encodeURIComponent(name)}`));
+    }
     async destroy(id) {
         await this.doJSON("DELETE", `${this.versionPrefix}/sandboxes/${id}`);
     }
@@ -212,7 +449,8 @@ export class APIClient {
         return this.wrap(response);
     }
     async exec(id, request) {
-        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/toolbox/process/execute`, toApiExecRequest(request));
+        // 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) {
@@ -328,6 +566,22 @@ export class APIClient {
         const response = await this.doJSON("GET", "/health");
         return fromApiHealthStatus(response);
     }
+    async checkNetworkPolicy(options) {
+        const response = await this.doJSON("POST", this.versioned("/network/policy/check"), {
+            network_block_all: options.networkBlockAll,
+            network_allow_out: options.networkAllowOut,
+            network_deny_out: options.networkDenyOut,
+            destination: options.destination,
+        });
+        const result = {
+            allowed: response.allowed,
+            matchedRule: response.matched_rule ?? "",
+            defaultVerdict: response.default_verdict,
+        };
+        if (response.outside_ceiling)
+            result.outsideCeiling = response.outside_ceiling;
+        return result;
+    }
     async mounts(id) {
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/mounts`);
         return response.mounts.map(fromApiMountSpecRedacted);
@@ -340,10 +594,86 @@ export class APIClient {
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/network/usage`);
         return fromApiNetworkUsage(response);
     }
+    async getAudit(id, options = {}) {
+        const params = new URLSearchParams();
+        if (options.kind)
+            params.set("kind", options.kind);
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        if (options.incarnationID)
+            params.set("incarnation_id", options.incarnationID);
+        const query = params.toString();
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/audit${query ? `?${query}` : ""}`);
+        return fromApiAuditPage(response);
+    }
     async setNetworkLimits(id, options) {
         const response = await this.doJSON("PATCH", `${this.versionPrefix}/sandboxes/${id}/network/limits`, toApiSetNetworkLimitsOptions(options));
         return fromApiNetworkUsage(response);
     }
+    async setNetworkPolicy(id, options) {
+        const response = await this.doJSON("PUT", `${this.versionPrefix}/sandboxes/${id}/network/policy`, {
+            network_block_all: options.networkBlockAll ?? false,
+            network_allow_out: options.networkAllowOut ?? [],
+            network_deny_out: options.networkDenyOut ?? [],
+            egress_profiles: options.egressProfiles ?? [],
+            network_egress_mode: options.networkEgressMode,
+            network_egress_rules: options.networkEgressRules?.map(toApiEgressRule),
+        });
+        const policy = {
+            networkBlockAll: response.network_block_all,
+            networkAllowOut: response.network_allow_out ?? [],
+            networkDenyOut: response.network_deny_out ?? [],
+            egressProfiles: response.egress_profiles ?? [],
+            networkEgressMode: response.network_egress_mode ?? "enforce",
+            networkEgressRules: (response.network_egress_rules ?? []).map(fromApiEgressRule),
+            effectiveHostnameCount: response.effective_hostname_count ?? 0,
+        };
+        if (response.egress_status)
+            policy.egressStatus = response.egress_status;
+        return policy;
+    }
+    async getNetworkLearned(id) {
+        const r = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/network/learned`);
+        const learned = {
+            mode: r.mode,
+            truncated: r.truncated,
+            entries: (r.entries ?? []).map((e) => ({ host: e.host, ports: e.ports ?? [], firstSeen: e.first_seen, lastSeen: e.last_seen, hits: e.hits })),
+            cidrs: r.cidrs ?? [],
+            suggestedAllowOut: r.suggested_allow_out ?? [],
+        };
+        if (r.suggested_profile) {
+            learned.suggestedProfile = { allowOut: r.suggested_profile.allow_out ?? [], description: r.suggested_profile.description };
+        }
+        return learned;
+    }
+    async putEgressProfile(name, options) {
+        const response = await this.doJSON("PUT", this.versioned(`/egress-profiles/${encodeURIComponent(name)}`), {
+            allow_out: options.allowOut,
+            description: options.description,
+        });
+        return fromApiEgressProfile(response);
+    }
+    async getEgressProfile(name) {
+        return fromApiEgressProfile(await this.doJSON("GET", this.versioned(`/egress-profiles/${encodeURIComponent(name)}`)));
+    }
+    async listEgressProfiles(options = {}) {
+        const params = new URLSearchParams();
+        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(`/egress-profiles${query ? `?${query}` : ""}`));
+        const list = { profiles: (response.profiles ?? []).map(fromApiEgressProfile) };
+        if (response.next_cursor)
+            list.nextCursor = response.next_cursor;
+        return list;
+    }
+    async deleteEgressProfile(name) {
+        await this.doJSON("DELETE", this.versioned(`/egress-profiles/${encodeURIComponent(name)}`));
+    }
     async createTemplate(options) {
         const response = await this.doJSON("POST", this.versioned("/templates"), {
             id: options.id,
@@ -407,10 +737,33 @@ export class APIClient {
         const response = await this.doJSON("POST", `${this.versionPrefix}/templates/${id}/rebuild`);
         return fromApiTemplate(response);
     }
+    async whoami() {
+        return fromApiWhoAmI(await this.doJSON("GET", this.versioned("/whoami")));
+    }
+    async createAPIToken(options) {
+        const response = await this.doJSON("POST", this.versioned("/tokens"), {
+            name: options.name,
+            role: options.role,
+            team: options.team,
+            expires_in: options.expiresIn,
+        });
+        return { ...fromApiAPIToken(response), token: response.token };
+    }
+    async listAPITokens() {
+        const response = await this.doJSON("GET", this.versioned("/tokens"));
+        return { tokens: (response.tokens ?? []).map(fromApiAPIToken) };
+    }
+    async revokeAPIToken(id) {
+        const trimmed = id.trim();
+        if (trimmed === "") {
+            throw new Error("token id is required");
+        }
+        await this.doJSON("DELETE", this.versioned(`/tokens/${encodeURIComponent(trimmed)}`));
+    }
     wrap(sandbox) {
         return new SandboxResource(this, fromApiSandbox(sandbox));
     }
-    async doJSON(method, path, body) {
+    async doJSON(method, path, body, options) {
         const init = {};
         if (body !== undefined) {
             init.body = JSON.stringify(body);
@@ -418,7 +771,7 @@ export class APIClient {
                 "Content-Type": "application/json",
             };
         }
-        const response = await this.request(method, path, init);
+        const response = await this.request(method, path, init, options);
         if (!response.ok) {
             throw await decodeError(response);
         }
@@ -437,46 +790,59 @@ export class APIClient {
     /**
      * Low-level HTTP request with automatic retry for transient failures.
      *
-     * Transport-level errors (socket closed, connection reset, DNS blip) are
-     * always retried regardless of HTTP method — the request never reached the
-     * server so there is no idempotency concern.
+     * Transport-level errors (socket closed, connection reset, timeouts, DNS
+     * blip) and HTTP 421/429/502/503/504 are retried regardless of HTTP method.
+     * Several of those failures can happen after the server received the
+     * request, so a retry may deliver it twice; that is safe only because every
+     * mutating endpoint in the daemon is designed for idempotent retry (e.g.
+     * INSERT OR IGNORE + disambiguation).
+     *
+     * A request passed `{ idempotent: false }` (exec) retries only transport
+     * failures that prove the request never left the client and HTTP 429/503;
+     * everything else is surfaced to the caller rather than risk running the
+     * command twice.
      *
-     * HTTP-level retryable codes (429, 502, 503, 504) are retried for ALL
-     * methods because every mutating endpoint in the daemon is already
-     * designed for idempotent retry (e.g. INSERT OR IGNORE + disambiguation).
+     * 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.
      */
-    async request(method, path, init = {}) {
+    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 requestInit = { ...init, method, headers };
-        const { maxRetries, baseDelayMs, maxDelayMs } = this.retryConfig;
-        let lastError;
-        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const signal = init.signal ?? this.signal;
+        const requestInit = { ...init, method, headers, ...(signal ? { signal } : {}) };
+        const { maxRetries } = this.retryConfig;
+        const idempotent = options.idempotent ?? true;
+        const retryableStatusCodes = idempotent ? RETRYABLE_STATUS_CODES : REFUSED_STATUS_CODES;
+        const isRetryableError = idempotent ? isTransientTransportError : isUnsentTransportError;
+        for (let attempt = 0;; attempt++) {
+            let retryAfter = null;
             try {
                 const response = await this.fetchFn(url, requestInit);
-                // Retry on transient HTTP status codes.
-                if (RETRYABLE_STATUS_CODES.has(response.status) && attempt < maxRetries) {
-                    const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
-                    await jitteredDelay(delay);
-                    continue;
+                if (!retryableStatusCodes.has(response.status) || attempt >= maxRetries) {
+                    return response;
+                }
+                if (REFUSED_STATUS_CODES.has(response.status)) {
+                    retryAfter = response.headers.get("retry-after");
                 }
-                return response;
+                // Free the connection instead of holding it through the wait.
+                response.body?.cancel().catch(() => undefined);
             }
             catch (error) {
-                lastError = error;
-                // Only retry transport-level failures; anything else propagates.
-                if (!isTransientTransportError(error) || attempt >= maxRetries) {
+                // Only retry transport-level failures; anything else propagates. An
+                // aborted signal surfaces whatever fetch threw for it.
+                if (signal?.aborted || !isRetryableError(error) || attempt >= maxRetries) {
                     throw error;
                 }
-                const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
-                await jitteredDelay(delay);
             }
+            await sleep(retryDelayMs(this.retryConfig, attempt, retryAfter, Date.now(), Math.random()), signal);
         }
-        // Should be unreachable — the loop always throws or returns.
-        throw lastError;
     }
 }
 export class SandboxResource {
@@ -594,6 +960,36 @@ export class SandboxResource {
     async setNetworkLimits(options) {
         return this.client.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);
+        this.networkBlockAll = policy.networkBlockAll;
+        this.egressStatus = policy.egressStatus;
+        this.egressProfiles = policy.egressProfiles.length ? policy.egressProfiles : undefined;
+        this.networkEgressMode = policy.networkEgressMode === "learn" ? "learn" : undefined;
+        this.networkEgressRules = policy.networkEgressRules.length ? policy.networkEgressRules : undefined;
+        return policy;
+    }
+    /**
+     * Reads what this sandbox reached in learn mode and the allow list that
+     * 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);
+    }
+    /**
+     * 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);
+    }
     toJSON() {
         return cloneSandbox(this);
     }
@@ -603,6 +999,8 @@ export class SandboxResource {
 }
 function toApiCreateOptions(options) {
     return {
+        name: options.name,
+        tags: options.tags,
         image: options.image,
         cpu: options.cpu,
         memory_mb: options.memoryMB,
@@ -612,6 +1010,9 @@ function toApiCreateOptions(options) {
         network_block_all: options.networkBlockAll,
         network_allow_out: options.networkAllowOut,
         network_deny_out: options.networkDenyOut,
+        egress_profiles: options.egressProfiles,
+        network_egress_mode: options.networkEgressMode,
+        network_egress_rules: options.networkEgressRules?.map(toApiEgressRule),
         allow_public_traffic: options.allowPublicTraffic,
         mask_request_host: options.maskRequestHost,
         network_bytes_in_limit: options.networkBytesInLimit,
@@ -623,7 +1024,19 @@ function toApiCreateOptions(options) {
         lifecycle: options.lifecycle ? toApiLifecycle(options.lifecycle) : undefined,
         failover: options.failover ? toApiFailover(options.failover) : undefined,
         runtime: options.runtime,
+        durability: options.durability,
+        module_ref: options.moduleRef,
+        tenant_id: options.tenantId,
         custom_domains: options.customDomains,
+        gpus: options.gpus ? toApiGPUOptions(options.gpus) : undefined,
+        template_id: options.templateId,
+    };
+}
+function toApiGPUOptions(gpus) {
+    return {
+        vendor: gpus.vendor,
+        count: gpus.count,
+        device_ids: gpus.deviceIDs,
     };
 }
 function toApiRegisterSnapshotOptions(options) {
@@ -684,6 +1097,8 @@ function toApiFailover(failover) {
 function fromApiSandbox(sandbox) {
     return {
         id: sandbox.id,
+        name: sandbox.name || undefined,
+        tags: sandbox.tags,
         image: sandbox.image,
         status: sandbox.status,
         publicURL: sandbox.public_url,
@@ -695,6 +1110,11 @@ function fromApiSandbox(sandbox) {
         osUser: sandbox.os_user,
         env: sandbox.env,
         networkBlockAll: sandbox.network_block_all,
+        egressStatus: sandbox.egress_status || undefined,
+        egressProfiles: sandbox.egress_profiles?.length ? sandbox.egress_profiles : undefined,
+        egressProfilesApplied: sandbox.egress_profiles_applied?.length ? sandbox.egress_profiles_applied : undefined,
+        networkEgressMode: sandbox.network_egress_mode || undefined,
+        networkEgressRules: sandbox.network_egress_rules?.length ? sandbox.network_egress_rules.map(fromApiEgressRule) : undefined,
         toolboxEnabled: sandbox.toolbox_enabled,
         sshPublicKey: sandbox.ssh_public_key,
         exposedPorts: sandbox.exposed_ports?.map(fromApiExposedPort),
@@ -706,13 +1126,22 @@ function fromApiSandbox(sandbox) {
         lifecycle: fromApiLifecycle(sandbox.lifecycle),
         failover: fromApiFailover(sandbox.failover),
         runtime: normalizeRuntime(sandbox.runtime),
+        durability: sandbox.durability,
+        moduleRef: sandbox.module_ref,
+        moduleDigest: sandbox.module_digest,
+        tenantId: sandbox.tenant_id,
     };
 }
 // normalizeRuntime narrows the wire-level string to the union we expose, while
 // tolerating older sandboxd versions that don't send the field at all (treat
 // as "" — i.e. host default at start time).
 function normalizeRuntime(value) {
-    if (value === "docker" || value === "gvisor" || value === "kata") {
+    if (value === "docker" ||
+        value === "gvisor" ||
+        value === "kata" ||
+        value === "firecracker" ||
+        value === "wasm" ||
+        value === "isolate") {
         return value;
     }
     return "";
@@ -874,6 +1303,31 @@ function fromApiMountSpecRedacted(mount) {
         hasCredentials: mount.has_credentials,
     };
 }
+function fromApiAuditPage(page) {
+    const out = {
+        events: (page.events ?? []).map((e) => ({
+            time: e.time,
+            kind: e.kind,
+            result: e.result,
+            reason: e.reason,
+            destination: e.destination,
+            network: e.network,
+            actor: e.actor,
+            ref: e.ref,
+            eventID: e.event_id,
+            incarnationID: e.incarnation_id,
+            dropped: e.dropped,
+        })),
+        coverage: {
+            answered: page.coverage?.answered ?? [],
+            missing: page.coverage?.missing ?? [],
+            partial: page.coverage?.partial ?? false,
+        },
+    };
+    if (page.next_cursor)
+        out.nextCursor = page.next_cursor;
+    return out;
+}
 function fromApiNetworkUsage(usage) {
     return {
         sandboxID: usage.sandbox_id,
@@ -933,10 +1387,32 @@ function buildTagQuery(tags) {
     const parts = entries.map(([key, value]) => `tag.${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
     return "?" + parts.join("&");
 }
+function buildIncludeEnvQuery(includeEnv) {
+    return includeEnv ? "?include_env=true" : "";
+}
+function buildSandboxListQuery(options) {
+    let query = buildTagQuery(options?.tags);
+    if (options?.includeEnv) {
+        query = appendQueryParam(query, "include_env", "true");
+    }
+    const name = options?.name?.trim();
+    if (name) {
+        query = appendQueryParam(query, "name", name);
+    }
+    return query;
+}
+function appendQueryParam(path, key, value) {
+    if (!value) {
+        return path;
+    }
+    const sep = path.includes("?") ? "&" : "?";
+    return `${path}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+}
 function cloneSandbox(sandbox) {
     return {
         ...sandbox,
         env: sandbox.env ? { ...sandbox.env } : undefined,
+        tags: sandbox.tags ? { ...sandbox.tags } : undefined,
         exposedPorts: sandbox.exposedPorts?.map((port) => ({ ...port })),
         containerCommand: sandbox.containerCommand ? [...sandbox.containerCommand] : undefined,
         lifecycle: { ...sandbox.lifecycle },