@aerol-ai/aerolvm-sdk 0.4.1 → 0.5.2

package/dist/MicroVM.d.ts

@@ -1,7 +1,7 @@
 import { type APIVersion, type RetryConfig } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, ExecStreamHandle, ExecStreamOptions, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template } from "./types.js";
+import type { BuildImageOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "./types.js";
 type FetchLike = typeof fetch;
 export interface MicroVMConfig {
     patToken?: string;
@@ -48,6 +48,13 @@ export declare class MicroVM {
     buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
     health(): Promise<HealthStatus>;
     mounts(sandboxID: string): Promise<MountSpecRedacted[]>;
+    /**
+     * Read a sandbox's clone-generation token. The token changes whenever the
+     * sandbox is resumed from a snapshot, so a change signals "this is a clone."
+     * Read-only — the SDK cannot reseed a process inside the guest; see the
+     * "Randomness in cloned sandboxes" docs page for the in-guest reseed pattern.
+     */
+    cloneGeneration(sandboxID: string): Promise<CloneGeneration>;
     execStream(sandboxID: string, options: ExecStreamOptions): ExecStreamHandle;
     createSession(sandboxID: string, options: CreateSessionOptions): Promise<Session>;
     listSessions(sandboxID: string): Promise<Session[]>;
@@ -72,6 +79,21 @@ export declare class MicroVM {
     listTemplates(): Promise<Template[]>;
     getTemplate(id: string): Promise<Template>;
     deleteTemplate(id: string): Promise<void>;
+    /**
+     * Register a WASM module in the host catalogue. Resolution is synchronous —
+     * the returned row is typically already `ready`. Use the row's `id` or
+     * `moduleRef` on subsequent `create` calls with `runtime: "wasm"`.
+     */
+    createWasmModule(options: CreateWasmModuleOptions): Promise<WasmModule>;
+    listWasmModules(): Promise<WasmModule[]>;
+    getWasmModule(id: string): Promise<WasmModule>;
+    deleteWasmModule(id: string): Promise<void>;
+    /**
+     * Upload a compiled core-wasip1 module to the registry under your own
+     * credentials and get back the `oci://` ref to use as `moduleRef` on create.
+     * The daemon validates and forwards the bytes; it never stores them.
+     */
+    pushWasmModule(options: PushWasmModuleOptions): Promise<PushWasmModuleResult>;
     /**
      * Re-run the snapshot phase against an existing template. Idempotent
      * under concurrent retry: the daemon's CAS collapses N parallel calls

package/dist/MicroVM.js

@@ -1,4 +1,4 @@
-import { APIClient } from "./internal/client.js";
+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.";
@@ -80,6 +80,15 @@ export class MicroVM {
     async mounts(sandboxID) {
         return this.client.mounts(sandboxID);
     }
+    /**
+     * Read a sandbox's clone-generation token. The token changes whenever the
+     * sandbox is resumed from a snapshot, so a change signals "this is a clone."
+     * Read-only — the SDK cannot reseed a process inside the guest; see the
+     * "Randomness in cloned sandboxes" docs page for the in-guest reseed pattern.
+     */
+    async cloneGeneration(sandboxID) {
+        return this.client.cloneGeneration(sandboxID);
+    }
     execStream(sandboxID, options) {
         return this.client.execStream(sandboxID, options);
     }
@@ -132,6 +141,31 @@ export class MicroVM {
     async deleteTemplate(id) {
         await this.client.deleteTemplate(id);
     }
+    /**
+     * Register a WASM module in the host catalogue. Resolution is synchronous —
+     * the returned row is typically already `ready`. Use the row's `id` or
+     * `moduleRef` on subsequent `create` calls with `runtime: "wasm"`.
+     */
+    async createWasmModule(options) {
+        return this.client.createWasmModule(options);
+    }
+    async listWasmModules() {
+        return this.client.listWasmModules();
+    }
+    async getWasmModule(id) {
+        return this.client.getWasmModule(id);
+    }
+    async deleteWasmModule(id) {
+        await this.client.deleteWasmModule(id);
+    }
+    /**
+     * Upload a compiled core-wasip1 module to the registry under your own
+     * credentials and get back the `oci://` ref to use as `moduleRef` on create.
+     * The daemon validates and forwards the bytes; it never stores them.
+     */
+    async pushWasmModule(options) {
+        return this.client.pushWasmModule(options);
+    }
     /**
      * Re-run the snapshot phase against an existing template. Idempotent
      * under concurrent retry: the daemon's CAS collapses N parallel calls
@@ -164,7 +198,7 @@ export class MicroVM {
     }
 }
 function normalizeURL(value) {
-    return value.replace(/\/+$/, "");
+    return stripTrailingSlashes(value);
 }
 function readEnv(name) {
     if (typeof process === "undefined" || !process.env) {

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
 export type { MicroVMConfig } from "./MicroVM.js";
 export type { RetryConfig } from "./internal/client.js";
-export type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, UpdateLifecycleOptions, } from "./types.js";
+export type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, MountSpec, MountSpecRedacted, MountType, RegisterSnapshotOptions, 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,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CustomDomain, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template } from "../types.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, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "../types.js";
 type FetchLike = typeof fetch;
 /**
  * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
@@ -54,6 +54,12 @@ export interface APIClientConfig {
      */
     retry?: RetryConfig;
 }
+/**
+ * Trim trailing slashes from a URL without a backtracking regex. The natural
+ * `value.replace(/\/+$/, "")` is an anchored `+` quantifier — a polynomial
+ * ReDoS shape that CodeQL flags — so we strip by index instead, which is O(n).
+ */
+export declare function stripTrailingSlashes(value: string): string;
 export declare class APIClient {
     readonly baseURL: string;
     readonly apiVersion: APIVersion;
@@ -144,12 +150,18 @@ export declare class APIClient {
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
+    cloneGeneration(id: string): Promise<CloneGeneration>;
     getNetworkUsage(id: string): Promise<NetworkUsage>;
     setNetworkLimits(id: string, options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
     createTemplate(options: CreateTemplateOptions): Promise<Template>;
     listTemplates(): Promise<Template[]>;
     getTemplate(id: string): Promise<Template>;
     deleteTemplate(id: string): Promise<void>;
+    createWasmModule(options: CreateWasmModuleOptions): Promise<WasmModule>;
+    listWasmModules(): Promise<WasmModule[]>;
+    getWasmModule(id: string): Promise<WasmModule>;
+    deleteWasmModule(id: string): Promise<void>;
+    pushWasmModule(options: PushWasmModuleOptions): Promise<PushWasmModuleResult>;
     rebuildTemplate(id: string): Promise<Template>;
     private wrap;
     private doJSON;
@@ -196,6 +208,13 @@ export declare class SandboxResource implements Sandbox {
     constructor(client: APIClient, sandbox: Sandbox);
     refresh(): Promise<this>;
     exec(command: string | ExecRequest): Promise<ExecResult>;
+    /**
+     * Read this sandbox's clone-generation token. The token changes whenever the
+     * sandbox is resumed from a snapshot. Use it to detect that a sandbox is a
+     * 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.
+     */
+    cloneGeneration(): Promise<CloneGeneration>;
     execStream(options: ExecStreamOptions): ExecStreamHandle;
     createSession(options: CreateSessionOptions): Promise<Session>;
     listSessions(): Promise<Session[]>;

package/dist/internal/client.js

@@ -47,6 +47,18 @@ function isTransientTransportError(error) {
     }
     return false;
 }
+/**
+ * Trim trailing slashes from a URL without a backtracking regex. The natural
+ * `value.replace(/\/+$/, "")` is an anchored `+` quantifier — a polynomial
+ * ReDoS shape that CodeQL flags — so we strip by index instead, which is O(n).
+ */
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* "/" */) {
+        end--;
+    }
+    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
@@ -60,7 +72,7 @@ export class APIClient {
     versionPrefix;
     retryConfig;
     constructor(config) {
-        this.baseURL = config.baseURL.replace(/\/+$/, "");
+        this.baseURL = stripTrailingSlashes(config.baseURL);
         this.patToken = config.patToken ?? "";
         this.fetchFn = config.fetch ?? fetch;
         this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
@@ -320,6 +332,10 @@ export class APIClient {
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/mounts`);
         return response.mounts.map(fromApiMountSpecRedacted);
     }
+    async cloneGeneration(id) {
+        const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/toolbox/clone-generation`);
+        return fromApiCloneGeneration(response);
+    }
     async getNetworkUsage(id) {
         const response = await this.doJSON("GET", `${this.versionPrefix}/sandboxes/${id}/network/usage`);
         return fromApiNetworkUsage(response);
@@ -349,6 +365,44 @@ export class APIClient {
     async deleteTemplate(id) {
         await this.doJSON("DELETE", `${this.versionPrefix}/templates/${id}`);
     }
+    async createWasmModule(options) {
+        const response = await this.doJSON("POST", this.versioned("/wasm-modules"), {
+            id: options.id,
+            module_ref: options.moduleRef,
+            entrypoint: options.entrypoint,
+        });
+        return fromApiWasmModule(response);
+    }
+    async listWasmModules() {
+        const response = await this.doJSON("GET", this.versioned("/wasm-modules"));
+        return (response ?? []).map(fromApiWasmModule);
+    }
+    async getWasmModule(id) {
+        const response = await this.doJSON("GET", `${this.versionPrefix}/wasm-modules/${id}`);
+        return fromApiWasmModule(response);
+    }
+    async deleteWasmModule(id) {
+        await this.doJSON("DELETE", `${this.versionPrefix}/wasm-modules/${id}`);
+    }
+    async pushWasmModule(options) {
+        const params = new URLSearchParams({ name: options.name });
+        if (options.tag) {
+            params.set("tag", options.tag);
+        }
+        const headers = {
+            "Content-Type": "application/octet-stream",
+            "X-Registry-Token": options.registryToken,
+        };
+        if (options.registryUsername) {
+            headers["X-Registry-Username"] = options.registryUsername;
+        }
+        const response = await this.request("POST", this.versioned(`/wasm-modules/push?${params.toString()}`), { body: options.module, headers });
+        if (!response.ok) {
+            throw await decodeError(response);
+        }
+        const r = (await response.json());
+        return { moduleRef: r.module_ref, digest: r.digest, sizeBytes: r.size_bytes };
+    }
     async rebuildTemplate(id) {
         const response = await this.doJSON("POST", `${this.versionPrefix}/templates/${id}/rebuild`);
         return fromApiTemplate(response);
@@ -439,6 +493,15 @@ export class SandboxResource {
     async exec(command) {
         return this.client.exec(this.id, typeof command === "string" ? { command } : command);
     }
+    /**
+     * Read this sandbox's clone-generation token. The token changes whenever the
+     * sandbox is resumed from a snapshot. Use it to detect that a sandbox is a
+     * 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);
+    }
     execStream(options) {
         return this.client.execStream(this.id, options);
     }
@@ -674,6 +737,21 @@ function fromApiTemplate(template) {
         pushError: template.push_error,
     };
 }
+function fromApiWasmModule(module) {
+    return {
+        id: module.id,
+        moduleRef: module.module_ref,
+        status: module.status,
+        moduleSizeBytes: module.module_size_bytes,
+        digest: module.digest,
+        entrypoint: module.entrypoint,
+        hasWarm: module.has_warm,
+        lastError: module.last_error,
+        createdAt: module.created_at,
+        updatedAt: module.updated_at,
+        readyAt: module.ready_at,
+    };
+}
 function fromApiSandboxSnapshot(snapshot) {
     return {
         name: snapshot.name,
@@ -758,6 +836,12 @@ function fromApiHealthStatus(status) {
         version: status.version,
     };
 }
+function fromApiCloneGeneration(gen) {
+    return {
+        generation: gen.generation,
+        resumedAt: gen.resumed_at ?? 0,
+    };
+}
 function toApiMountSpec(mount) {
     return {
         type: mount.type,

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-export type SandboxStatus = "creating" | "started" | "stopped" | "destroyed" | "error";
+export type SandboxStatus = "creating" | "started" | "stopped" | "destroyed" | "error" | "passivated" | "awaiting_runtime";
+export type Durability = "ephemeral" | "passivatable" | "durable";
 export interface RegistryAuth {
     server: string;
     username: string;
@@ -164,7 +165,15 @@ export interface CreateOptions {
      *
      * GPU access is not supported with `"gvisor"`.
      */
-    runtime?: "docker" | "gvisor" | "kata" | "firecracker";
+    runtime?: "docker" | "gvisor" | "kata" | "firecracker" | "wasm";
+    /**
+     * Survival class across daemon restarts. Omit for the runtime default:
+     * `passivatable` for docker/gvisor/firecracker, `ephemeral` for wasm.
+     * `durable` is wasm-only and not yet implemented.
+     */
+    durability?: Durability;
+    /** WASM module reference. When runtime is wasm, may be used instead of image. */
+    moduleRef?: string;
     /**
      * Attach GPU resources to the sandbox. Omit for CPU-only workloads.
      * Not compatible with runtime="gvisor".
@@ -279,8 +288,13 @@ export interface IngressTarget {
     ips?: string[];
     source: IngressTargetSource;
 }
-/** DNS record types the daemon emits for custom-domain wiring. */
-export type DNSRecordType = "CNAME" | "A" | "AAAA";
+/**
+ * DNS record types the daemon emits for custom-domain wiring. `ANAME` and
+ * `ALIAS` only appear for an apex domain on a hostname ingress, where they are
+ * mutually-exclusive flattening alternatives to `CNAME` (add the one your
+ * provider supports — see each record's `notes`).
+ */
+export type DNSRecordType = "CNAME" | "A" | "AAAA" | "ANAME" | "ALIAS";
 /**
  * One ready-to-paste DNS record a user adds at their DNS provider to make a
  * custom domain reach the cluster. `name` is the leftmost label (or "@" for
@@ -375,7 +389,13 @@ export interface Sandbox {
      * Container runtime this sandbox is running under. Empty string indicates
      * a pre-migration row that resolves to the host default at start time.
      */
-    runtime: "" | "docker" | "gvisor" | "kata" | "firecracker";
+    runtime: "" | "docker" | "gvisor" | "kata" | "firecracker" | "wasm";
+    /** Survival class this sandbox was created with. */
+    durability?: Durability;
+    /** Resolved WASM module reference when runtime is wasm. */
+    moduleRef?: string;
+    /** sha256 hex digest of the resolved WASM module bytes. */
+    moduleDigest?: string;
     /** GPU configuration this sandbox was created with. Absent means no GPU. */
     gpus?: GPUOptions;
 }
@@ -469,6 +489,21 @@ export interface HealthStatus {
     sshGateway: string;
     version: string;
 }
+/**
+ * Clone-generation marker for a sandbox. The `generation` token changes every
+ * time the sandbox is resumed from a snapshot (i.e. it is a clone). A
+ * long-lived process running *inside* the sandbox can poll this and reseed its
+ * own userspace PRNGs when the token changes — two clones otherwise share the
+ * snapshot's frozen seed state. This is a read-only signal; the SDK cannot
+ * reseed an in-guest process from the client side. See the "Randomness in
+ * cloned sandboxes" docs page.
+ */
+export interface CloneGeneration {
+    /** Opaque token that changes on every resume-from-snapshot. */
+    generation: string;
+    /** Host wall-clock of the last resume, in unix nanoseconds. 0 = never resumed. */
+    resumedAt: number;
+}
 export type BinaryLike = Uint8Array | ArrayBuffer | Blob | string;
 /**
  * Lifecycle states reported by a Firecracker rootfs template. See
@@ -530,3 +565,56 @@ export interface CreateTemplateOptions {
     /** Optional floor for the ext4 image size, in MiB. */
     minSizeMiB?: number;
 }
+/** Catalogue lifecycle for POST /v1/wasm-modules rows. */
+export type WasmModuleStatus = "ready" | "failed";
+/**
+ * A WASM module catalogue entry. Resolved synchronously on the host and
+ * referenced by `moduleRef` when creating `runtime: "wasm"` sandboxes.
+ */
+export interface WasmModule {
+    id: string;
+    moduleRef: string;
+    status: WasmModuleStatus;
+    moduleSizeBytes?: number;
+    digest?: string;
+    entrypoint?: string;
+    hasWarm: boolean;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+    readyAt?: string;
+}
+export interface CreateWasmModuleOptions {
+    /** Optional explicit ID. Empty means the daemon uses the module digest. */
+    id?: string;
+    /** Module reference resolved on this host (file path, URL, etc.). */
+    moduleRef: string;
+    /** WASI entry export; defaults to `_start` on the daemon. */
+    entrypoint?: string;
+}
+/**
+ * Upload a compiled core-wasip1 `.wasm` to the registry. The daemon validates
+ * and forwards it under YOUR registry credentials — it never stores the bytes.
+ * The returned {@link PushWasmModuleResult.moduleRef} is what you pass as
+ * `moduleRef` on a later `create`.
+ */
+export interface PushWasmModuleOptions {
+    /** Target repository path, e.g. `tenant/my-app`. */
+    name: string;
+    /** Image tag; defaults to `latest`. */
+    tag?: string;
+    /** The compiled core-wasip1 module bytes. */
+    module: Uint8Array;
+    /** Registry login (your AOCR username). */
+    registryUsername?: string;
+    /** Registry token (your AOCR PAT). Required. */
+    registryToken: string;
+}
+export interface PushWasmModuleResult {
+    /** The `oci://` ref to pass as `moduleRef` on create. */
+    moduleRef: string;
+    /** sha256 content digest of the uploaded module. */
+    digest: string;
+    /** Uploaded size in bytes. */
+    sizeBytes: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.4.1",
+  "version": "0.5.2",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -21,8 +21,8 @@
     "test": "tsc -p tsconfig.test.json --outDir dist-test && node --test dist-test/*.test.js dist-test/internal/*.test.js"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "typescript": "^6.0.3",
-    "tsx": "^4.22.3"
+    "tsx": "^4.22.4"
   }
 }