@theagenticguy/microvms 0.8.0 → 0.10.0

package/index.d.ts

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