@theagenticguy/microvms 0.9.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>
   /**
@@ -64,6 +80,11 @@ export declare class AgentVm {
    * uploaded `buildArtifact`'s bytes. Several minutes, server-side.
    */
   buildImage(options: AgentImageOptions, size?: SizeClass | undefined | null): Promise<Image>
+  /**
+   * Hands the VM off to another process; see `Sandbox.detach`. The adopter passes the
+   * same agents to `AgentVm.adopt`.
+   */
+  detach(): Promise<Detached>
   /**
    * Launches with egress and waits for the daemon to answer.
    *
@@ -131,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.
@@ -170,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
 }
@@ -197,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.
    */
@@ -205,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.
@@ -213,6 +302,28 @@ export declare class CostReport {
   toJson(): string
 }
 
+/**
+ * What another process needs to adopt a VM handed off by `sandbox.detach()`.
+ *
+ * Pass the fields to `Sandbox.adopt(region, microvmId, endpoint, agentToken, port)`. The
+ * token is a method rather than a getter so it is never read by accident, and it is absent
+ * from `toString()`; `JSON.stringify` of the instance carries nothing.
+ */
+export declare class Detached {
+  get microvmId(): string
+  get endpoint(): string
+  /** The region the VM runs in, ready to pass to `Sandbox.adopt`. */
+  get region(): Region
+  /** The daemon port the endpoint's proxy tokens are minted for. */
+  get port(): number
+  /** The VM's bearer credential; store it only privately. */
+  agentToken(): string
+  /** Every field, token included, for a private encrypted store. */
+  toObject(): DetachedObject
+  /** The record without its secret. */
+  toString(): string
+}
+
 /**
  * Seconds, plus how we know them.
  *
@@ -391,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`.
@@ -400,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
@@ -437,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
@@ -476,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
 }
@@ -508,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. */
@@ -640,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
 }
@@ -698,6 +859,20 @@ export declare class Sandbox {
   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>
+  /**
+   * Hands the VM off to another process and resolves with what that process adopts it
+   * with.
+   *
+   * For a workflow whose steps run in different processes: the launching step calls this
+   * instead of dropping the sandbox (which warns that a live VM was abandoned), persists
+   * the record privately, and a later step calls `Sandbox.adopt` with it. The VM keeps
+   * running and no AWS call is made. Afterwards this sandbox is inert: `run`,
+   * `waitUntilRunning`, `suspend`, `resume`, and `terminate` are refused. Rejects with
+   * `ERR_PRECONDITION` without a live VM or when already detached.
+   */
+  detach(): Promise<Detached>
+  /** Whether `detach()` handed this sandbox's VM to another process. */
+  isDetached(): Promise<boolean>
   /** The VM id, once launched. */
   microvmId(): Promise<string | null>
   /** The proxy endpoint, once launched. */
@@ -718,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.
    *
@@ -734,16 +917,48 @@ export declare class Sandbox {
    * after the caller's artifact upload: a rejection AWS raises costs the upload first.
    */
   buildImage(options: BuildImageOptions, size?: SizeClass | undefined | null, runHookTimeout?: RunHookTimeout | undefined | null, buildHookTimeout?: BuildHookTimeout | undefined | null): Promise<Image>
+  /**
+   * Builds or reuses the content-addressed image for a task: one call from build inputs
+   * to a ready image.
+   *
+   * The name is `<namePrefix>-<hash12>` over the daemon, the Dockerfile, the build
+   * context, the base image and the size class. A ready image is returned with
+   * `reused: true` and no upload; a running build is waited out; a failed image — or any
+   * image under `force` — is deleted and rebuilt; an absent one is uploaded to
+   * `s3://<s3Bucket>/<s3KeyPrefix>/<name>/artifact.zip`, created, and waited for. When a
+   * concurrent caller creates the name first, this call waits for that build and returns
+   * it with `reused: true`. Every local check runs before the first AWS call.
+   */
+  ensureImage(options: EnsureImageOptions, size?: SizeClass | undefined | null): Promise<EnsuredImage>
   /**
    * The artifact bytes to upload to `codeArtifactUri`.
    *
-   * The upload is the caller's: S3 is not in the core's dependency set. Takes the same
+   * The upload is the caller's on this path (`ensureImage` uploads for itself). Takes the same
    * options as [`Self::build_image`] so the bytes a caller puts in the bucket are the bytes
    * the build will receive.
    */
   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
    *
@@ -753,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
@@ -821,6 +1038,16 @@ export declare class Session {
   agentToken(): Promise<string>
   /** The endpoint this session addresses. */
   endpoint(): Promise<string>
+  /**
+   * The launch's egress posture: `"open"`, `"unsealed"`, `"best-effort"`, or `"sealed"`.
+   *
+   * The value the CLI envelope's `egressPosture` reports for the same launch options, and
+   * what `egressPostureFor` answers before the launch. A session that does not hold its
+   * launch options (`Session.direct`, `Session.attach`, an adopted sandbox) reports
+   * `"unsealed"`. Advertise network isolation only for `"sealed"`. Async like `endpoint()`,
+   * because a sandbox-held session is read under the sandbox's lock.
+   */
+  egressPosture(): Promise<string>
   /** The port the proxy token is scoped to. */
   port(): Promise<number>
   /** Unauthenticated liveness. */
@@ -875,6 +1102,22 @@ export declare class Session {
   exec(execId: string): Promise<ExecHandle>
   /** Start, wait, ack. The one-shot shape, for when output is all you want. */
   runSync(command: string | Array<string>, options?: ExecOptions | undefined | null): Promise<ExecResult>
+  /**
+   * Start, stream, and collect one command: exactly one `ExecResult` back (BIND-6..10).
+   *
+   * With `onOutput`, each output chunk (a `StreamEvent` of kind `"output"`) is handed to it
+   * as it arrives. The result then comes from the ack that follows the terminal `exit`
+   * event, or, when the stream ends without one, from a wait and ack. When `timeoutSec +
+   * clientGraceSec` passes first (or, with no `timeoutSec`, the VM's maximum lifetime), the
+   * process group is killed and the exec waited for and acked within `clientGraceSec` once
+   * more; if that fails too the result is synthesized with `posixExitCode` 124.
+   *
+   * A throwing `onOutput` stops delivery; the exec is still waited for and acked so nothing
+   * is left behind, and then the promise rejects with the callback's message. `shell: true`
+   * runs `/bin/sh -c`; for bash semantics pass `shell: "bash"` with a script string, or
+   * `["bash", "-c", script]` for a daemon that predates named shells.
+   */
+  runToCompletion(command: string | string[], options?: CompletionRequest | undefined | null, onOutput?: ((chunk: StreamEvent) => unknown) | undefined | null): Promise<ExecResult>
   /** Signals an exec's whole process group. Returns whether anything was signalled. */
   kill(execId: string): Promise<boolean>
   /**
@@ -890,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>
   /**
@@ -943,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.
    *
@@ -969,6 +1265,16 @@ export declare class SizeClass {
    * readings differ in both memory and rate, and neither has been measured.
    */
   static fromBaselineMib(mib: number): SizeClass
+  /**
+   * The smallest class whose baseline covers a resource request (BIND-14).
+   *
+   * `cpus` in vCPUs and `memoryMib` in MiB, each a request; `undefined` or zero is no
+   * requirement on that axis, and with none on either the answer is `defaultClass()`.
+   * Chosen by baseline, the billed and always-present figure. Throws `ERR_INVALID_ARG`
+   * naming the largest class when no class covers the request, or for a CPU figure that is
+   * not a finite non-negative number.
+   */
+  static fromRequest(cpus?: number | undefined | null, memoryMib?: number | undefined | null): SizeClass
   /**
    * The platform's default, 2048 MiB. Not the smallest — a 0.5 GB baseline fixes the
    * guest's always-present ceiling at 2 GB, which OOM-kills a real test suite, and the
@@ -1006,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.
  *
@@ -1020,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. */
@@ -1035,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
@@ -1060,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. */
@@ -1087,6 +1464,16 @@ export interface AgentSpecInput {
   cliVersion?: string
 }
 
+/**
+ * The base a task Dockerfile pairs with: the managed base's `name`, so `baseImageArn` is
+ * unchanged, and the Dockerfile's first `FROM` as `dockerRef`, digest pin included.
+ *
+ * `buildImage` refuses a Dockerfile whose first `FROM` is not the base's `dockerRef`; a base
+ * derived from that Dockerfile passes by construction. Throws `ERR_INVALID_ARG` for a
+ * Dockerfile with no `FROM`.
+ */
+export declare function baseImageFromDockerfile(dockerfile: string): BaseImageInput
+
 /**
  * The platform's managed base image, paired with the Dockerfile `FROM` it goes with.
  *
@@ -1129,15 +1516,23 @@ export interface BuildImageOptions {
   /** The daemon binary's bytes, zipped into the artifact. */
   binary: Uint8Array
   /**
-   * Where the artifact is uploaded to. This client does not upload — S3 is not in the
-   * core's dependency set — so the caller puts the bytes there and passes the URI.
+   * Where the artifact is uploaded to. `buildImage` does not upload: the caller puts the
+   * bytes there and passes the URI. `ensureImage` is the path that uploads for itself.
    */
   codeArtifactUri: string
   /** 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
   /**
@@ -1166,9 +1561,70 @@ 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
 
+/**
+ * How `runToCompletion` should start and collect a command.
+ *
+ * The `ExecOptions` a completed run can use (no `stdin`, which nothing would write, and no
+ * `timeout`, which `clientGraceSec` replaces), plus the client grace.
+ */
+export interface CompletionRequest {
+  /**
+   * `true` runs a single script string under `/bin/sh -c`; a string such as `"bash"` runs
+   * it under that shell, resolved by the daemon in the guest. See `ExecOptions.shell`.
+   */
+  shell?: boolean | string
+  cwd?: string
+  env?: Record<string, string>
+  /** A numeric uid, or a name the daemon resolves in the guest. See `ExecOptions.user`. */
+  user?: number | string
+  /** A numeric gid, or a name the daemon resolves in the guest. */
+  group?: number | string
+  /**
+   * The daemon's own kill deadline for the child. The client deadline is this plus
+   * `clientGraceSec`.
+   */
+  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
+  /**
+   * How long past `timeoutSec` the client waits before it kills, and how long it then
+   * waits for the killed exec's result. Defaults to the core's 60 seconds.
+   */
+  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.
  *
@@ -1190,6 +1646,105 @@ 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
+  endpoint: string
+  region: string
+  port: number
+  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.
+ *
+ * One of `"open"`, `"unsealed"`, `"best-effort"`, or `"sealed"`: the value the launched
+ * session's `egressPosture()` and the CLI envelope's `egressPosture` carry. Throws the launch's
+ * own `ERR_INVALID_ARG` for options it would refuse. No AWS call and no credentials, so a
+ * harness can decide before a build whether a no-network task is satisfiable.
+ *
+ * Only `"sealed"` is network isolation, and no option answers it: isolation needs a VPC
+ * egress connector and separately verified VPC routing without an internet gateway or NAT
+ * gateway. Omitting `egress` is `"unsealed"`; `denyEgress` is `"best-effort"`. Without a
+ * `region`, each connector ARN is checked against the region it names.
+ */
+export declare function egressPostureFor(egress?: boolean | undefined | null, connectors?: Array<string> | undefined | null, denyEgress?: boolean | undefined | null, region?: Region | undefined | null): string
+
+/** What `ensureImage` returns: the ready image and how this call got it. */
+export interface EnsuredImage {
+  /** The ready image; pass `image.identifier` to `run`. */
+  image: Image
+  /**
+   * True when this call's own create did not build the image: it was ready, a build
+   * already running was waited out, or a concurrent caller won the create race.
+   */
+  reused: boolean
+  /** `s3://<bucket>/<prefix>/<name>/artifact.zip`, whether or not this call uploaded it. */
+  artifactUri: string
+  /** Whether this call uploaded the artifact. */
+  uploaded: boolean
+  /** What reading the build context skipped, one line each. */
+  warnings: Array<string>
+}
+
+/**
+ * Everything `ensureImage` needs besides the size class.
+ *
+ * `baseImage` defaults to `baseImageFromDockerfile(dockerfile)`; `waitTimeoutSeconds` is
+ * the build wait, 45 minutes by default. `contextDir` is read as `docker build` reads a
+ * context: `Dockerfile.dockerignore`, else `.dockerignore`, is honoured, and symlinks are
+ * skipped with a line in the result's `warnings`.
+ */
+export interface EnsureImageOptions {
+  /** The image name's stem; the name is `<namePrefix>-<hash12>`. */
+  namePrefix: string
+  /** The daemon binary's bytes. */
+  binary: Uint8Array
+  /** The Dockerfile, usually `wrapDockerfile(task)`. */
+  dockerfile: string
+  /** The directory the Dockerfile's `COPY` lines read, or omitted for none. */
+  contextDir?: string
+  /** The artifact bucket, in the sandbox's region. */
+  s3Bucket: string
+  /** A key prefix inside the bucket, or omitted for the bucket root. */
+  s3KeyPrefix?: string
+  /** 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>
+  waitTimeoutSeconds?: number
+}
+
 /**
  * Every `ERR_*` code this library can raise, for a caller building an exhaustive switch.
  *
@@ -1209,12 +1764,23 @@ export declare function estimateRun(size: SizeClass, options?: PlanUsageOptions
 
 /** How an exec should be started. Every field optional; the defaults are the daemon's. */
 export interface ExecOptions {
-  /** A single script string rather than an argv. Requires `shell: true`. */
-  shell?: boolean
+  /**
+   * `true` runs a single script string under `/bin/sh -c`; a string such as `"bash"`
+   * runs it under that shell, resolved by the daemon in the guest, and a shell the guest
+   * does not have is refused (`unknown_shell`) before anything starts.
+   */
+  shell?: boolean | string
   cwd?: string
   env?: Record<string, string>
-  user?: number
-  group?: number
+  /**
+   * A numeric uid, or a name the daemon resolves against the guest's `/etc/passwd`. An
+   * unknown name is refused (`unknown_user`) before anything starts. A user with a passwd
+   * row gets `HOME`, `USER` and `LOGNAME` from it, beneath the launch environment and
+   * `env`.
+   */
+  user?: number | string
+  /** A numeric gid, or a name the daemon resolves against the guest's `/etc/group`. */
+  group?: number | string
   /** The daemon's own kill deadline for the child, distinct from a client-side `wait`. */
   timeoutSec?: number
   /** Whether to open a stdin pipe. Writing without this is a 409. */
@@ -1233,6 +1799,12 @@ export interface ExecOptions {
    * guarantee for callers who rely on it.
    */
   reapGroupOnExit?: boolean
+  /**
+   * Start the child's environment from the image's `ENV` (minus `AGENTD_*`, never the
+   * token), beneath everything else (AGENTD-11). Off by default, which keeps the child's environment
+   * exactly the launch environment plus `env`.
+   */
+  inheritImageEnv?: boolean
 }
 
 /**
@@ -1271,6 +1843,22 @@ export interface ExecResult {
    * exec, since neither is a success.
    */
   ok: boolean
+  /**
+   * The exit code a POSIX shell would report (BIND-6): 124 when a deadline ended the
+   * command (the daemon's, or `runToCompletion`'s client deadline), 128 plus the signal
+   * for any other signal death, otherwise `exitCode`. `null` only for a running exec.
+   */
+  posixExitCode?: number
+  /**
+   * Human-readable annotations, one per condition that changes how the output reads
+   * (BIND-7). Empty for a clean result; append them to stderr as they are.
+   */
+  notes: Array<string>
+  /**
+   * True when `runToCompletion` synthesized this result because nothing came back after
+   * its client-deadline kill (BIND-10): `posixExitCode` is 124 and the output is unknown.
+   */
+  synthesized: boolean
 }
 
 /**
@@ -1372,6 +1960,12 @@ export interface Health {
    * VM's identity.
    */
   identitySteps: Array<IdentityStep>
+  /**
+   * How many variables the daemon's image-environment snapshot holds, or `null` when it
+   * holds none. `null` is also what a daemon built before `inheritImageEnv` reports, and
+   * such a daemon ignores that option. The values are never reported.
+   */
+  imageEnvKeys?: number
 }
 
 /** One lifecycle-hook invocation, as the daemon observed it. */
@@ -1437,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`.
  *
@@ -1455,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. */
@@ -1468,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. */
@@ -1488,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
@@ -1581,10 +2317,70 @@ 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.
+ *
+ * Three checks: the region resolves (advisory when `Region.unlisted`), the credential chain
+ * resolves credentials (no AWS call), and one `ListManagedMicrovmImages` page answers in that
+ * region, the only AWS operation, free and read-only. A check after a failure is reported
+ * with `ran: false` and makes no call. Nothing billable, nothing mutating. It does not check
+ * roles, the artifact bucket, quotas, or VPC connectors. Never rejects; read `report.ok`.
+ */
+export declare function preflight(region?: Region | undefined | null): Promise<PreflightReport>
+
+/** One line of a preflight report. */
+export interface PreflightCheck {
+  /** `"region"`, `"credentials"`, or `"service"`. */
+  name: string
+  ok: boolean
+  /** Whether a failure decides the report's `ok`. An unlisted region's line is advisory. */
+  fatal: boolean
+  /** False when an earlier check's failure kept this one from running (and calling AWS). */
+  ran: boolean
+  detail: string
+  /** What to do about a failure; empty on a pass. */
+  remedy: string
+}
+
+/** What `preflight` found: three checks and whether a launch could proceed. */
+export interface PreflightReport {
+  /** True exactly when no fatal check failed or was skipped. */
+  ok: boolean
+  /** The region checked, absent when none resolved. */
+  region?: string
+  /** `region`, `credentials`, and `service`, in that order. */
+  checks: Array<PreflightCheck>
+}
+
 /**
  * What `wait()` resolves to.
  *
@@ -1657,9 +2453,67 @@ export interface PromptOptions {
   reapGroupOnExit?: boolean
 }
 
+/**
+ * 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 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>
+
+/** `provisionAgentd`, answering with the bytes and how they got here. */
+export declare function provisionAgentdReport(options?: ProvisionOptions | undefined | null): Promise<ProvisionedAgentd>
+
+/** A provisioned `agentd` binary and how it got here: `provisionAgentdReport()`'s answer. */
+export interface ProvisionedAgentd {
+  /** The binary itself, an aarch64 ELF. */
+  data: Buffer
+  /** Where the binary is on disk: the cache entry, or the caller's own path. */
+  path: string
+  /** `"caller-supplied"`, `"cache"`, or `"fetched"`. */
+  source: string
+  /**
+   * For a caller-supplied binary, `"argument"` (the `binary` option) or `"env"`
+   * (`$MICROVM_AGENTD`).
+   */
+  suppliedBy?: string
+  /**
+   * `"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`. */
+  version: string
+  /** The lowercase hex SHA-256 of `data`. */
+  sha256: string
+}
+
+/** What to provision. Every field is optional. */
+export interface ProvisionOptions {
+  /** The release version, with or without a leading `v`. Defaults to `coreVersion()`. */
+  version?: string
+  /**
+   * The state directory the cache lives under. Defaults to the CLI's
+   * (`$MICROVM_STATE_DIR`, else `~/.microvm/runs`), so every surface shares one cache.
+   */
+  stateDir?: string
+  /** A binary the caller manages. Outranks `$MICROVM_AGENTD`; must be an aarch64 ELF. */
+  binary?: string
+}
+
 /** 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.
@@ -1692,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
   /**
@@ -1714,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. */
@@ -1775,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.
@@ -1894,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.
  *
@@ -1914,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. */
@@ -1952,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. */
@@ -1964,3 +2893,28 @@ export interface WaitForStateOptions {
 
 /** Every daemon-status class, as `err.cause.cause.message` names them. */
 export declare function wireKinds(): Array<string>
+
+/**
+ * A task Dockerfile with the agentd stanza appended, ready for `buildImage`.
+ *
+ * The result is the task text, a newline if it lacked one, `USER root` when the task's last
+ * `USER` is anyone else, then the stanza the default Dockerfile uses: `COPY agentd /agentd`,
+ * the chmod, `ENV AGENTD_PORT`, `EXPOSE`, `ENTRYPOINT []` and `CMD ["/agentd"]`. Pass the
+ * result to `buildImage` with `baseImage: baseImageFromDockerfile(result)`.
+ *
+ * Throws `ERR_INVALID_ARG` for a task with no `FROM`, one that ends inside a line
+ * continuation or an unterminated heredoc (either would swallow the stanza), a keepalive the
+ * client cannot tolerate, a port of 0, a workdir that is not one absolute path, or
+ * `inheritWorkdir` with nothing to inherit.
+ */
+export declare function wrapDockerfile(taskDockerfile: string, options?: WrapDockerfileOptions | undefined | null): string
+
+/** What `wrapDockerfile` takes besides the task text. Every field is optional. */
+export interface WrapDockerfileOptions {
+  /** The agent port the stanza names, 9000 by default. It must match the sandbox's. */
+  port?: number
+  /** A working directory for the stanza to create and set, as the default Dockerfile does. */
+  workdir?: string
+  /** Refuse a result with no `WORKDIR` anywhere, because the exec would inherit `/`. */
+  inheritWorkdir?: boolean
+}