@aerol-ai/aerolvm-sdk 0.6.4 → 0.7.0

package/dist/MicroVM.d.ts

@@ -1,11 +1,40 @@
 import { type APIVersion, type RetryConfig } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { BuildImageOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, EgressProfile, EgressProfileList, EgressProfileOptions, ListEgressProfilesOptions, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "./types.js";
+import type { APITokenList, BuildImageOptions, BuildImageResult, CloneGeneration, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, EgressProfile, EgressProfileList, EgressProfileOptions, ListEgressProfilesOptions, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "./types.js";
 type FetchLike = typeof fetch;
+/** Scoped API token calls, reached as `microvm.tokens`. */
+export interface Tokens {
+    /**
+     * Mint a token (admin only). The result's `token` is the secret, returned
+     * this once and never again. A 409 means the name is taken, possibly by an
+     * earlier attempt whose reply was lost; that secret cannot be recovered,
+     * so revoke the token and create it again.
+     */
+    create(options: CreateAPITokenOptions): Promise<CreatedAPIToken>;
+    /** List every token (auditor or admin); expired ones stay listed for 30 days. */
+    list(): Promise<APITokenList>;
+    /** Revoke a token by id (admin only). Revoking one already gone succeeds. */
+    revoke(id: string): Promise<void>;
+}
 export interface MicroVMConfig {
+    /**
+     * The bearer every request carries: the operator PAT, an `avm_` API token
+     * or an OIDC ID token. Defaults to `SB_PAT_TOKEN`, then its alias
+     * `SB_API_TOKEN`; when both are set, `SB_PAT_TOKEN` wins.
+     */
     patToken?: string;
     apiUrl?: string;
+    /**
+     * The team requests act for, sent as the `X-AerolVM-Team` header on every
+     * HTTP request. Defaults to `SB_TEAM`; with neither, no header is sent and
+     * the server uses the credential's first matching binding. The header only
+     * chooses among teams the credential is already bound to (a team it does
+     * not hold is refused with 403), and the operator PAT ignores it.
+     * WebSocket streams (`execStream`, `attachSession`) cannot carry custom
+     * headers from a browser or Node, so they go without it.
+     */
+    team?: string;
     fetch?: FetchLike;
     /**
      * Wire version of the sandbox daemon API to call. Defaults to the SDK's
@@ -17,14 +46,27 @@ export interface MicroVMConfig {
     /**
      * Retry policy for transient transport errors (socket closed, connection
      * reset) and retryable HTTP status codes (421, 429, 502, 503, 504). The SDK
-     * retries up to 3 times with exponential backoff by default. Pass
-     * `{ maxRetries: 0 }` to disable.
+     * retries up to 3 times with exponential backoff by default. `exec` retries
+     * only failures that prove the command never reached the server
+     * (connection refused, connect timeout, DNS) and HTTP 429/503, so a command
+     * never runs twice. Pass `{ maxRetries: 0 }` to disable. A 429 or 503
+     * waits as long as the server's `Retry-After` asks, up to
+     * `retry.maxRetryAfterMs` (30 s by default).
      */
     retry?: RetryConfig;
+    /**
+     * Cancels the client's HTTP requests: aborting it ends the request in
+     * flight and any retry wait, so a call never sits out a long
+     * `Retry-After` once aborted. Pass `AbortSignal.timeout(ms)` to bound
+     * how long the client may run. WebSocket streams are not affected.
+     */
+    signal?: AbortSignal;
 }
 export declare class MicroVM {
     readonly apiUrl: string;
     readonly patToken: string;
+    /** The team sent as `X-AerolVM-Team`, or `""` when none is. */
+    readonly team: string;
     private readonly client;
     constructor(config?: MicroVMConfig);
     create(options: CreateOptions): Promise<Sandbox>;
@@ -46,6 +88,12 @@ export declare class MicroVM {
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
     registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
+    /** Look a snapshot up by name. In a cluster the request is routed to the node holding the image. */
+    getSnapshot(name: string): Promise<SandboxSnapshot>;
+    /** List the caller's snapshots, one name-ordered page at a time. */
+    listSnapshots(options?: ListSnapshotsOptions): Promise<SnapshotList>;
+    /** Delete a snapshot by name (idempotent 404 if it does not exist). */
+    deleteSnapshot(name: string): Promise<void>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<Sandbox>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<Sandbox>;
@@ -143,6 +191,17 @@ export declare class MicroVM {
     get dns(): {
         target(): Promise<IngressTarget>;
     };
+    /**
+     * Who the server says the caller is: principal, role, team and when the
+     * credential expires. Every valid credential may ask.
+     */
+    whoami(): Promise<WhoAmI>;
+    /**
+     * Scoped API tokens (`avm_…`) for services and CI, as
+     * `microvm.tokens.create/list/revoke`. Same namespaced shape as
+     * {@link MicroVM.dns}.
+     */
+    get tokens(): Tokens;
     private wrap;
 }
 export {};

package/dist/MicroVM.js

@@ -1,25 +1,31 @@
 import { APIClient, stripTrailingSlashes } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 const defaultAPIURL = "http://127.0.0.1:21212";
-const authRequiredErrorMessage = "PAT token is required. Set patToken or SB_PAT_TOKEN.";
+const authRequiredErrorMessage = "PAT token is required. Set patToken, SB_PAT_TOKEN or SB_API_TOKEN.";
 export class MicroVM {
     apiUrl;
     patToken;
+    /** The team sent as `X-AerolVM-Team`, or `""` when none is. */
+    team;
     client;
     constructor(config = {}) {
-        const patToken = config.patToken ?? readEnv("SB_PAT_TOKEN") ?? "";
+        const patToken = config.patToken ?? readEnv("SB_PAT_TOKEN") ?? readEnv("SB_API_TOKEN") ?? "";
         const apiUrl = normalizeURL(config.apiUrl ?? readEnv("SB_API_URL") ?? defaultAPIURL);
+        const team = (config.team ?? readEnv("SB_TEAM") ?? "").trim();
         if (patToken === "") {
             throw new Error(authRequiredErrorMessage);
         }
         this.apiUrl = apiUrl;
         this.patToken = patToken;
+        this.team = team;
         this.client = new APIClient({
             baseURL: apiUrl,
             patToken,
+            team,
             fetch: config.fetch,
             apiVersion: config.apiVersion,
             retry: config.retry,
+            signal: config.signal,
         });
     }
     async create(options) {
@@ -69,6 +75,18 @@ export class MicroVM {
     async registerSnapshotFromImage(name, image, options = {}) {
         return this.client.registerSnapshotFromImage(name, image, options);
     }
+    /** Look a snapshot up by name. In a cluster the request is routed to the node holding the image. */
+    async getSnapshot(name) {
+        return this.client.getSnapshot(name);
+    }
+    /** List the caller's snapshots, one name-ordered page at a time. */
+    async listSnapshots(options = {}) {
+        return this.client.listSnapshots(options);
+    }
+    /** Delete a snapshot by name (idempotent 404 if it does not exist). */
+    async deleteSnapshot(name) {
+        return this.client.deleteSnapshot(name);
+    }
     async destroy(id) {
         await this.client.destroy(id);
     }
@@ -237,6 +255,26 @@ export class MicroVM {
             target: () => client.ingressDNS(),
         };
     }
+    /**
+     * Who the server says the caller is: principal, role, team and when the
+     * credential expires. Every valid credential may ask.
+     */
+    async whoami() {
+        return this.client.whoami();
+    }
+    /**
+     * Scoped API tokens (`avm_…`) for services and CI, as
+     * `microvm.tokens.create/list/revoke`. Same namespaced shape as
+     * {@link MicroVM.dns}.
+     */
+    get tokens() {
+        const client = this.client;
+        return {
+            create: (options) => client.createAPIToken(options),
+            list: () => client.listAPITokens(),
+            revoke: (id) => client.revokeAPIToken(id),
+        };
+    }
     wrap(sandbox) {
         return new Sandbox(this.client, sandbox);
     }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
-export type { MicroVMConfig } from "./MicroVM.js";
+export type { MicroVMConfig, Tokens } from "./MicroVM.js";
 export type { RetryConfig } from "./internal/client.js";
-export type { AddCustomDomainOptions, AuditEvent, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressInject, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkLearnedEntry, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, GetOptions, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, ListOptions, MountSpec, MountSpecRedacted, MountType, PlatformVolumeMount, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";
+export type { AddCustomDomainOptions, APIToken, APITokenList, CreateAPITokenOptions, CreatedAPIToken, WhoAmI, WhoAmIPrincipal, AuditEvent, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressInject, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkLearnedEntry, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, GetOptions, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, ListOptions, MountSpec, MountSpecRedacted, MountType, PlatformVolumeMount, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";

package/dist/internal/client.d.ts

@@ -1,6 +1,11 @@
 import { Image } from "../Image.js";
-import type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "../types.js";
+import type { AddCustomDomainOptions, APITokenList, BinaryLike, BuildImageOptions, BuildImageResult, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, ListSnapshotsOptions, RegisterSnapshotOptions, SnapshotList, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "../types.js";
 type FetchLike = typeof fetch;
+/**
+ * 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 declare const TEAM_HEADER = "X-AerolVM-Team";
 /**
  * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
  * client speaks. The SDK and the server version independently — bumping the
@@ -36,10 +41,24 @@ export interface RetryConfig {
      * waits when `maxRetries` is high. Defaults to `5000`.
      */
     maxDelayMs?: number;
+    /**
+     * Cap in milliseconds on the wait before re-sending a 429 or 503. The SDK
+     * waits as long as the server's `Retry-After` header asks (seconds or an
+     * HTTP date), never less than its own backoff, plus up to a fifth more so
+     * clients told the same value spread out; a longer ask is cut to this. A
+     * missing or malformed header uses the backoff above. Defaults to
+     * `30000`; `0` ignores `Retry-After`.
+     */
+    maxRetryAfterMs?: number;
 }
 export interface APIClientConfig {
     baseURL: string;
     patToken?: string;
+    /**
+     * Sent as the {@link TEAM_HEADER} header on every HTTP request. Empty or
+     * absent sends no header.
+     */
+    team?: string;
     fetch?: FetchLike;
     /**
      * Wire version to call. Defaults to "v1". Pin this if you need a specific
@@ -49,11 +68,37 @@ export interface APIClientConfig {
     apiVersion?: APIVersion;
     /**
      * Retry policy for transient transport errors (socket closed, connection
-     * reset) and retryable HTTP status codes (421, 429, 502, 503, 504). Pass
-     * `{ maxRetries: 0 }` to disable retry entirely.
+     * reset) and retryable HTTP status codes (421, 429, 502, 503, 504). `exec`
+     * is narrower: it retries only failures that prove the command never
+     * reached the server (connection refused, connect timeout, DNS) and HTTP
+     * 429/503. Pass `{ maxRetries: 0 }` to disable retry entirely.
      */
     retry?: RetryConfig;
+    /**
+     * Cancels the client's HTTP requests: aborting it ends the request in
+     * flight and any retry wait, so a call never sits out a long
+     * `Retry-After` once aborted. WebSocket streams are not affected.
+     */
+    signal?: AbortSignal;
 }
+/**
+ * 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 declare function parseRetryAfter(value: string | null | undefined, nowMs: number): number | undefined;
+/**
+ * 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 declare function retryDelayMs(config: Required<RetryConfig>, attempt: number, retryAfter: string | null, nowMs: number, random: number): number;
 /**
  * Trim trailing slashes from a URL without a backtracking regex. The natural
  * `value.replace(/\/+$/, "")` is an anchored `+` quantifier — a polynomial
@@ -64,9 +109,11 @@ export declare class APIClient {
     readonly baseURL: string;
     readonly apiVersion: APIVersion;
     private readonly patToken;
+    private readonly team;
     private readonly fetchFn;
     private readonly versionPrefix;
     private readonly retryConfig;
+    private readonly signal;
     constructor(config: APIClientConfig);
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
@@ -106,6 +153,9 @@ export declare class APIClient {
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
     registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
+    getSnapshot(name: string): Promise<SandboxSnapshot>;
+    listSnapshots(options?: ListSnapshotsOptions): Promise<SnapshotList>;
+    deleteSnapshot(name: string): Promise<void>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<SandboxResource>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<SandboxResource>;
@@ -181,19 +231,31 @@ export declare class APIClient {
     deleteWasmModule(id: string): Promise<void>;
     pushWasmModule(options: PushWasmModuleOptions): Promise<PushWasmModuleResult>;
     rebuildTemplate(id: string): Promise<Template>;
+    whoami(): Promise<WhoAmI>;
+    createAPIToken(options: CreateAPITokenOptions): Promise<CreatedAPIToken>;
+    listAPITokens(): Promise<APITokenList>;
+    revokeAPIToken(id: string): Promise<void>;
     private wrap;
     private doJSON;
     private doBytes;
     /**
      * 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 (421, 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.
      */
     private request;
 }

package/dist/internal/client.js

@@ -1,10 +1,40 @@
 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,
@@ -29,17 +59,76 @@ function fromApiEgressRule({ inject, ...rule }) {
 // 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([
@@ -69,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
@@ -81,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];
@@ -103,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.
@@ -272,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}`);
     }
@@ -284,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) {
@@ -571,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);
@@ -582,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);
         }
@@ -601,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).
      *
-     * HTTP-level retryable codes (421, 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 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.
+     *
+     * 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 {
@@ -826,6 +1028,15 @@ function toApiCreateOptions(options) {
         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) {

package/dist/types.d.ts

@@ -194,9 +194,10 @@ export interface CreateOptions {
      */
     networkEgressRules?: EgressRule[];
     /**
-     * Whether the sandbox may be exposed to the public internet. Omitted defaults
-     * to private (no public URL, `exposePort` fails). Set `true` to opt in to
-     * public exposure; `false` permanently refuses it for this sandbox.
+     * Whether the sandbox is public from boot. Omitted or `false` creates it
+     * private: no public URL and no ingress route. `true` makes it public from
+     * boot. Either way the first `exposePort` call makes the sandbox public, so
+     * `false` does not stop a later `exposePort`.
      */
     allowPublicTraffic?: boolean;
     /**
@@ -269,6 +270,13 @@ export interface CreateOptions {
      * `sandbox.customDomains.add(host)` for each entry after create.
      */
     customDomains?: string[];
+    /**
+     * Firecracker template id (from `createTemplate`); the template must be
+     * ready. Requires `runtime: "firecracker"` and `image`: pass the image the
+     * template was built from. The sandbox boots from the template's prepared
+     * rootfs instead of building one from `image` on every create.
+     */
+    templateId?: string;
 }
 export interface ResizeOptions {
     /** Number of CPU cores. Fractional values supported (e.g. 0.5). */
@@ -445,6 +453,19 @@ export interface SandboxSnapshot {
     memoryMB?: number;
     diskGB?: number;
 }
+/** Options for {@link MicroVM.listSnapshots}: one name-ordered page. */
+export interface ListSnapshotsOptions {
+    /** Maximum snapshots to return in this page. */
+    limit?: number;
+    /** Exclusive name cursor — pass the last name of the previous page. */
+    startingAfter?: string;
+}
+/** One page of snapshots from {@link MicroVM.listSnapshots}. */
+export interface SnapshotList {
+    snapshots: SandboxSnapshot[];
+    /** True when more snapshots remain after this page. */
+    hasMore: boolean;
+}
 /**
  * Discriminated result from `exposePort`. Branch on `protocol` to access the
  * fields that are meaningful for the chosen wire protocol — only the raw-TCP
@@ -482,8 +503,9 @@ export interface Sandbox {
     networkBlockAll: boolean;
     /**
      * Hostname-egress state on `get` for a sandbox whose allow list names
-     * hosts (container runtimes): "active", "held" or "unavailable". Absent
-     * otherwise, and on list results.
+     * hosts (container runtimes): "active", "held" or "unavailable";
+     * "unenforced" when the server's firewall is off and nothing filters the
+     * sandbox. Absent otherwise, and on list results.
      */
     egressStatus?: string;
     /** Egress profiles this sandbox references. */
@@ -629,7 +651,10 @@ export interface NetworkPolicy {
     networkEgressRules: EgressRule[];
     /** Hostname entries in force: inline plus every profile's (at most 1024). */
     effectiveHostnameCount: number;
-    /** "active", "held" or "unavailable" for hostname rules on a container. */
+    /**
+     * "active", "held" or "unavailable" for hostname rules on a container;
+     * "unenforced" when the server's firewall is off.
+     */
     egressStatus?: string;
 }
 /**
@@ -722,6 +747,59 @@ export interface EgressProfileList {
     /** Pass back as `cursor` for the next page; absent on the last one. */
     nextCursor?: string;
 }
+/** Who the caller is, as `microvm.whoami()` reports it. */
+export interface WhoAmIPrincipal {
+    /** `"operator"`, `"token"`, `"oidc"`, `"controlplane"`, ... */
+    kind: string;
+    /** Stable id: `"operator"`, `"tok_…"`, `"oidc:<issuer>:<sub>"`, ... */
+    id: string;
+    /** Display name; absent when the server has none. */
+    name?: string;
+}
+/** The body of `microvm.whoami()`: the caller's own resolved identity. */
+export interface WhoAmI {
+    principal: WhoAmIPrincipal;
+    /** `"viewer"`, `"runner"`, `"auditor"` or `"admin"`. */
+    role: string;
+    /** `"*"` for every team, a team name, or absent for a managed account. */
+    team?: string;
+    /** When the credential stops working (RFC 3339); absent if it never does. */
+    expiresAt?: string;
+}
+/** One scoped API token as `microvm.tokens.list()` returns it. Never the secret. */
+export interface APIToken {
+    /** Public id (`tok_…`): what `tokens.revoke` takes and audit records name. */
+    id: string;
+    name: string;
+    role: string;
+    /** A team name, or `"*"` for every team. */
+    team: string;
+    createdBy: string;
+    createdAt: string;
+    expiresAt: string;
+    /** Expired tokens no longer work; they stay listed for 30 days. */
+    expired: boolean;
+}
+/** `microvm.tokens.create()`'s result: the token plus its secret. */
+export interface CreatedAPIToken extends APIToken {
+    /** The secret (`avm_…`), returned this once and never stored by the server. */
+    token: string;
+}
+/** The body of `microvm.tokens.create()`. */
+export interface CreateAPITokenOptions {
+    /** 1 to 64 of `A-Z a-z 0-9 . _ -`, unique among the team's tokens. */
+    name: string;
+    /** `"viewer"`, `"runner"`, `"auditor"` or `"admin"`. */
+    role: string;
+    /** A team name, or `"*"` for every team. `auditor` and `admin` require `"*"`. */
+    team: string;
+    /** Required lifetime: `"90d"`, `"720h"` or any Go duration. */
+    expiresIn: string;
+}
+/** `microvm.tokens.list()`'s result. */
+export interface APITokenList {
+    tokens: APIToken[];
+}
 /** One destination a learn-mode sandbox reached. */
 export interface NetworkLearnedEntry {
     host: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js dist-test/internal/*.test.js"
   },
   "devDependencies": {
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.6",
     "typescript": "^7.0.2",
     "tsx": "^4.23.15"
   }