@theagenticguy/microvms 0.7.0 → 0.9.0

package/README.md

@@ -1,53 +1,156 @@
 # @theagenticguy/microvms
 
-Node bindings over `microvms-core`, the client library for AWS Lambda MicroVMs.
+Run coding agents and their tools in sandboxed AWS Lambda MicroVMs. Give each
+task its own Linux workspace, execute commands, collect files, and terminate
+the VM from JavaScript or TypeScript. `AgentVm` runs Claude Code or Codex
+through Amazon Bedrock; `Sandbox` supports your own agent or command runner.
 
-```bash
+## Install
+
+```sh
 npm install @theagenticguy/microvms
 ```
 
-A prebuilt native addon per platform, selected through `optionalDependencies`. No compiler
-and no install-time download script runs on a consumer's machine.
+Requires Node.js **22.13.0+**. Native addons ship for Linux x64/ARM64 (glibc),
+macOS Apple Silicon, and Windows x64. TypeScript declarations are included.
 
-Requires Node >= 22.13.
+## Run your first command
 
-## Async-native
+With an existing image and AWS credentials, this is the 90-second path to a
+working SDK example. One-time AWS setup and image builds take longer.
 
-The core's async surface maps straight through: an exported `async` function runs on napi's
-managed runtime and returns a real `Promise`, with an error rejecting it. Exec output and
-stdin are handed across as `ReadableStream<Uint8Array>` rather than as async iterators a
-consumer would have to adapt.
+You need Lambda MicroVMs access, your normal AWS credential configuration,
+and an execution role. Follow [AWS setup](https://laithalsaadoon.github.io/microvms-agentd/learn/tutorial/first-run/)
+to set `AWS_REGION` and `MICROVM_EXECUTION_ROLE_ARN`. Then use the
+[CLI](https://laithalsaadoon.github.io/microvms-agentd/learn/tutorial/install/)
+to prepare an image containing `agentd`:
 
-## The traps are in the types
+```sh
+microvm build --name agent-tools --json
+export MICROVM_IMAGE='paste data.imageIdentifier from the result'
+```
 
-The constraints the platform enforces at runtime are shapes this package refuses to
-construct: a raw token cannot be passed where a session is expected, and a dollar amount is
-never a bare float. Each planted bypass has a test that goes red if the door reopens.
+Use the **image ARN**, in the same account and region as your credentials.
+The CLI can resolve image names; the SDK example takes the ARN directly.
+The CLI provisions `agentd` and uploads the build artifact for you.
+Shell examples use Bash or Zsh; in PowerShell, set variables with `$env:NAME='value'`.
+
+Save as `hello.mjs`:
+
+```js
+import { Region, Sandbox } from '@theagenticguy/microvms';
+
+const imageIdentifier = process.env.MICROVM_IMAGE;
+const executionRoleArn = process.env.MICROVM_EXECUTION_ROLE_ARN;
+if (!imageIdentifier || !executionRoleArn) {
+  throw new Error('Set MICROVM_IMAGE and MICROVM_EXECUTION_ROLE_ARN first');
+}
+const vm = await Sandbox.create(Region.parse(process.env.AWS_REGION ?? 'us-east-1'));
+try {
+  const session = await vm.run({ imageIdentifier, executionRoleArn });
+  const result = await session.runSync(['echo', 'hello from a sandbox']);
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  if (!result.ok) process.exitCode = 1;
+} finally {
+  const cleanup = await vm.terminate();
+  if (cleanup.failures.length || cleanup.undeleted.length) {
+    console.error('Cleanup needs attention:', cleanup);
+    process.exitCode = 1;
+  }
+}
+```
 
-## Coding agents in a VM
+```sh
+node hello.mjs
+```
 
-`AgentVm` is the L3 layer over the sandbox: an image with Claude Code and/or Codex CLI in
-it, a launch with egress, a Bedrock bearer token minted in process and installed as a file
-the agent sources, and one method that hands the agent a task as uid 1000 in `/workspace`.
+Expected output: `hello from a sandbox`. The VM is terminated after the
+command; the image stays available for reuse. `terminate()` returns once
+termination is accepted by default. Pass `{ waitForTerminated: true }` to
+wait for the final state. Inspect `failures` and `undeleted` because cleanup
+reports failures in its result.
 
-```ts
-const vm = await AgentVm.create(Region.usEast1(), [{ agent: 'codex' }]);
-await vm.launch({ imageIdentifier: imageArn, executionRoleArn: role });
-await vm.installAccess();
-console.log((await vm.promptSync('codex', 'Create hello.py that prints hello, run it.')).stdout);
-await vm.terminate();
-```
+## Run a coding agent
 
-`findImage`, `imageName`, `buildArtifact`, and `buildImage` cover the image, with the S3
-upload left to you. `installedAgents`, `installAgentAccess`, and `promptAgent` do the same
-over a bare `Session` for a process that holds only the identifier triple.
+First prepare a Claude Code image using the same AWS setup plus
+[Bedrock permissions](https://laithalsaadoon.github.io/microvms-agentd/learn/operations/run-coding-agents-on-bedrock/).
+This builds or reuses the agent image and starts a temporary VM. Capture
+only its image ARN, then terminate that temporary VM:
 
-## Reading
+```sh
+MICROVM_AGENT_IMAGE="$(microvm agent-up --vm-name sdk-image --agent claude-code --json |
+  node -pe 'JSON.parse(require("node:fs").readFileSync(0, "utf8")).data.imageIdentifier')"
+export MICROVM_AGENT_IMAGE
+microvm terminate sdk-image --wait
+```
 
-- [Documentation](https://laithalsaadoon.github.io/microvms-agentd/)
-- [`docs/EMBEDDING.md`](https://github.com/laithalsaadoon/microvms-agentd/blob/main/docs/EMBEDDING.md)
-- [`docs/TRUST.md`](https://github.com/laithalsaadoon/microvms-agentd/blob/main/docs/TRUST.md)
+Save as `agent.mjs`. The agent writes a file inside its own VM; the SDK
+downloads that file before cleanup:
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { AgentVm, Region } from '@theagenticguy/microvms';
+
+const imageIdentifier = process.env.MICROVM_AGENT_IMAGE;
+const executionRoleArn = process.env.MICROVM_EXECUTION_ROLE_ARN;
+if (!imageIdentifier || !executionRoleArn) {
+  throw new Error('Set MICROVM_AGENT_IMAGE and MICROVM_EXECUTION_ROLE_ARN first');
+}
+const vm = await AgentVm.create(Region.parse(process.env.AWS_REGION ?? 'us-east-1'));
+try {
+  const session = await vm.launch({ imageIdentifier, executionRoleArn });
+  await vm.installAccess();
+  const result = await vm.promptSync(
+    'claude-code',
+    'Create /workspace/hello.py that prints hello from a sandbox. Run it.',
+  );
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  if (!result.ok) throw new Error(`Agent exited with ${result.exitCode}`);
+  await writeFile('hello-from-agent.py', await session.downloadFile('/workspace/hello.py'));
+} finally {
+  const cleanup = await vm.terminate();
+  if (cleanup.failures.length || cleanup.undeleted.length) {
+    console.error('Cleanup needs attention:', cleanup);
+    process.exitCode = 1;
+  }
+}
+```
 
-## License
+```sh
+node agent.mjs
+```
 
-Apache-2.0
+For Codex, prepare the image with `--agent codex`, create the VM with
+`AgentVm.create(region, [{ agent: 'codex' }])`, and prompt `'codex'`.
+Agent images must contain the agent you select. Agents run as UID/GID 1000
+in `/workspace`; `installAccess()` installs a short-lived Bedrock token
+after launch. `AgentVm` enables internet egress for model calls.
+
+## Next steps
+
+For a `Sandbox` named `vm` and its `session`:
+
+| Need | API |
+| --- | --- |
+| Start a task and poll or stream later | `session.run(argv)` → `ExecHandle` |
+| Read live output as byte streams | `session.spawn(argv)` → `ExecProcess` |
+| Keep the VM awake while an exec runs | `await session.keepAwake({ whileBusy: true })` → `KeepAwake` |
+| Upload input or download results | `session.uploadFile(path, bytes)`, `session.downloadFile(path)` |
+| Transfer a directory | `session.uploadTar(path, tarBytes)`, `session.downloadTar(path)` |
+| Freeze and restore a workspace | `vm.suspend()`, `vm.resume()` |
+
+`runSync` returns a Promise: it starts a command, waits, and acknowledges
+its saved output. A nonzero exit is a result, so check `result.ok` or
+`result.exitCode`. Use `{ shell: true }` when passing a shell script string.
+Async library errors expose their `ERR_*` code through `error.cause.message`.
+
+Omitting `egress` does not block outbound traffic. For no egress, use
+`egressNetworkConnectors: [vpcConnectorArn]` with a VPC without an internet
+gateway, NAT gateway, or other internet route. `denyEgress` sets advisory proxy variables that
+workloads can bypass. Keep the guest execution role limited to the task's needs.
+
+[SDK tutorial](https://laithalsaadoon.github.io/microvms-agentd/learn/tutorial/from-code/)
+· [API reference](https://laithalsaadoon.github.io/microvms-agentd/reference/public-api/)
+· [Source](https://github.com/laithalsaadoon/microvms-agentd) · Apache-2.0

package/index.d.ts

@@ -1,6 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 /**
  * One VM with coding agents in it: the sandbox plus the specs it is built for.
  *
@@ -17,6 +25,15 @@ export declare class AgentVm {
    * the core before any AWS call.
    */
   static create(region: Region, agents?: Array<AgentSpecInput> | undefined | null): Promise<AgentVm>
+  /** Adopts the agent VM registered as `name` in `registry`; see `Sandbox.fromName`. */
+  static fromName(region: Region, name: string, registry: NameRegistry, agents?: Array<AgentSpecInput> | undefined | null, port?: number | undefined | null): Promise<AgentVm>
+  /**
+   * An agent VM for a VM another process launched; see `Sandbox.adopt`.
+   *
+   * `agents` states what the VM carries and defaults to Claude Code alone; read
+   * `installedAgents(session)` first when the adopting process does not know.
+   */
+  static adopt(region: Region, microvmId: string, endpoint: string, agentToken: string, agents?: Array<AgentSpecInput> | undefined | null, port?: number | undefined | null): Promise<AgentVm>
   /** The specs this VM carries, resolved, in profile order. */
   agents(): Array<AgentSpec>
   region(): Region
@@ -50,8 +67,10 @@ export declare class AgentVm {
   /**
    * Launches with egress and waits for the daemon to answer.
    *
-   * Egress is not optional: neither agent reaches Bedrock without it. The idle knobs default
-   * to the core's figures (ten-minute idle and suspended windows, a one-hour ceiling).
+   * Egress is not optional: neither agent reaches Bedrock without it. The managed internet
+   * connector is the default; `egressNetworkConnectors` replaces it with customer-managed
+   * VPC connectors, whose VPC must route to Bedrock. The idle knobs default to the core's
+   * figures (ten-minute idle and suspended windows, a one-hour ceiling).
    */
   launch(options: AgentLaunchOptions): Promise<Session>
   /**
@@ -102,8 +121,8 @@ export declare class BearerToken {
   /** The token text, for a caller writing it into an environment themselves. */
   expose(): string
   /**
-   * The presign's expiry, seconds since the epoch. An upper bound: the service also caps
-   * validity at the signing credentials' own expiry.
+   * Effective Unix expiry, capped at the known signing credential expiry.
+   * With missing credential expiry metadata this is only an upper bound.
    */
   get expiresAt(): number
   /** The region the token was minted for. */
@@ -122,6 +141,39 @@ export declare class BuildHookTimeout {
   toString(): string
 }
 
+/**
+ * MicroVM lifecycle by ID: get, list, suspend, resume, terminate, and wait.
+ *
+ * Holds no lifecycle state, so it checks nothing a `Sandbox` would (STATE-5, STATE-7,
+ * STATE-12). Use it when a process has only an identifier.
+ */
+export declare class ControlPlane {
+  /**
+   * Resolves credentials for `region` from the default chain. A factory because
+   * credential resolution is async.
+   */
+  static create(region: Region): Promise<ControlPlane>
+  /** `GetMicrovm`. */
+  get(microvmId: string): Promise<Microvm>
+  /** `ListMicrovms`, every page, optionally narrowed to one image and version. */
+  list(options?: ListMicrovmsOptions | undefined | null): Promise<Array<MicrovmSummary>>
+  /** `SuspendMicrovm`. Resolves once accepted; `waitForState` for SUSPENDED. */
+  suspend(microvmId: string): Promise<void>
+  /** `ResumeMicrovm`. Resolves once accepted; `waitForState` for RUNNING. */
+  resume(microvmId: string): Promise<void>
+  /** `TerminateMicrovm`. Resolves once accepted; `waitForState` for TERMINATED. */
+  terminate(microvmId: string): Promise<void>
+  /**
+   * Polls `GetMicrovm` until the state is one of `wanted`.
+   *
+   * Reaching one of `failOn` first rejects naming the state and `stateReason`; running
+   * past `timeout` rejects with a timeout.
+   */
+  waitForState(microvmId: string, wanted: Array<string>, options?: WaitForStateOptions | undefined | null): Promise<Microvm>
+  /** The region this plane addresses. */
+  get region(): string
+}
+
 /** Per-phase attribution for one sandbox, measured or projected. */
 export declare class CostReport {
   get label(): string
@@ -350,6 +402,19 @@ export declare class ExecProcess {
  */
 export declare class ExecStream {}
 
+/**
+ * A running keepalive. Call `stop()` when the work is done; `done()` resolves when it
+ * ends on its own. A garbage-collected handle stops the keepalive.
+ */
+export declare class KeepAwake {
+  /** Whether the keepalive is still polling. */
+  get running(): boolean
+  /** Stops polling and resolves with the report; rejects with the error that ended it. */
+  stop(): Promise<KeepAwakeReport>
+  /** Resolves when the keepalive ends (`whileBusy`, `maxDurationSec`, or `stop()`). */
+  done(): Promise<KeepAwakeReport>
+}
+
 /** One phase's one billing line: what was consumed, and what that costs. */
 export declare class LineItem {
   get phase(): string
@@ -383,6 +448,68 @@ export declare class LineItem {
   toString(): string
 }
 
+/** One named VM: everything `Sandbox.adopt` needs, under a name. */
+export declare class NameRecord {
+  /**
+   * A record for a VM this process can already address. Refuses an illegal name or an
+   * empty id, endpoint, or token.
+   */
+  constructor(name: string, microvmId: string, endpoint: string, agentToken: string, region: Region)
+  /** A record naming the VM `sandbox` addresses — launched or adopted. */
+  static forSandbox(name: string, sandbox: Sandbox): Promise<NameRecord>
+  /** A record from `toObject()` output (or a CLI registry file's JSON), checked. */
+  static fromObject(object: NameRecordObject): NameRecord
+  /**
+   * The record as a plain object, **agent token included** — the form to store privately
+   * and read back with `fromObject`.
+   */
+  toObject(): NameRecordObject
+  get name(): string
+  get microvmId(): string
+  get endpoint(): string
+  /**
+   * The VM's bearer credential. A method rather than a getter, so it is never read by
+   * accident; store it only privately.
+   */
+  agentToken(): string
+  get region(): string
+  /** Seconds since the epoch when the name was registered. */
+  get at(): number
+  get egressPosture(): string | null
+  /** The record without its secrets. */
+  toString(): string
+}
+
+/**
+ * The CLI's name registry: one owner-only JSON file per name under `<stateDir>/names/`.
+ *
+ * `stateDir` defaults to the CLI's — `$MICROVM_STATE_DIR`, else `~/.microvm/runs` — so a
+ * name registered here resolves in `microvm exec --name` and the reverse.
+ */
+export declare class NameRegistry {
+  constructor(stateDir?: string | undefined | null)
+  /** The directory holding the name files. */
+  get directory(): string
+  /**
+   * The record registered as `name`, or `null`. A file that exists but does not parse
+   * throws rather than reading as free.
+   */
+  get(name: string): NameRecord | null
+  /** Writes `record` under its name, replacing any earlier record, owner-only on Unix. */
+  put(record: NameRecord): void
+  /** Names the VM `sandbox` addresses and writes the record; resolves with it. */
+  register(name: string, sandbox: Sandbox): Promise<NameRecord>
+  /** Removes `name`, answering whether a record was there. */
+  delete(name: string): boolean
+  /** Every readable record, sorted by name. */
+  list(): Array<NameRecord>
+  /**
+   * Removes every name registered to `microvmId` and returns them — the step after a
+   * terminate, so no name outlives its VM.
+   */
+  releaseByVm(microvmId: string): Array<string>
+}
+
 /** The pinned rate table, and everything it says about itself. */
 export declare class RateTable {
   /**
@@ -554,6 +681,23 @@ export declare class Sandbox {
   wasTerminated(): Promise<boolean>
   /** How many times the token has been installed. Never above one (STATE-3). */
   bootstrapCount(): Promise<number>
+  /**
+   * A sandbox for a VM another process launched, from its private record.
+   *
+   * The lifecycle is read from `GetMicrovm`, so suspend, resume, and terminate start from
+   * the service's state and keep every guard. The VM was bootstrapped by its own launch,
+   * so `run` is refused and no run-hook payload is ever sent. Never publish or log
+   * `agentToken`; it appears in no error.
+   */
+  static adopt(region: Region, microvmId: string, endpoint: string, agentToken: string, port?: number | undefined | null): Promise<Sandbox>
+  /**
+   * Adopts the VM registered as `name` in `registry`; see `Sandbox.adopt`.
+   *
+   * `region` must match the record's: an id from another region addresses nothing here.
+   */
+  static fromName(region: Region, name: string, registry: NameRegistry, port?: number | undefined | null): Promise<Sandbox>
+  /** Whether this sandbox was built by `adopt` rather than by its own launch. */
+  adopted(): Promise<boolean>
   /** The VM id, once launched. */
   microvmId(): Promise<string | null>
   /** The proxy endpoint, once launched. */
@@ -570,9 +714,8 @@ export declare class Sandbox {
   /**
    * The suspended window this sandbox asked for at launch, in seconds.
    *
-   * `null` before a launch, and for a sandbox that did not send the launch — this client is
-   * the only party that can name the number, because `suspendedDurationSeconds` exists only
-   * in the `RunMicrovm` request.
+   * `null` before this sandbox launches a VM. This accessor reports the requested
+   * window; `GetMicrovm` also returns the service's idle policy.
    */
   suspendedWindowSecondsAsync(): Promise<number | null>
   /**
@@ -609,6 +752,14 @@ export declare class Sandbox {
    * `Sandbox`. A run with no image at all, before any call. Neither check is in this file.
    */
   run(options?: RunOptions | undefined | null): Promise<Session>
+  /**
+   * Finishes a `run({ wait: false })`: waits for RUNNING and resolves with the session.
+   *
+   * A launch whose `clientToken` adopted an existing, idle-suspended VM resumes it; a
+   * fresh launch that reaches a terminal state first rejects with the service's
+   * `stateReason`. Refused unless the launch is still PENDING.
+   */
+  waitUntilRunning(timeout?: number | undefined | null): Promise<Session>
   /**
    * Freezes the VM and waits for the platform to report it.
    *
@@ -660,12 +811,30 @@ export declare class Session {
    * in would be handing in one that expires.
    */
   static direct(endpoint: string, agentToken: string): Session
+  /**
+   * Reattach using a private control record, without bootstrapping again.
+   * Owns its transport independently of sandbox locks; use a separate attach with
+   * a short requestTimeout for keepalives. Never publish or log agentToken.
+   */
+  static attach(region: Region, microvmId: string, endpoint: string, agentToken: string, port?: number | undefined | null, requestTimeout?: number | undefined | null): Promise<Session>
+  /** The guest bearer credential. Store only in a private encrypted control record. */
+  agentToken(): Promise<string>
   /** The endpoint this session addresses. */
   endpoint(): Promise<string>
   /** The port the proxy token is scoped to. */
   port(): Promise<number>
   /** Unauthenticated liveness. */
   health(): Promise<Health>
+  /**
+   * Keeps the VM awake by polling health from this process until stopped.
+   *
+   * The platform counts only inbound requests as activity, so an exec working with no
+   * client traffic is suspended once `maxIdleDurationSeconds` passes. Resolves at once
+   * with a running handle. On a sandbox-held session a suspend or terminate through the
+   * sandbox ends the keepalive before its next poll; stop it before suspending through
+   * anything else, or the next poll auto-resumes the VM.
+   */
+  keepAwake(options?: KeepAwakeOptions | undefined | null): Promise<KeepAwake>
   /**
    * Polls health until the daemon reports bootstrapped.
    *
@@ -708,6 +877,14 @@ export declare class Session {
   runSync(command: string | Array<string>, options?: ExecOptions | undefined | null): Promise<ExecResult>
   /** Signals an exec's whole process group. Returns whether anything was signalled. */
   kill(execId: string): Promise<boolean>
+  /**
+   * Process accounting: every registered exec with its group's live pids.
+   *
+   * The daemon reads `/proc` itself, so this needs no `ps` in the guest. A `ProcGroup` with
+   * `childExited` and a non-empty `pids` is a command that finished while something it
+   * backgrounded did not; pass its `execId` to `kill`.
+   */
+  procs(): Promise<Array<ProcGroup>>
   /**
    * Writes one file, creating parents. `mode` is an **octal string** (`"0755"`), which is
    * the daemon's shape — a number here would be ambiguous between 0o755 and 755.
@@ -862,10 +1039,27 @@ export interface AgentLaunchOptions {
   imageIdentifier: string
   /** The execution role. Optional in the model; every real launch needs one. */
   executionRoleArn?: string
+  /** Persist this secret privately before launch when recovery is needed. */
+  agentToken?: string
+  /** Persist once per intended launch and reuse with the identical request. */
+  clientToken?: string
   maxIdleSec?: number
   suspendedSec?: number
   autoResume?: boolean
   maxDurationSec?: number
+  /** Pins the launch to one image version rather than the latest active one. */
+  imageVersion?: string
+  /**
+   * Customer-managed VPC egress connector ARNs. When given they replace the managed
+   * internet connector, and the VPC must route to Bedrock.
+   */
+  egressNetworkConnectors?: Array<string>
+  /** Per-VM CloudWatch log group. Omitted keeps the service's default destination. */
+  logGroup?: string
+  /** An exact log stream inside `logGroup`. */
+  logStream?: string
+  /** Turns per-VM logging off. Cannot be combined with `logGroup` or `logStream`. */
+  disableLogging?: boolean
 }
 
 /** A resolved spec: the model it will use and the command `prompt` runs. */
@@ -1033,6 +1227,12 @@ export interface ExecOptions {
   execId?: string
   /** The client-side deadline for `runSync` only. */
   timeout?: number
+  /**
+   * Signal the whole process group once the command's own child exits, so nothing it
+   * backgrounded outlives it. Off by default, which keeps the backgrounded-grandchild-output
+   * guarantee for callers who rely on it.
+   */
+  reapGroupOnExit?: boolean
 }
 
 /**
@@ -1057,6 +1257,8 @@ export interface ExecResult {
    * inside the bytes, which would be indistinguishable from output containing it.
    */
   truncated: boolean
+  /** True when the daemon execution deadline expired, distinct from cancellation. */
+  timedOut: boolean
   /**
    * Set when the post-exit linger deadline expired with the pipes still open: some
    * grandchild is alive and may write more that nobody will see.
@@ -1094,6 +1296,22 @@ export declare const enum GapPolicy {
   Event = 'event',
 }
 
+/** What a workload's hook handler did. Its output is in the daemon's log, not here. */
+export interface HandlerOutcome {
+  /** The exit code, or `null` when the handler was killed or never started. */
+  exitCode?: number
+  /** The signal that ended it, if one did. */
+  signal?: number
+  /** Whether the daemon killed it at its time budget. */
+  timedOut: boolean
+  /** Milliseconds from spawn to exit or kill. */
+  durationMs: number
+  /** Why it could not run at all, such as `not executable`. */
+  error?: string
+  /** Whether it ran and exited 0 within its budget. */
+  succeeded: boolean
+}
+
 /** The daemon's liveness answer. `bootstrapped` is the useful field. */
 export interface Health {
   /** The daemon's own version, distinct from the protocol version. */
@@ -1140,6 +1358,50 @@ export interface Health {
    * VM holding unacked output somebody still has to collect.
    */
   execs: number
+  /**
+   * Every lifecycle-hook invocation the daemon observed, oldest first, each with its
+   * workload handler's outcome when the image carries one. The hook routes are
+   * reachable over loopback from inside the guest, so a workload can add entries; the
+   * earliest are the platform's.
+   */
+  hooks: Array<HookObservation>
+  /** How many hook invocations the daemon's log cap dropped. */
+  hooksDropped: number
+  /**
+   * Each identity-repair step and its outcome. Empty until the run hook repairs this
+   * VM's identity.
+   */
+  identitySteps: Array<IdentityStep>
+}
+
+/** One lifecycle-hook invocation, as the daemon observed it. */
+export interface HookObservation {
+  /** `ready`, `validate`, `run`, `suspend`, `resume`, or `terminate`. */
+  hook: string
+  /** Seconds since the epoch on the daemon's clock when the hook arrived. */
+  firedAt: number
+  /** The workload handler's outcome, or `null` when the image has no handler for it. */
+  handler?: HandlerOutcome
+}
+
+/** One identity-repair step. */
+export interface IdentityStep {
+  /** `machine-id`, `hostname`, `boot-id`, `random-seed`, or `cached-credential`. */
+  name: string
+  /** `repaired`, `not_applicable`, or `failed`. */
+  outcome: string
+  /** The OS error for a failed step. */
+  error?: string
+}
+
+/** The idle policy the service reports a VM is running under. */
+export interface IdlePolicy {
+  /** `maxIdleDurationSeconds`: inbound-traffic silence before an auto-suspend. */
+  maxIdleSec: number
+  /** `suspendedDurationSeconds`: how long a suspended VM lasts before it is terminated. */
+  suspendedSec: number
+  /** `autoResumeEnabled`: whether a request to a suspended VM resumes it. */
+  autoResume: boolean
 }
 
 /** A built image, and the log group the service created alongside it. */
@@ -1193,6 +1455,67 @@ export declare function installAgentAccess(session: Session, agents: Array<Agent
  */
 export declare function installedAgents(session: Session): Promise<Array<AgentSpec>>
 
+/** The options bag for `keepAwake`. */
+export interface KeepAwakeOptions {
+  /** Seconds between polls. Default: a third of the idle window, at most 20. */
+  intervalSec?: number
+  /** End once no exec is running. */
+  whileBusy?: boolean
+  /** End after this many seconds even if still busy. */
+  maxDurationSec?: number
+  /**
+   * The VM's `maxIdleDurationSeconds`. A sandbox-held session knows it; otherwise the
+   * platform minimum of 60 is assumed. The interval may be at most half of it.
+   */
+  idleWindowSec?: number
+}
+
+/** What a finished keepalive did. */
+export interface KeepAwakeReport {
+  /** Why it ended: `"stopped"`, `"idle"`, `"elapsed"`, or `"not-running"`. */
+  end: string
+  /** Health polls that answered. */
+  polls: number
+  /** `busy` from the last answered poll, or `null` when none answered. */
+  lastBusy?: boolean
+  /** Seconds from start to end. */
+  elapsedSec: number
+}
+
+/** The service's optional `ListMicrovms` filters. */
+export interface ListMicrovmsOptions {
+  imageIdentifier?: string
+  imageVersion?: string
+}
+
+/** A MicroVM as `GetMicrovm` last described it. */
+export interface Microvm {
+  id: string
+  /** As the service spells it. Eventually consistent. */
+  state: string
+  /** Why the VM is in this state, when the service said. */
+  stateReason?: string
+  /** The proxy endpoint. Pair it with the agent token in `Session.attach`. */
+  endpoint: string
+  imageArn: string
+  imageVersion: string
+  idlePolicy?: IdlePolicy
+  /** `maximumDurationInSeconds`. Suspended time counts toward it. */
+  maximumDurationSeconds?: number
+  /** When the VM first started, as Unix seconds. */
+  startedAt?: number
+  /** When the VM terminated, as Unix seconds, once it has. */
+  terminatedAt?: number
+}
+
+/** One `ListMicrovms` item: narrower than `Microvm`, with no endpoint or reason. */
+export interface MicrovmSummary {
+  id: string
+  state: string
+  imageArn: string
+  imageVersion: string
+}
+
 /**
  * Mints a Bedrock bearer token from the default credential chain.
  *
@@ -1202,6 +1525,29 @@ export declare function installedAgents(session: Session): Promise<Array<AgentSp
  */
 export declare function mintBedrockToken(region: Region, ttlSeconds?: number | undefined | null): Promise<BearerToken>
 
+/**
+ * Mint using explicit STS credentials without changing the process environment.
+ * credentialsExpiresAt is Unix seconds from STS Expiration. Do not log these inputs.
+ */
+export declare function mintBedrockTokenWithCredentials(region: Region, accessKeyId: string, secretAccessKey: string, sessionToken: string | undefined | null, credentialsExpiresAt: number, ttlSeconds?: number | undefined | null): BearerToken
+
+/**
+ * A record's JSON-safe form, with the CLI registry's camelCase keys. **Holds the agent
+ * token**; store it privately.
+ */
+export interface NameRecordObject {
+  name: string
+  microvmId: string
+  endpoint: string
+  agentToken: string
+  region: string
+  /** Seconds since the epoch when the name was registered. */
+  at: number
+  identityHostSeed?: string
+  identityVmPublicKey?: string
+  egressPosture?: string
+}
+
 /**
  * One byte range the daemon could not replay.
  *
@@ -1264,6 +1610,36 @@ export interface ProcessExit {
    * because it is the only thing that makes a `null` exit code actionable.
    */
   signal?: number
+  /** True when the remote execution deadline expired. */
+  timedOut: boolean
+}
+
+/**
+ * One exec's process group, as `GET /v1/procs` reports it.
+ *
+ * `childExited` beside a non-empty `pids` is the shape worth reading: a command that finished
+ * while something it backgrounded did not, which `Health.busy` cannot show. The `execId`
+ * beside it is what `Session.kill` takes.
+ */
+export interface ProcGroup {
+  /** The exec this group belongs to — what `kill` takes. */
+  execId: string
+  /**
+   * The process group id captured at spawn, or `null` when the child was reaped before it
+   * could be read (then `pids` is empty: there is no group to scan for).
+   */
+  pgid?: number
+  /** Seconds since the epoch on the daemon's clock when the child was spawned. */
+  startedAt: number
+  /** Whether the exec's own child has exited. An acked exec still reads `true`. */
+  childExited: boolean
+  /** Whether the exec was started with `reapGroupOnExit`. */
+  reap: boolean
+  /**
+   * Live pids whose process group is `pgid`, read from `/proc` inside the guest. Zombies
+   * are not listed. Empty once the group is gone.
+   */
+  pids: Array<number>
 }
 
 /** Starts one task for `agent` over `session` and resolves with its handle. Does not wait. */
@@ -1275,6 +1651,10 @@ export interface PromptOptions {
   timeoutSec?: number
   /** A stable exec id, for a retry that must not spawn twice. */
   execId?: string
+  /** Agent process permissions: agent-default (default) or unrestricted. */
+  permissionMode?: 'agent-default' | 'unrestricted'
+  /** Stop residual children when the main agent exits. Defaults to false. */
+  reapGroupOnExit?: boolean
 }
 
 /** Everything a launch needs. */
@@ -1301,6 +1681,8 @@ export interface RunOptions {
    * shared image snapshot.
    */
   agentToken?: string
+  /** Persist once per intended launch and reuse with the identical request. */
+  clientToken?: string
   /**
    * Base environment for every exec in the launched VM, delivered in the same
    * `runHookPayload` as the token.
@@ -1310,18 +1692,25 @@ export interface RunOptions {
    * payload before the launch, naming the byte count.
    */
   launchEnv?: Record<string, string>
-  /** Whether to request the egress connector. Off means no outbound network. */
+  /** Request the managed INTERNET_EGRESS connector. Omission does not block egress. */
   egress?: boolean
+  /**
+   * Existing VPC network connector ARNs. For no egress, use a VPC without an
+   * internet gateway or NAT gateway. Cannot be combined with `egress: true`.
+   */
+  egressNetworkConnectors?: Array<string>
+  /**
+   * Set advisory HTTP proxy variables. Workloads can ignore or override them;
+   * use a VPC without an internet gateway or NAT gateway for no egress.
+   */
+  denyEgress?: boolean
   /**
    * Whether to launch shell-capable: the ingress set becomes the measured pair
    * `[HTTP_INGRESS, SHELL_INGRESS]`, which is what `microvm shell` attaches to.
    */
   shell?: boolean
   maxIdleSec?: number
-  /**
-   * The window a resume is refused past (STATE-12). Exists **only** in the launch request:
-   * `GetMicrovm` does not return it, so this client is the only party that can name it.
-   */
+  /** Requested suspended window, in seconds; the service also reports its idle policy. */
   suspendedSec?: number
   autoResume?: boolean
   maxDurationSec?: number
@@ -1329,6 +1718,17 @@ export interface RunOptions {
   readyTimeout?: number
   /** A label for the run token. Never the token. */
   tokenScope?: string
+  /**
+   * Whether `run` waits for RUNNING (default `true`). `false` resolves once the launch
+   * is accepted, with the lifecycle PENDING; `waitUntilRunning` finishes it.
+   */
+  wait?: boolean
+  /** Per-VM CloudWatch log group. Omitted keeps the service's default destination. */
+  logGroup?: string
+  /** An exact log stream inside `logGroup`. */
+  logStream?: string
+  /** Turns per-VM logging off. Cannot be combined with `logGroup` or `logStream`. */
+  disableLogging?: boolean
 }
 
 /**
@@ -1466,6 +1866,8 @@ export interface StreamEvent {
   exitCode?: number
   signal?: number
   truncated?: boolean
+  /** Present on exit: whether the remote execution deadline expired. */
+  timedOut?: boolean
   writersMayBeAlive?: boolean
 }
 
@@ -1550,5 +1952,15 @@ export interface TeardownReport {
   leaked: boolean
 }
 
+/** How `waitForState` polls. */
+export interface WaitForStateOptions {
+  /** States that reject with `stateReason` instead of being waited through. */
+  failOn?: Array<string>
+  /** Seconds before giving up. Default 300. */
+  timeout?: number
+  /** Seconds between polls. Default 5. */
+  pollInterval?: number
+}
+
 /** Every daemon-status class, as `err.cause.cause.message` names them. */
 export declare function wireKinds(): Array<string>

package/index.js

@@ -4,6 +4,10 @@
 
 const { readFileSync } = require('fs')
 let nativeBinding = null
+// Which artifact actually loaded. The WASI fallback chain overwrites it with
+// the flavor it resolved; the late native retry below leaves it alone because
+// it only runs while no WASI candidate has been loaded.
+let __napiLoadedBindingTarget = 'native'
 const loadErrors = []
 
 const isMusl = () => {
@@ -62,7 +66,16 @@ const isMuslFromChildProcess = () => {
 function requireNative() {
   if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
     try {
-      return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH)
+      const overrideBinding = require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH)
+      // The override may be a generated WASI loader, which already reports its
+      // own flavor. Adopt it: `module.exports` aliases this object, so claiming
+      // 'native' would both misreport the artifact and overwrite the loader's
+      // marker through the alias.
+      __napiLoadedBindingTarget =
+        overrideBinding && typeof overrideBinding.__napiBindingTarget === 'string'
+          ? overrideBinding.__napiBindingTarget
+          : 'native'
+      return overrideBinding
     } catch (err) {
       loadErrors.push(err)
     }
@@ -76,8 +89,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-android-arm64')
         const bindingPackageVersion = require('@theagenticguy/microvms-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -92,8 +105,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-android-arm-eabi')
         const bindingPackageVersion = require('@theagenticguy/microvms-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -113,8 +126,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-win32-x64-gnu')
           const bindingPackageVersion = require('@theagenticguy/microvms-win32-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -129,8 +142,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-win32-x64-msvc')
           const bindingPackageVersion = require('@theagenticguy/microvms-win32-x64-msvc/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -146,8 +159,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-win32-ia32-msvc')
         const bindingPackageVersion = require('@theagenticguy/microvms-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -162,8 +175,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-win32-arm64-msvc')
         const bindingPackageVersion = require('@theagenticguy/microvms-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -181,8 +194,8 @@ function requireNative() {
     try {
       const binding = require('@theagenticguy/microvms-darwin-universal')
       const bindingPackageVersion = require('@theagenticguy/microvms-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -197,8 +210,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-darwin-x64')
         const bindingPackageVersion = require('@theagenticguy/microvms-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -213,8 +226,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-darwin-arm64')
         const bindingPackageVersion = require('@theagenticguy/microvms-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -233,8 +246,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-freebsd-x64')
         const bindingPackageVersion = require('@theagenticguy/microvms-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -249,8 +262,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-freebsd-arm64')
         const bindingPackageVersion = require('@theagenticguy/microvms-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -270,8 +283,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-x64-musl')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -286,8 +299,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-x64-gnu')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -304,8 +317,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-arm64-musl')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -320,8 +333,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-arm64-gnu')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -338,8 +351,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-arm-musleabihf')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -354,8 +367,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -372,8 +385,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-loong64-musl')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -388,8 +401,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-loong64-gnu')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -406,8 +419,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-riscv64-musl')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -422,8 +435,8 @@ function requireNative() {
         try {
           const binding = require('@theagenticguy/microvms-linux-riscv64-gnu')
           const bindingPackageVersion = require('@theagenticguy/microvms-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -439,8 +452,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-linux-ppc64-gnu')
         const bindingPackageVersion = require('@theagenticguy/microvms-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -455,8 +468,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-linux-s390x-gnu')
         const bindingPackageVersion = require('@theagenticguy/microvms-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -475,8 +488,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-openharmony-arm64')
         const bindingPackageVersion = require('@theagenticguy/microvms-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -491,8 +504,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-openharmony-x64')
         const bindingPackageVersion = require('@theagenticguy/microvms-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -507,8 +520,8 @@ function requireNative() {
       try {
         const binding = require('@theagenticguy/microvms-openharmony-arm')
         const bindingPackageVersion = require('@theagenticguy/microvms-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.7.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -627,6 +640,7 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         wasiBinding = require('./microvms.wasi.cjs')
         nativeBinding = wasiBinding
+        __napiLoadedBindingTarget = 'wasm32-wasi'
         wasiBindingLoaded = true
       }
     } catch (err) {
@@ -647,12 +661,13 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('@theagenticguy/microvms-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '0.7.0') {
-            throw new Error(`WASI binding package version mismatch, expected 0.7.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0') {
+            throw new Error(`WASI binding package version mismatch, expected 0.9.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('@theagenticguy/microvms-wasm32-wasi')
         nativeBinding = wasiBinding
+        __napiLoadedBindingTarget = 'wasm32-wasi'
         wasiBindingLoaded = true
       }
     } catch (err) {
@@ -698,18 +713,86 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
+function __napiStampBindingTarget(exportsObject, target) {
+  if (
+    Object.prototype.hasOwnProperty.call(exportsObject, '__napiBindingTarget')
+  ) {
+    if (exportsObject.__napiBindingTarget === target) {
+      // Already ours: the root entry aliases the object it loaded, so a WASI
+      // fallback candidate — or a `NAPI_RS_NATIVE_LIBRARY_PATH` override that
+      // is a generated loader — arrives already stamped with this same value.
+      return target
+    }
+    const error = new Error(
+      '`__napiBindingTarget` is reserved by the generated binding loader, but the loaded binding already exports it. Rename the export, e.g. #[napi(js_name = "...")].',
+    )
+    error.code = 'ERR_NAPI_BINDING_TARGET_CONFLICT'
+    throw error
+  }
+  if (!Object.isExtensible(exportsObject)) {
+    // A `#[napi(module_exports)]` hook may seal or freeze this object
+    // (`Object::seal` / `Object::freeze`). Reporting the artifact is metadata,
+    // never a reason to fail an otherwise successful load, so the stamp is
+    // skipped. What a consumer still sees then follows the entry point: the
+    // browser and deferred loaders declare `__napiBindingTarget` at module
+    // level and go on reporting it, while the CommonJS entries hand back this
+    // very object as `module.exports`, so there the value is absent.
+    return target
+  }
+  try {
+    // [[Define]], not [[Set]]: an ordinary assignment walks the prototype
+    // chain, so an inherited accessor could swallow the value or throw and
+    // fail an otherwise successful load. The descriptor is what a successful
+    // assignment would have produced.
+    Object.defineProperty(exportsObject, '__napiBindingTarget', {
+      configurable: true,
+      enumerable: true,
+      value: target,
+      writable: true,
+    })
+  } catch {
+    // Same rule as the non-extensible skip above: reporting the artifact is
+    // metadata, never a reason to fail an otherwise successful load. An exotic
+    // object (a Proxy whose defineProperty trap refuses) is skipped, not
+    // thrown over.
+  }
+  // The CommonJS loaders assign this return value so `cjs-module-lexer` — and
+  // therefore Node's CJS -> ESM named export detection — can see
+  // `__napiBindingTarget` statically.
+  return target
+}
+// Stamp before the alias, not after. The guard only reads `nativeBinding`
+// (`hasOwnProperty` plus a comparison), which is safe against any addon
+// accessor; an assignment is not, because a `#[napi(module_exports)]` hook can
+// expose a getter reporting this very value and a setter that throws. So the
+// assignment lands on the loader's own `module.exports`, still the original
+// object here, and the alias below replaces it.
+//
+// The assignment is what keeps the marker a statically visible CommonJS export:
+// `cjs-module-lexer` is Node's CJS -> ESM named export detection, it cannot see
+// a bare call, and the later `module.exports = nativeBinding` does not undo the
+// detection. The assignment itself always succeeds — its target is this
+// loader's own, still extensible `module.exports` — and the alias below then
+// discards the value it wrote. What a consumer reads is whatever the guard put
+// on `nativeBinding`, so on a frozen binding, where the guard skips, the
+// linked import resolves to `undefined`.
+module.exports.__napiBindingTarget = __napiStampBindingTarget(nativeBinding, __napiLoadedBindingTarget)
 module.exports = nativeBinding
 module.exports.AgentVm = nativeBinding.AgentVm
 module.exports.Amount = nativeBinding.Amount
 module.exports.BearerToken = nativeBinding.BearerToken
 module.exports.BuildHookTimeout = nativeBinding.BuildHookTimeout
+module.exports.ControlPlane = nativeBinding.ControlPlane
 module.exports.CostReport = nativeBinding.CostReport
 module.exports.Duration = nativeBinding.Duration
 module.exports.EstimatedUsd = nativeBinding.EstimatedUsd
 module.exports.ExecHandle = nativeBinding.ExecHandle
 module.exports.ExecProcess = nativeBinding.ExecProcess
 module.exports.ExecStream = nativeBinding.ExecStream
+module.exports.KeepAwake = nativeBinding.KeepAwake
 module.exports.LineItem = nativeBinding.LineItem
+module.exports.NameRecord = nativeBinding.NameRecord
+module.exports.NameRegistry = nativeBinding.NameRegistry
 module.exports.RateTable = nativeBinding.RateTable
 module.exports.Region = nativeBinding.Region
 module.exports.ResidencyComparison = nativeBinding.ResidencyComparison
@@ -731,6 +814,7 @@ module.exports.GapPolicy = nativeBinding.GapPolicy
 module.exports.installAgentAccess = nativeBinding.installAgentAccess
 module.exports.installedAgents = nativeBinding.installedAgents
 module.exports.mintBedrockToken = nativeBinding.mintBedrockToken
+module.exports.mintBedrockTokenWithCredentials = nativeBinding.mintBedrockTokenWithCredentials
 module.exports.promptAgent = nativeBinding.promptAgent
 module.exports.runReport = nativeBinding.runReport
 module.exports.sessionConstants = nativeBinding.sessionConstants

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theagenticguy/microvms",
-  "version": "0.7.0",
-  "description": "Node bindings over microvms-core: the MicroVMs client with every trap closure",
+  "version": "0.9.0",
+  "description": "Node.js and TypeScript client for AWS Lambda MicroVMs",
   "license": "Apache-2.0",
   "author": "Laith Al-Saadoon",
   "homepage": "https://laithalsaadoon.github.io/microvms-agentd/",
@@ -45,7 +45,7 @@
     "build": "napi build --manifest-path ../Cargo.toml --package microvms-js --platform --output-dir .",
     "test": "node --test __test__/*.mjs",
     "test:smoke": "node --test __test__/smoke.mjs",
-    "test:unit": "node --test __test__/cost.mjs __test__/errors.mjs __test__/exec.mjs __test__/process.mjs __test__/session.mjs"
+    "test:unit": "node --test __test__/cost.mjs __test__/errors.mjs __test__/exec.mjs __test__/process.mjs __test__/session.mjs __test__/numbers.mjs"
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.8.2"