@theagenticguy/microvms 0.10.0 → 0.11.0

package/index.d.ts

@@ -1,4 +1,5 @@
-/* auto-generated by NAPI-RS */
+// SPDX-License-Identifier: Apache-2.0
+/* auto-generated by NAPI-RS from bindings/microvms-js/src/. Regenerate with `mise run dts`; `mise run dts:check` fails when this file drifts. */
 /* eslint-disable */
 
 /**
@@ -9,6 +10,15 @@
  */
 export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
 
+declare global {
+  interface __NapiRsAsyncGenerator<TOwner, T, TReturn, TNext> {
+    next(...[value]: [] | [TNext]): globalThis.Promise<globalThis.IteratorResult<T, TReturn | undefined>>
+    return(...[value]: [] | [TReturn]): globalThis.Promise<globalThis.IteratorResult<T, TReturn | undefined>>
+    throw(exception?: unknown): globalThis.Promise<globalThis.IteratorResult<T, TReturn | undefined>>
+    [globalThis.Symbol.asyncIterator](): this
+  }
+}
+
 /**
  * One VM with coding agents in it: the sandbox plus the specs it is built for.
  *
@@ -51,12 +61,18 @@ export declare class AgentVm {
   dockerfile(): Promise<string>
   /**
    * The image name for these specs and this daemon binary: `agent-vm-<agents>-<hash12>`.
-   * Content-addressed, so an unchanged binary and spec set name the image a previous run
-   * built; `findImage` looks it up.
+   * Content-addressed, so an unchanged binary, spec set and size name the image a previous
+   * run built; `findImage` looks it up, and `ensureImage` builds or reuses it.
    */
   imageName(options: AgentImageOptions, size?: SizeClass | undefined | null): Promise<string>
   /** The ARN of an existing image named per `imageName`, or `null` when there is none. */
   findImage(options: AgentImageOptions, size?: SizeClass | undefined | null): Promise<string | null>
+  /**
+   * Builds or reuses this VM's image, named per `imageName`: resolved at once when ready,
+   * waited on while building, deleted and rebuilt when failed, and uploaded to
+   * `s3://<s3Bucket>/<s3KeyPrefix>/<name>/artifact.zip` only when a build is needed.
+   */
+  ensureImage(options: AgentEnsureOptions, size?: SizeClass | undefined | null): Promise<EnsuredImage>
   /** The artifact bytes to upload to `s3://<bucket>/<imageName>.zip` before `buildImage`. */
   buildArtifact(options: AgentImageOptions, size?: SizeClass | undefined | null): Promise<Buffer>
   /**
@@ -136,18 +152,54 @@ export declare class BearerToken {
   toString(): string
 }
 
+/**
+ * A report's total judged against a budget: core's `Budget::check`, the verdict
+ * `microvm cost --max-cost` renders.
+ */
+export declare class BudgetVerdict {
+  /** The ceiling, as the caller wrote it. */
+  get maxUsd(): EstimatedUsd
+  /** `"warn"` or `"abort"`: what the caller said a breach does. */
+  get onBreach(): string
+  /** The total's floor: the whole estimate unless `isLowerBound`. */
+  get floor(): EstimatedUsd
+  /** Whether the floor is a lower bound, because a line is unpriced. */
+  get isLowerBound(): boolean
+  /** `"exact"` or `"lower-bound"`. */
+  get basis(): string
+  /** The phases whose lines are unpriced, sorted. */
+  get unpricedPhases(): Array<string>
+  /** Whether the floor is over the ceiling. At the ceiling is within it. */
+  get breached(): boolean
+  /** Whether the caller's judgement refuses the report: breached, under `"abort"`. */
+  get aborts(): boolean
+  /**
+   * How far over the ceiling the floor is, when breached; at least that much for a lower
+   * bound.
+   */
+  get overage(): EstimatedUsd | null
+  /** One line for a human, the one `microvm cost --max-cost` prints. */
+  render(): string
+  /**
+   * Core's JSON shape for the verdict, as a JSON **string**: `maxUsd`, `onBreach`, `basis`,
+   * `breached`, `overageAtLeastUsd`.
+   */
+  toJson(): string
+}
+
 /** A timeout for the `ready` or `validate` image-build hook: 1..=3600 seconds. */
 export declare class BuildHookTimeout {
   /** A build-family timeout, or a refusal naming both ceilings. */
   constructor(seconds: number)
   /** The service ceiling for this family: 3600. */
-  get maxSecs(): number
+  get maxSecs(): 3600
   get seconds(): number
   toString(): string
 }
 
 /**
- * MicroVM lifecycle by ID: get, list, suspend, resume, terminate, and wait.
+ * MicroVM lifecycle by ID (get, list, suspend, resume, terminate, and wait) and image
+ * administration (list, delete, versions and their status, builds).
  *
  * 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.
@@ -175,6 +227,37 @@ export declare class ControlPlane {
    * past `timeout` rejects with a timeout.
    */
   waitForState(microvmId: string, wanted: Array<string>, options?: WaitForStateOptions | undefined | null): Promise<Microvm>
+  /** `ListMicrovmImages`, every page: every image in the account and region. */
+  listImages(): Promise<Array<ImageSummary>>
+  /**
+   * Deletes the image, its extra versions first, retrying while it refuses (an image still
+   * `CREATING`, or one a terminating VM holds).
+   *
+   * Resolves `true` once the service took the deletion and `false` when every attempt
+   * failed or `identifier` is not one the service accepts. It doesn't reject, as a
+   * teardown's delete shouldn't.
+   */
+  deleteImage(identifier: string, options?: DeleteImageOptions | undefined | null): Promise<boolean>
+  /**
+   * `ListMicrovmImageVersions`, every page: each version, its status, and its build
+   * configuration.
+   */
+  listImageVersions(identifier: string): Promise<Array<ImageVersion>>
+  /**
+   * `UpdateMicrovmImageVersion`: `status` is `"ACTIVE"` or `"INACTIVE"`.
+   *
+   * `INACTIVE` is the non-destructive retire: `RunMicrovm` refuses the version, running VMs
+   * keep running, and the version's readback stays. Resolves with the readback, and rejects
+   * when it doesn't carry the status asked for, so a 200 that didn't take isn't a rollback.
+   */
+  setImageVersionStatus(identifier: string, version: string, status: string): Promise<ImageVersion>
+  /**
+   * `ListMicrovmImageBuilds` for one version, every page: one build per Graviton
+   * generation. Each `buildId` is what `getImageBuild` takes.
+   */
+  listImageBuilds(identifier: string, version: string): Promise<Array<ImageBuild>>
+  /** `GetMicrovmImageBuild`: one build, with the snapshot sizes the listing doesn't carry. */
+  getImageBuild(identifier: string, version: string, buildId: string): Promise<ImageBuild>
   /** The region this plane addresses. */
   get region(): string
 }
@@ -202,7 +285,7 @@ export declare class CostReport {
    *
    * The string is judged by the core's own [`CostPhase::from_str`], which is where the
    * closed set lives. This file used to carry its own seven-element table for it, as did
-   * `microvms-py/src/cost.rs` — two parallel lists over one enum, which would have gone
+   * `bindings/microvms-py/src/cost.rs` — two parallel lists over one enum, which would have gone
    * stale the first time a phase was added and would have disagreed with each other in
    * whichever direction was edited first.
    */
@@ -210,7 +293,8 @@ export declare class CostReport {
   /** Plain text, leading with what the dollars are rather than with the dollars. */
   render(): string
   /**
-   * The `cli.py:688 report_to_dict` shape as a JSON **string**.
+   * Core's JSON shape for a report, as a JSON **string**: the one `microvm cost --json`
+   * and Python's `to_dict` emit (#255).
    *
    * A string for the same reason [`LineItem::to_json`] is: the unpriced line item omits
    * its `usd` key, which no typed return shape can express.
@@ -418,6 +502,12 @@ export declare class ExecProcess {
 /**
  * A JS async iterator over an exec's output.
  *
+ * Loop over the stream itself: `for await (const event of handle.stream())`. The object
+ * `[Symbol.asyncIterator]()` returns has `next`, `return` and `throw` and no
+ * `[Symbol.asyncIterator]()` of its own, though its generated type, `__NapiRsAsyncGenerator`,
+ * declares one. So `for await` over that object type-checks, then throws a `TypeError`
+ * because it isn't async iterable (#262).
+ *
  * See the module docs for why this is a task and a bounded channel. The receiver is behind
  * a tokio `Mutex` because `AsyncGenerator::next` must answer a `Send + 'static` future, so
  * the guard is taken *inside* that future rather than borrowed from `&mut self`.
@@ -427,7 +517,10 @@ export declare class ExecProcess {
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
  */
-export declare class ExecStream {}
+export declare class ExecStream {
+
+  [globalThis.Symbol.asyncIterator](): globalThis.__NapiRsAsyncGenerator<ExecStream, StreamEvent, void, undefined>
+}
 
 /**
  * A running keepalive. Call `stop()` when the work is done; `done()` resolves when it
@@ -464,7 +557,7 @@ export declare class LineItem {
   get duration(): Duration | null
   get note(): string
   /**
-   * The `cli.py` `_line_to_dict` shape as a JSON **string**.
+   * Core's JSON shape for a line item, as a JSON **string**.
    *
    * A string rather than an object because the unpriced case must **omit** the `usd` key
    * entirely, and a `#[napi(object)]` return type cannot express an absent key — an
@@ -503,6 +596,14 @@ export declare class NameRecord {
   /** Seconds since the epoch when the name was registered. */
   get at(): number
   get egressPosture(): string | null
+  /**
+   * The VM's tunnel identity, when it was launched with `identity: true`; `null` otherwise.
+   *
+   * Throws when the record carries one half of the pair, or a half that doesn't decode: the
+   * record claims a verifiable VM, and reading it as unverifiable would hide that it's
+   * broken. A method, like `agentToken()`, because it holds the host's secret half.
+   */
+  tunnelIdentity(): TunnelIdentity | null
   /** The record without its secrets. */
   toString(): string
 }
@@ -535,6 +636,39 @@ export declare class NameRegistry {
    * terminate, so no name outlives its VM.
    */
   releaseByVm(microvmId: string): Array<string>
+  /**
+   * Registers a record this registry didn't write, once the VM has answered one
+   * authenticated request with the record's token; resolves with whether it refreshed a
+   * record of the same VM.
+   *
+   * `session` must be attached with the record's endpoint and token (`Session.attach` from
+   * its fields). A name held by another VM, or by an unreadable file, is refused before any
+   * request, and a probe the daemon refuses writes nothing. Core's `names::import`, the rule
+   * `microvm attach` applies.
+   */
+  importRecord(record: NameRecord, session: Session): Promise<boolean>
+}
+
+/**
+ * A running port-forward. Call `stop()` when done; a garbage-collected handle stops the
+ * forward and cuts its open connections.
+ */
+export declare class PortForward {
+  /** The local address to connect to, `host:port`, with the port the OS picked. */
+  get localAddress(): string
+  /** Whether the forward is still serving. */
+  get running(): boolean
+  /**
+   * Stops accepting, waits for the connections still open to end, and resolves with the
+   * report.
+   *
+   * With `timeout` (seconds), connections still open after it are cut and listed as
+   * `"failed"`. Without it, a client that keeps its connection open keeps this waiting.
+   * Callable again, with the same report.
+   */
+  stop(timeout?: number | undefined | null): Promise<PortForwardReport>
+  /** The handle without its credentials. */
+  toString(): string
 }
 
 /** The pinned rate table, and everything it says about itself. */
@@ -667,7 +801,7 @@ export declare class RunHookTimeout {
   /** A run-family timeout, or a refusal naming **both** ceilings. */
   constructor(seconds: number)
   /** The service ceiling for this family: 60. */
-  get maxSecs(): number
+  get maxSecs(): 60
   get seconds(): number
   toString(): string
 }
@@ -759,6 +893,14 @@ export declare class Sandbox {
    * window; `GetMicrovm` also returns the service's idle policy.
    */
   suspendedWindowSecondsAsync(): Promise<number | null>
+  /**
+   * The tunnel identity a launch with `identity: true` generated, or that an adopted record
+   * carried; `null` otherwise.
+   *
+   * Holds the host's secret half: pass it to `session.tunnel(...)`, and store it only
+   * where the agent token goes.
+   */
+  tunnelIdentity(): Promise<TunnelIdentity | null>
   /**
    * The session, once launched.
    *
@@ -797,7 +939,26 @@ export declare class Sandbox {
    */
   buildArtifact(options: BuildImageOptions, size?: SizeClass | undefined | null, runHookTimeout?: RunHookTimeout | undefined | null, buildHookTimeout?: BuildHookTimeout | undefined | null): Promise<Buffer>
   /**
-   * Launches a MicroVM, waits for RUNNING, and resolves with its session.
+   * Every local guard `buildImage` runs, with zero calls: rejects with the refusal
+   * `buildImage` would, so a caller who uploads its own artifact checks the request before
+   * paying for the upload. Takes `buildImage`'s arguments.
+   */
+  preflight(options: BuildImageOptions, size?: SizeClass | undefined | null, runHookTimeout?: RunHookTimeout | undefined | null, buildHookTimeout?: BuildHookTimeout | undefined | null): Promise<void>
+  /**
+   * `ListManagedMicrovmImageVersions`, every page: the versions of a managed base, the
+   * values `buildImage`'s base-version pin takes.
+   *
+   * `baseImageArn` is the base's full ARN, such as
+   * `arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1`; a bare name is refused.
+   */
+  managedBaseVersions(baseImageArn: string): Promise<Array<ManagedBaseVersion>>
+  /**
+   * Launches a MicroVM, waits for RUNNING and for its daemon to answer, and resolves with
+   * its session.
+   *
+   * `readyTimeout` bounds the wait for RUNNING; the wait for the daemon after it is
+   * `sessionConstants().defaultReadyTimeoutSeconds`, and a daemon that never answers
+   * rejects with `ERR_TIMEOUT` with the VM left RUNNING.
    *
    * # What the core refuses here, and this file does not
    *
@@ -807,7 +968,9 @@ export declare class Sandbox {
    */
   run(options?: RunOptions | undefined | null): Promise<Session>
   /**
-   * Finishes a `run({ wait: false })`: waits for RUNNING and resolves with the session.
+   * Finishes a `run({ wait: false })`: waits for RUNNING and for the daemon to answer, and
+   * resolves with the session. `timeout` bounds the wait for RUNNING, as `readyTimeout`
+   * does.
    *
    * 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
@@ -970,8 +1133,39 @@ export declare class Session {
    * the daemon's shape — a number here would be ambiguous between 0o755 and 755.
    */
   uploadFile(path: string, data: Uint8Array, mode?: string | undefined | null): Promise<void>
-  /** Reads one file. */
-  downloadFile(path: string): Promise<Buffer>
+  /**
+   * Reads one file, or lines `startLine` through `endLine` of it.
+   *
+   * The range is 1-based and inclusive, and the daemon slices the file, so reading lines 40
+   * to 60 of a large log reads those lines alone. Either bound may be left out (line 1,
+   * through EOF), and an `endLine` past the last line reads through EOF. Line 0 and an end
+   * before the start reject with `ERR_INVALID_ARG` before any request.
+   */
+  downloadFile(path: string, options?: DownloadFileOptions | undefined | null): Promise<Buffer>
+  /**
+   * Brings the files of a directory in the VM back under `localDir`: the regular files
+   * `globs` select, and nothing else.
+   *
+   * The daemon packs `remote`, and the archive describes the VM's filesystem, where
+   * untrusted work runs, so core writes only regular-file members that match a glob, never
+   * under `.git` whatever the globs say, and never outside `localDir`. A symlink, a special
+   * file or a `../` member is skipped, not refused. `['**']` brings every regular file back.
+   * Resolves to what was written; a local directory that can't be written to rejects with
+   * `ERR_INVALID_ARG`.
+   */
+  downloadDir(remote: string, localDir: string, globs: Array<string>): Promise<Array<DownloadedFile>>
+  /**
+   * Syncs `localDir` into the VM's `/workspace` once, uploading only what changed.
+   *
+   * Core's one pass, `microvm sync`'s: the local tree is hashed and diffed against the
+   * manifest the last sync left in the VM, the changed members travel as one archive, the
+   * paths gone locally are removed in the VM with one `rm` whose deadline is
+   * `deleteTimeout` seconds (core's default when omitted), and the manifest is rewritten.
+   * `full: true` ignores the manifest and uploads everything. `.git`, `target`,
+   * `node_modules` and `.venv` never travel. A tree over the daemon's budgets rejects with
+   * `ERR_INVALID_ARG` before anything is sent.
+   */
+  syncDir(localDir: string, options?: SyncDirOptions | undefined | null): Promise<SyncReport>
   /** Whether a path exists, distinguishing absence from every other refusal. */
   fileExists(path: string): Promise<boolean>
   /**
@@ -1023,6 +1217,28 @@ export declare class Session {
    * The middle string **contains the credential**. Same rule as `connectHeaders`.
    */
   connectSubprotocols(port: number): Promise<Array<string> | null>
+  /**
+   * Serves a local TCP port as a tunnel to `guestPort` in the VM, on a background task, and
+   * resolves at once with its handle: `microvm tunnel`'s loop.
+   *
+   * Each local connection gets a WebSocket of its own through the endpoint proxy, and a
+   * connection the daemon refuses is listed in the report while the tunnel keeps serving.
+   * With `verifyIdentity` (a `TunnelIdentity`, such as `sandbox.tunnelIdentity()`), each
+   * connection first proves the far end is the daemon of the VM that identity was launched
+   * with, and a connection that can't is refused. A separate parameter rather than an
+   * option, for the reason `buildImage`'s guarded values are: a class in an options object
+   * can't cross an async call.
+   */
+  tunnel(guestPort: number, options?: ServeOptions | undefined | null, verifyIdentity?: TunnelIdentity | undefined | null): Promise<Tunnel>
+  /**
+   * Serves a local port as an HTTP and WebSocket forward to `guestPort` in the VM, on a
+   * background task, and resolves at once with its handle: `microvm port-forward`'s loop.
+   *
+   * Connections are served at once rather than one after another, so a slow request
+   * doesn't hold the next. A request the endpoint proxy refuses is listed in the report
+   * with its status while the forward keeps serving.
+   */
+  portForward(guestPort: number, options?: ServeOptions | undefined | null): Promise<PortForward>
   /**
    * How many proxy tokens this session has minted, or `null` for a direct session.
    *
@@ -1096,6 +1312,50 @@ export declare class Total {
   toString(): string
 }
 
+/**
+ * A running tunnel. Call `stop()` when done; a garbage-collected handle stops the tunnel and
+ * cuts its open connections.
+ */
+export declare class Tunnel {
+  /** The local address to connect to, `host:port`, with the port the OS picked. */
+  get localAddress(): string
+  /** Whether the tunnel is still serving. */
+  get running(): boolean
+  /**
+   * Stops accepting, waits for the connections still open to end, and resolves with the
+   * report.
+   *
+   * With `timeout` (seconds), connections still open after it are cut and listed as
+   * `"failed"`. Without it, a client that keeps its connection open keeps this waiting.
+   * Callable again, with the same report.
+   */
+  stop(timeout?: number | undefined | null): Promise<TunnelReport>
+  /** The handle without its credentials. */
+  toString(): string
+}
+
+/**
+ * What a launcher keeps to verify its VM: the host's secret seed and the VM's public key,
+ * both base64.
+ *
+ * From `sandbox.tunnelIdentity()` after a `run({ identity: true })`, from a `NameRecord`, or
+ * built from the two values `microvm run --identity` prints. Holds a secret: `hostSeed()` is a
+ * method rather than a getter so it's never read by accident, and `toString()` leaves it out.
+ */
+export declare class TunnelIdentity {
+  /**
+   * Rebuilds the pair from its base64 spellings. Refuses a value that doesn't decode, or a
+   * seed or key of the wrong length.
+   */
+  constructor(hostSeed: string, vmPublicKey: string)
+  /** The host's secret half, base64. Store only privately. */
+  hostSeed(): string
+  /** The VM's public key, base64: the pin. Safe to print and compare. */
+  get vmPublicKey(): string
+  /** The pair without its secret. */
+  toString(): string
+}
+
 /**
  * A quantity we can measure but cannot price, because no rate is published.
  *
@@ -1110,6 +1370,21 @@ export declare class Unpriced {
 /** The layer's fixed values as JSON, for a caller that wants to reason about the guest. */
 export declare function agentConstants(): string
 
+/**
+ * What `ensureImage` builds or reuses from: the daemon binary, the build role, and where
+ * the artifact goes.
+ */
+export interface AgentEnsureOptions {
+  /** The daemon binary's bytes, zipped into the artifact. */
+  binary: Uint8Array
+  /** The build role, which must read the bucket and grant logs on `/aws/lambda-microvms/*`. */
+  buildRoleArn: string
+  /** The bucket the artifact is uploaded to, in the VM's region. */
+  s3Bucket: string
+  /** A key prefix inside the bucket, or absent for the bucket root. */
+  s3KeyPrefix?: string
+}
+
 /** What an agent image is derived from: the daemon binary and the build role. */
 export interface AgentImageOptions {
   /** The daemon binary's bytes, zipped into the artifact. */
@@ -1125,7 +1400,10 @@ export interface AgentImageOptions {
 
 /** Everything a launch takes beyond what the layer fixes (egress on, the image). */
 export interface AgentLaunchOptions {
-  /** The image ARN from `findImage` or `buildImage`. */
+  /**
+   * The image ARN from `findImage` or `buildImage`, or a bare image name, which the core
+   * resolves with one `ListMicrovmImages` read.
+   */
   imageIdentifier: string
   /** The execution role. Optional in the model; every real launch needs one. */
   executionRoleArn?: string
@@ -1150,6 +1428,15 @@ export interface AgentLaunchOptions {
   logStream?: string
   /** Turns per-VM logging off. Cannot be combined with `logGroup` or `logStream`. */
   disableLogging?: boolean
+  /** The base environment for every exec in the VM. See `RunOptions.launchEnv`. */
+  launchEnv?: Record<string, string>
+  /** Launch shell-capable. See `RunOptions.shell`. */
+  shell?: boolean
+  /**
+   * How long to wait for RUNNING. The wait for the daemon after it is the core's
+   * `defaultReadyTimeoutSeconds`.
+   */
+  readyTimeout?: number
 }
 
 /** A resolved spec: the model it will use and the command `prompt` runs. */
@@ -1236,8 +1523,16 @@ export interface BuildImageOptions {
   /** The build role, which must grant logs on `/aws/lambda-microvms/*`. */
   buildRoleArn: string
   baseImage?: BaseImageInput
+  /** Pins the managed base to one version, a value `managedBaseVersions` lists. */
+  baseImageVersion?: string
   /** A caller-supplied Dockerfile, checked against the base image's `FROM`. */
   dockerfile?: string
+  /**
+   * A directory whose one manifest+lockfile pair bakes an environment layer, by the rule
+   * the CLI's `--project` uses. A directory without exactly one pair is refused before any
+   * call.
+   */
+  projectDir?: string
   /** Whether to repair guest identity. A boolean, not a capability list — see above. */
   repairGuestIdentity?: boolean
   /**
@@ -1266,6 +1561,16 @@ export interface BuildImageOptions {
 /** Why the image build has no price, as the reason that lands on the line item. */
 export declare function buildUnpricedReason(): string
 
+/**
+ * Judges `report`'s total against a ceiling of `maxUsd` (a decimal string, such as `"1.50"`),
+ * with `onBreach` (`"warn"` or `"abort"`) saying what a breach does.
+ *
+ * `onBreach` has no default, because a breach of a lower-bound total has already been exceeded
+ * by an unknown margin, and whether that warns or refuses is the caller's call. Core's
+ * `Budget::check`, the gate `microvm cost --max-cost` applies.
+ */
+export declare function checkBudget(report: CostReport, maxUsd: string, onBreach: string): BudgetVerdict
+
 /** The warm-pool argument, with its own counter-argument attached. */
 export declare function compareResidency(size: SizeClass, holdSeconds: number, cycles?: number | undefined | null, rates?: RateTable | undefined | null): ResidencyComparison
 
@@ -1294,6 +1599,11 @@ export interface CompletionRequest {
   timeoutSec?: number
   /** The idempotency key. Omitted, one is minted. */
   execId?: string
+  /**
+   * Signal the whole process group once the command's own child exits. See
+   * `ExecOptions.reapGroupOnExit`.
+   */
+  reapGroupOnExit?: boolean
   /** Start the child's environment from the image's `ENV`. See `ExecOptions.inheritImageEnv`. */
   inheritImageEnv?: boolean
   /**
@@ -1303,6 +1613,18 @@ export interface CompletionRequest {
   clientGraceSec?: number
 }
 
+/** A connection that didn't end clean. */
+export interface ConnectionEnd {
+  /** The local client's address, `host:port`. */
+  peer: string
+  /** `"refused"`, `"truncated"`, `"unproven"`, or `"failed"`. */
+  kind: string
+  /** The close code or the HTTP status, when the end carried one. */
+  code?: number
+  /** The daemon's reason, the forwarder's explanation, or the error. */
+  detail: string
+}
+
 /**
  * The core crate's version, for a `doctor` or `manifest` command to report.
  *
@@ -1324,6 +1646,14 @@ export declare function costConstants(): string
 /** The managed base every `docs/PLATFORM.md` measurement from 2026-08-06 onward used. */
 export declare function defaultBaseImage(): BaseImageInput
 
+/** How `deleteImage` retries while the image refuses. */
+export interface DeleteImageOptions {
+  /** Attempts before giving up. Default: the core's teardown figure. */
+  attempts?: number
+  /** Seconds between attempts. Default: the core's teardown figure. */
+  backoff?: number
+}
+
 /** `Detached` as a plain object, token included, for a private store. */
 export interface DetachedObject {
   microvmId: string
@@ -1333,6 +1663,22 @@ export interface DetachedObject {
   agentToken: string
 }
 
+/** One file `downloadDir` wrote. */
+export interface DownloadedFile {
+  /** The file's path under the local directory, as the archive named it. */
+  path: string
+  /** The file's size in bytes. */
+  size: number
+}
+
+/** The line range `downloadFile` reads, 1-based and inclusive. Both absent reads the file. */
+export interface DownloadFileOptions {
+  /** The first line to read. Absent means line 1. */
+  startLine?: number
+  /** The last line to read. Absent, or past the last line, means through EOF. */
+  endLine?: number
+}
+
 /**
  * The egress posture `sandbox.run` with these options would report, without launching.
  *
@@ -1389,6 +1735,10 @@ export interface EnsureImageOptions {
   /** The build role. */
   buildRoleArn: string
   baseImage?: BaseImageInput
+  /** `buildImage`'s `baseImageVersion`; it joins the name's hash. */
+  baseImageVersion?: string
+  /** `buildImage`'s `projectDir`; the pair joins the name's hash. */
+  projectDir?: string
   /** Delete what exists under the name and build afresh. */
   force?: boolean
   tags?: Record<string, string>
@@ -1681,6 +2031,92 @@ export interface Image {
   logStream?: string
 }
 
+/**
+ * One build of an image version: one per Graviton generation, so a version's builds differ
+ * in `chipsetGeneration`. `getImageBuild` adds the snapshot sizes the listing lacks.
+ */
+export interface ImageBuild {
+  imageArn: string
+  imageVersion: string
+  /** What `getImageBuild` takes, and nothing else in the API mints one. */
+  buildId: string
+  /** `buildState`, as the service spells it. */
+  buildState: string
+  architecture: string
+  chipset: string
+  chipsetGeneration: string
+  /** Unix seconds. */
+  createdAt: number
+  /**
+   * Why the build is in this state, when the service said: where a failed build's reason
+   * lives.
+   */
+  stateReason?: string
+  /**
+   * `snapshotBuild.memorySnapshotSizeInBytes`, from `getImageBuild` only, and only when the
+   * service reported it.
+   */
+  memorySnapshotSizeInBytes?: number
+  /** `snapshotBuild.codeInstallSizeInBytes`, from `getImageBuild` only. */
+  codeInstallSizeInBytes?: number
+  /** `snapshotBuild.diskSnapshotSizeInBytes`, from `getImageBuild` only. */
+  diskSnapshotSizeInBytes?: number
+}
+
+/** One `ListMicrovmImages` item: an image's ARN, name and state. */
+export interface ImageSummary {
+  imageArn: string
+  name: string
+  /** As the service spells it, such as `"CREATING"` or `"CREATED"`. */
+  state: string
+}
+
+/**
+ * One image version as `ListMicrovmImageVersions` or `UpdateMicrovmImageVersion` reads it
+ * back: its build state, whether `RunMicrovm` launches it, and what it was built with.
+ */
+export interface ImageVersion {
+  imageArn: string
+  imageVersion: string
+  /** The version's build state, as the service spells it. */
+  state: string
+  /**
+   * `"ACTIVE"` (`RunMicrovm` launches it) or `"INACTIVE"` (it refuses; running VMs keep
+   * running).
+   */
+  status: string
+  /** Whether `RunMicrovm` launches this version. */
+  isActive: boolean
+  /**
+   * Why the version is in this state, when the service said. A failed build's reason is on
+   * its build (`listImageBuilds`), and this one is usually absent.
+   */
+  stateReason?: string
+  /** Unix seconds. */
+  createdAt: number
+  /** Unix seconds, when the service reported it. */
+  updatedAt?: number
+  baseImageArn: string
+  /**
+   * The base version the build used, as the service spells it (`"1.0"` where the managed
+   * base lists `"1"`). A record of the build, not a value to pass back as a pin.
+   */
+  baseImageVersion?: string
+  buildRoleArn: string
+  /** `codeArtifact.uri`: the artifact the version was built from. */
+  codeArtifactUri: string
+  description?: string
+  /**
+   * `resources[0].minimumMemoryInMiB`, the list's one member: the size class the version
+   * was built for, and the only place a built image reports it.
+   */
+  minimumMemoryMib?: number
+  egressNetworkConnectors?: Array<string>
+  additionalOsCapabilities?: Array<string>
+  environmentVariables?: Record<string, string>
+  tags?: Record<string, string>
+}
+
 /**
  * Installs Bedrock access for `agents` into a running VM over `session`.
  *
@@ -1699,6 +2135,18 @@ export declare function installAgentAccess(session: Session, agents: Array<Agent
  */
 export declare function installedAgents(session: Session): Promise<Array<AgentSpec>>
 
+/**
+ * Whether retrying the identical call could plausibly succeed, for an error this library raised.
+ *
+ * The TypeScript spelling of Python's `.retryable`, read off the chain every error here
+ * carries: `err.cause.message` is the `ERR_*` code, and core answers for its kind. A
+ * transient condition (a refused connection, a mint failure, a daemon not yet bootstrapped)
+ * is `true`; a full disk, a credential, or a refused argument is `false`. Anything that
+ * isn't a library error (no cause, or a cause whose message is no `ERR_*` code) is `false`,
+ * because nothing says a retry would land differently.
+ */
+export declare function isRetryable(error: unknown): boolean
+
 /** The options bag for `keepAwake`. */
 export interface KeepAwakeOptions {
   /** Seconds between polls. Default: a third of the idle window, at most 20. */
@@ -1712,6 +2160,11 @@ export interface KeepAwakeOptions {
    * platform minimum of 60 is assumed. The interval may be at most half of it.
    */
   idleWindowSec?: number
+  /**
+   * How many retryable poll failures in a row are retried, a second apart, before the
+   * keepalive ends with the error. Default: the core's `DEFAULT_TOLERATED_ERRORS`.
+   */
+  toleratedErrors?: number
 }
 
 /** What a finished keepalive did. */
@@ -1732,6 +2185,45 @@ export interface ListMicrovmsOptions {
   imageVersion?: string
 }
 
+/**
+ * The three guarded values a build takes, as separate parameters rather than fields.
+ *
+ * # Why they are not in [`BuildImageOptions`]
+ *
+ * Measured, not preferred. A `#[napi(object)]` field holding a class instance must be a
+ * `ClassInstance<'a, T>`, which carries raw `napi_value`/`napi_env` pointers and is therefore
+ * **not `Send`** — and napi's async path requires `Future: Send`. So an options object with a
+ * `size: SizeClass` field cannot be a parameter of an `async fn`, which
+ * `Sandbox.buildImage` has to be. The compiler said so in as many words:
+ * `future created by async block is not Send ... has type BuildImageOptions<'_> which is not
+ * Send`.
+ *
+ * A *reference* parameter — `Option<&SizeClass>` — has no such problem, because napi
+ * dereferences it before the future is built. So the guarded types move out of the bag and
+ * into the signature, which loses the keyword-argument look and keeps every closure:
+ *
+ * * `size` still refuses an off-table baseline, because the only way to have a `SizeClass` is
+ *   `SizeClass.fromBaselineMib` or `SizeClass.defaultClass` (TRAP-10).
+ * * `runHookTimeout` and `buildHookTimeout` are still two distinct classes, so they still
+ *   cannot be transposed — which was the whole reason they are types (BIND-2).
+ *
+ * A caller writes `sandbox.buildImage(opts, size, runTimeout, buildTimeout)` with the last
+ * three optional.
+ * One version of a managed base image, from `ListManagedMicrovmImageVersions`.
+ */
+export interface ManagedBaseVersion {
+  imageArn: string
+  /**
+   * A bare integer for a managed base (`"0"`, `"1"`), where a custom image's versions read
+   * `"1.0"`: the value `buildImage`'s pin takes, not one to compare with a build's readback.
+   */
+  imageVersion: string
+  /** Unix seconds. */
+  createdAt: number
+  /** Unix seconds, when the service reported it. */
+  updatedAt?: number
+}
+
 /** A MicroVM as `GetMicrovm` last described it. */
 export interface Microvm {
   id: string
@@ -1825,10 +2317,34 @@ export interface PlanUsageOptions {
   imageRetainedSeconds?: number
   suspendResumeCycles?: number
   snapshotGb?: number
+  /**
+   * Whether the plan launches, which reads a snapshot. Left out, the core infers it: running
+   * time, or an image of non-zero size, so suspended time alone reads no launch snapshot.
+   */
   launched?: boolean
+  /**
+   * What the report is of. Left out, `"estimate"`: the core's label, the one
+   * `microvm cost --estimate` uses for the same plan (#255).
+   */
   label?: string
 }
 
+/** What a stopped port-forward did. */
+export interface PortForwardReport {
+  /** Connections accepted. */
+  served: number
+  /** Exchanges the endpoint proxy refused, a 403 or a 502 among them. */
+  refused: number
+  /** Exchanges that upgraded, a WebSocket among them. */
+  upgrades: number
+  /** Proxy tokens the session minted by the time the forward stopped. */
+  proxyTokenMints: number
+  /** Why it stopped: `"stopped"`, `"limit"`, or `"listener-failed: <why>"`. */
+  stopped: string
+  /** Each connection that didn't end clean, in the order they ended. */
+  ended: Array<ConnectionEnd>
+}
+
 /**
  * Whether a harness can launch in `region` (default: `$AWS_REGION`, `$AWS_DEFAULT_REGION`,
  * then us-east-1), checked before it queues work.
@@ -1941,10 +2457,11 @@ export interface PromptOptions {
  * The `agentd` daemon binary for `options.version` (default: this client's own).
  *
  * Answered from `options.binary` or `$MICROVM_AGENTD` when either names a file, else the
- * version's cache entry, else the GitHub release asset, verified by `gh attestation
- * verify` or, when `gh` cannot download, by the release's `SHA256SUMS`. A fetch that
- * cannot be verified rejects with `ERR_PRECONDITION` (on `err.cause.message`), and so does
- * any binary that is not an aarch64 ELF.
+ * version's cache entry, else the GitHub release asset, verified in-process against the
+ * release workflow's Sigstore attestation or, only when GitHub can't be reached for one, the
+ * release's `SHA256SUMS`. A fetch that cannot be verified rejects with `ERR_PRECONDITION`
+ * (on `err.cause.message`), and so does any binary that is not an aarch64 ELF. Neither
+ * `gh` nor `curl` is needed.
  */
 export declare function provisionAgentd(options?: ProvisionOptions | undefined | null): Promise<Buffer>
 
@@ -1965,9 +2482,9 @@ export interface ProvisionedAgentd {
    */
   suppliedBy?: string
   /**
-   * `"attestation"` (`gh attestation verify`, provenance) or `"checksum"` (the release's
-   * `SHA256SUMS`, integrity), when fetched or when the cache entry was installed. Absent
-   * for a caller-supplied binary.
+   * `"attestation"` (the release workflow's Sigstore attestation, provenance) or
+   * `"checksum"` (the release's `SHA256SUMS`, integrity), when fetched or when the cache
+   * entry was installed. Absent for a caller-supplied binary.
    */
   verification?: string
   /** The release version provisioned for, without a leading `v`. */
@@ -1991,7 +2508,12 @@ export interface ProvisionOptions {
 
 /** Everything a launch needs. */
 export interface RunOptions {
-  /** The image to launch, or omitted for the one `buildImage` built. */
+  /**
+   * The image to launch, as an ARN or a bare image name, or omitted for the one
+   * `buildImage` built. The core resolves a name to its ARN with one `ListMicrovmImages`
+   * read, and a name no image carries is refused with `ERR_PRECONDITION` before anything
+   * launches.
+   */
   imageIdentifier?: string
   /**
    * `imageVersion`, or omitted for the image's own latest active version.
@@ -2024,6 +2546,12 @@ export interface RunOptions {
    * payload before the launch, naming the byte count.
    */
   launchEnv?: Record<string, string>
+  /**
+   * Generate a tunnel identity and deliver the VM's half with the launch, so
+   * `session.tunnel(port, {}, await sandbox.tunnelIdentity())` can prove the far end is
+   * this VM's daemon.
+   */
+  identity?: boolean
   /** Request the managed INTERNET_EGRESS connector. Omission does not block egress. */
   egress?: boolean
   /**
@@ -2046,13 +2574,17 @@ export interface RunOptions {
   suspendedSec?: number
   autoResume?: boolean
   maxDurationSec?: number
-  /** How long to wait for RUNNING. */
+  /**
+   * How long to wait for RUNNING. The wait for the daemon after it is the core's
+   * `defaultReadyTimeoutSeconds`.
+   */
   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.
+   * Whether `run` waits for RUNNING and for the daemon to answer (default `true`).
+   * `false` resolves once the launch is accepted, with the lifecycle PENDING;
+   * `waitUntilRunning` finishes both waits.
    */
   wait?: boolean
   /** Per-VM CloudWatch log group. Omitted keeps the service's default destination. */
@@ -2107,11 +2639,27 @@ export interface RunUsageOptions {
   suspendResumeCycles?: number
   /** The suspend snapshot's size. Defaults to the baseline memory footprint. */
   snapshotGb?: number
-  /** Whether a launch happened. A launch reads a snapshot. */
+  /**
+   * Whether a launch happened. A launch reads a snapshot. Left out, the core infers it:
+   * running time, or an image of non-zero size.
+   */
   launched?: boolean
+  /** What the report is of. Left out, `"run"`: the core's label, the one `microvm cost` uses. */
   label?: string
 }
 
+/** Where a tunnel or a port-forward listens, and when it stops on its own. */
+export interface ServeOptions {
+  /**
+   * A `host:port` to listen on. Default: loopback, on a port the OS picks; the handle's
+   * `localAddress` says which. Bind beyond loopback only on a network you trust: whoever
+   * connects reaches the VM with this session's credentials.
+   */
+  bind?: string
+  /** Stop accepting after this many connections. Default: serve until stopped. */
+  maxConnections?: number
+}
+
 /**
  * The daemon's protocol constants, as a JSON string, for a caller asserting against the
  * wire contract.
@@ -2226,6 +2774,30 @@ export interface StreamOptionsInput {
   idleTimeout?: number
 }
 
+/** How `syncDir` should behave. */
+export interface SyncDirOptions {
+  /** Ignore the manifest the last sync left in the VM and upload everything. */
+  full?: boolean
+  /** The in-VM removal's deadline, in seconds. Default: core's, 60. */
+  deleteTimeout?: number
+}
+
+/** What one `syncDir` did. */
+export interface SyncReport {
+  /** The uploaded archive's size, 0 when nothing travelled. */
+  uploadedBytes: number
+  /** How many members the upload carried: the changed ones, or every one when `full`. */
+  uploadedMembers: number
+  /** How many paths gone locally were removed in the VM. */
+  deleted: number
+  /** Deletions the VM's manifest ordered that weren't plain relative paths, so weren't run. */
+  refusedDeletions: number
+  /** No manifest was read (`full: true`, or none in the VM), so the whole tree travelled. */
+  full: boolean
+  /** The VM already held the tree as it is, so nothing travelled. */
+  unchanged: boolean
+}
+
 /**
  * What a teardown should delete beyond the VM itself.
  *
@@ -2246,9 +2818,10 @@ export interface TeardownOptions {
   /**
    * `false` by default: the caller is on the way out, and a teardown that blocked five
    * minutes on a state nobody reads is five minutes of a CI job. The report then honestly
-   * ends in `"TERMINATING"`.
+   * ends in `"TERMINATING"`. `true` waits for TERMINATED up to the core's lifecycle default;
+   * a number of seconds waits up to that instead.
    */
-  waitForTerminated?: boolean
+  waitForTerminated?: boolean | number
 }
 
 /** What a teardown did, and what it left behind. */
@@ -2284,6 +2857,30 @@ export interface TeardownReport {
   leaked: boolean
 }
 
+/** What a stopped tunnel did. */
+export interface TunnelReport {
+  /** Connections accepted. */
+  served: number
+  /** Connections the daemon refused, or that failed with an error. */
+  refused: number
+  /**
+   * Verified connections that ended without the daemon's end of stream, so their stream
+   * may have been cut short.
+   */
+  truncated: number
+  /**
+   * Verified connections into a daemon from before the end of stream, whose end nothing
+   * proved.
+   */
+  unproven: number
+  /** Proxy tokens the session minted by the time the tunnel stopped. */
+  proxyTokenMints: number
+  /** Why it stopped: `"stopped"`, `"limit"`, or `"listener-failed: <why>"`. */
+  stopped: string
+  /** Each connection that didn't end clean, in the order they ended. */
+  ended: Array<ConnectionEnd>
+}
+
 /** How `waitForState` polls. */
 export interface WaitForStateOptions {
   /** States that reject with `stateReason` instead of being waited through. */