microvms 0.0.0-stage → 1.0.0

package/index.d.ts

@@ -0,0 +1,2933 @@
+// 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 */
+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.
+ *
+ * The sequence is the CLI's `agent-up` and `agent-prompt`, one method per step: `findImage`
+ * or `buildArtifact` + your upload + `buildImage`; `launch`; `installAccess`; `prompt` or
+ * `promptSync`; `terminate`. `sandbox()` and `session()` reach the same VM for suspend,
+ * resume, file transfer, and any other exec.
+ */
+export declare class AgentVm {
+  /**
+   * Resolves credentials for `region` and returns a VM with nothing built or launched.
+   *
+   * `agents` defaults to Claude Code alone. An empty list or a repeated agent is refused by
+   * 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
+  /**
+   * The sandbox this VM drives, for suspend, resume, and the lifecycle getters. The same
+   * lock: a call here and a call there cannot interleave.
+   */
+  sandbox(): Sandbox
+  /** The session, once `launch` has resolved. */
+  session(): Promise<Session | null>
+  /**
+   * The Dockerfile `buildImage` will send: the client's agentd stanza plus the agent
+   * layers. Nothing in it is a secret.
+   */
+  dockerfile(): Promise<string>
+  /**
+   * The image name for these specs and this daemon binary: `agent-vm-<agents>-<hash12>`.
+   * 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>
+  /**
+   * Builds the image and waits for it to become usable. `codeArtifactUri` is where you
+   * 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 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>
+  /**
+   * Mints a token (or takes yours) and installs Bedrock access for this VM's agents.
+   *
+   * Resolves with the token used, so `expiresAt` says when to call this again. Re-runnable
+   * on a running VM: that call is the credential refresh.
+   */
+  installAccess(token?: BearerToken | undefined | null, ttlSeconds?: number | undefined | null): Promise<BearerToken>
+  /** Starts one task for `agent` and resolves with its handle. Does not wait. */
+  prompt(agent: string, task: string, options?: PromptOptions | undefined | null): Promise<ExecHandle>
+  /**
+   * Start, wait, ack: one task's whole result. `timeoutSec` defaults to 900 seconds,
+   * because agent tasks run minutes, and is also the daemon-side budget.
+   */
+  promptSync(agent: string, task: string, options?: PromptOptions | undefined | null): Promise<ExecResult>
+  /** Tears down, best-effort, never rejecting; see `Sandbox.terminate`. */
+  terminate(options?: TeardownOptions | undefined | null): Promise<TeardownReport>
+}
+
+/**
+ * What a line item's cost can be: an estimate, or unpriced.
+ *
+ * `kind` is the stable tag, and exactly one of `usd`/`unpriced` is non-null — so a reader
+ * who checks either has handled both.
+ */
+export declare class Amount {
+  /** `"estimated-usd"` or `"unpriced"`. */
+  get kind(): string
+  /**
+   * The estimate, or `null` when there is no published rate.
+   *
+   * `null` rather than a zero — the one arithmetic this module refuses to enable.
+   */
+  get usd(): EstimatedUsd | null
+  /** The unpriced half, or `null` when the line was priced. */
+  get unpriced(): Unpriced | null
+  toString(): string
+}
+
+/**
+ * A Bedrock bearer token, the region it was minted for, and when it stops working.
+ *
+ * A class rather than an object because it carries a secret: `JSON.stringify` gives `{}` and
+ * only `expose()` returns the text.
+ */
+export declare class BearerToken {
+  /** The token text, for a caller writing it into an environment themselves. */
+  expose(): string
+  /**
+   * 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. */
+  get region(): Region
+  /** The length of the token, never the token. */
+  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(): 3600
+  get seconds(): number
+  toString(): string
+}
+
+/**
+ * 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.
+ */
+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>
+  /** `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
+}
+
+/** Per-phase attribution for one sandbox, measured or projected. */
+export declare class CostReport {
+  get label(): string
+  get size(): SizeClass
+  get rates(): RateTable
+  get items(): Array<LineItem>
+  /** The line items with a published rate. */
+  get priced(): Array<LineItem>
+  /** The line items with no published rate. */
+  get unpriced(): Array<LineItem>
+  /** The total, which is a lower bound whenever anything is unpriced. */
+  get total(): Total
+  /** False whenever any phase has no published rate. */
+  get complete(): boolean
+  /** True only if every duration was timed. An estimate is never this. */
+  get fullyMeasured(): boolean
+  /** The staleness warning the table carried when this was computed. */
+  get staleness(): string | null
+  /**
+   * The line items belonging to one phase.
+   *
+   * 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
+   * `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.
+   */
+  byPhase(phase: string): Array<LineItem>
+  /** Plain text, leading with what the dollars are rather than with the dollars. */
+  render(): 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.
+   */
+  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.
+ *
+ * No constructor: `Duration.measured(s)` and `Duration.projected(s)` are the only doors,
+ * so a provenance cannot be omitted. See the module docs.
+ */
+export declare class Duration {
+  /**
+   * A timed phase: a clock ran and this is what it read.
+   *
+   * Fallible because the float is — a negative or non-finite figure has no reading as a
+   * duration, and the refusal is the core's, message and all.
+   */
+  static measured(seconds: number): Duration
+  /** A hypothetical phase: an estimate's input, or a documented minimum nobody timed. */
+  static projected(seconds: number): Duration
+  /** The span in seconds, without its label. */
+  get seconds(): number
+  /** `"measured"` or `"projected"`. */
+  get provenance(): string
+  /** True only for a timed span. What `CostReport.fullyMeasured` reads. */
+  get isMeasured(): boolean
+  /** `Ns (provenance)` — the label travels with the figure. */
+  toString(): string
+}
+
+/**
+ * Dollars derived from published rates. Not the bill.
+ *
+ * # There is no way to get a number out of this
+ *
+ * No `valueOf`, no `toJSON`, no `Symbol.toPrimitive`, no `add`, and no constructor. So
+ * `Number(usd)` is `NaN`, `usd * 2` is `NaN`, `+usd` is `NaN`, and `JSON.stringify(usd)`
+ * answers `{}`. The figure comes out through [`Self::amount`], a **string** — one visible
+ * step that keeps the type name at the call site, which is a decision a reviewer can see.
+ */
+export declare class EstimatedUsd {
+  /**
+   * The figure as an exact decimal **string**.
+   *
+   * A string and not a number: a JS double cannot hold `0.0000276944` summed a few
+   * thousand times without drifting in the direction of a bill nobody can reproduce.
+   */
+  get amount(): string
+  /** The figure at display precision: two places at a dollar or more, six below. */
+  get displayAmount(): string
+  /** `~$X (estimated)`. */
+  toString(): string
+}
+
+/**
+ * One exec, addressed by its caller-minted id.
+ *
+ * The id is the idempotency key, so a handle survives a process restart: rebuild it through
+ * `Session.exec(execId)` and every method still addresses the same server-side exec.
+ */
+export declare class ExecHandle {
+  get execId(): string
+  /** Reads current status and output. Read-only server-side; safe to spin on. */
+  poll(): Promise<ExecResult>
+  /**
+   * Polls until the exec is done, or rejects with `ERR_TIMEOUT`.
+   *
+   * A timeout has not touched the exec — polling is read-only and output lives until it
+   * is acked — so a caller that gives up can come back and poll again.
+   */
+  wait(timeout?: number | undefined | null): Promise<ExecResult>
+  /**
+   * An async iterator over output as it arrives, reconnecting at the last good offset.
+   *
+   * `for await (const event of handle.stream())`.
+   */
+  stream(options?: StreamOptionsInput | undefined | null): ExecStream
+  /**
+   * Writes to the child's stdin. Requires the exec to have been started with
+   * `stdin: true`, or the daemon answers 409.
+   *
+   * `eof` in the same call is the common case for feeding a prompt: two round trips would
+   * leave a window where the child has the bytes but not the EOF that says the input is
+   * complete.
+   */
+  writeStdin(data: Uint8Array, eof?: boolean | undefined | null): Promise<StdinAck>
+  /**
+   * Sends EOF. Nothing else closes stdin: the daemon's copy of the pipe outlives the
+   * child's wait, so a child blocked reading stdin hangs until its timeout otherwise.
+   */
+  closeStdin(): Promise<StdinAck>
+  /** Releases the buffered output and starts the TTL clock. */
+  ack(): Promise<ExecResult>
+  /**
+   * Signals the whole process group. `false` means nothing was signalled because the
+   * child had already been reaped — which is the outcome a kill wanted.
+   */
+  kill(): Promise<boolean>
+  /**
+   * Wait, then ack, returning the result that carries the output.
+   *
+   * Which result comes back matters: the ack response carries the released output and a
+   * poll issued after the ack reports `acked` with none, so returning the wrong one is a
+   * silent empty-output bug. The core sequences it.
+   */
+  waitAndAck(timeout?: number | undefined | null): Promise<ExecResult>
+}
+
+/**
+ * A long-running exec as the AI SDK's `SandboxProcess` shape.
+ *
+ * See the module docs. Built by `Session.spawn`, never by a constructor: a process object
+ * with no exec behind it is one whose every method fails in a way that looks like a dead VM.
+ */
+export declare class ExecProcess {
+  /**
+   * The exec id, which is the idempotency key.
+   *
+   * Read it back to reattach from another process: `session.exec(id)` addresses the same
+   * server-side exec, and `session.spawn` with the same id does not start a second child.
+   */
+  get execId(): string
+  /**
+   * The process id, if the sandbox exposes one.
+   *
+   * **Always `null`**, and that is a true answer rather than a stub. The daemon signals a
+   * whole process group and addresses an exec by its caller-minted id; it publishes no pid,
+   * because a pid inside a MicroVM is not meaningful outside it and would invite a caller to
+   * signal it directly through a channel that does not exist. The harness contract marks
+   * `pid` optional for exactly this case.
+   */
+  get pid(): number | null
+  /**
+   * The child's standard output as a stream of bytes.
+   *
+   * One stream per process: reading this twice hands back the same object, because two
+   * readers over one channel would split the bytes between them.
+   */
+  get stdout(): ReadableStream<Uint8Array>
+  /**
+   * The child's standard error as a stream of bytes.
+   *
+   * Independent of [`Self::stdout`]: order is preserved within each and is not recoverable
+   * between them, which is what the wire supports (one shared offset space) and what the
+   * harness shape promises.
+   */
+  get stderr(): ReadableStream<Uint8Array>
+  /**
+   * Every byte range the daemon could not replay, under `gapPolicy: 'event'`.
+   *
+   * Empty under the default policy, where a gap errors the streams instead — see the module
+   * docs for why the ignorable form is not the default.
+   */
+  get gaps(): Array<OutputGap>
+  /**
+   * Resolves when the process exits.
+   *
+   * **From the daemon's exec record, not from the streams ending**, and that is the whole
+   * reason a suspend/resume does not look like a clean exit here: a stream that stopped
+   * carrying bytes is a stream that stopped, which is the identical observation for a cut
+   * connection and a finished command. Only the daemon's record distinguishes them.
+   *
+   * Rejects with `ERR_TIMEOUT` past `timeoutSeconds` (300 by default). A timeout has not
+   * touched the exec — polling is read-only and the output lives until it is acked — so a
+   * caller that gives up can call this again.
+   */
+  wait(timeoutSeconds?: number | undefined | null): Promise<ProcessExit>
+  /**
+   * Terminates the process. Idempotent.
+   *
+   * Signals the whole process group rather than the direct child, so a shell's children go
+   * with it. Idempotent because the daemon answers 200 either way: a group that had already
+   * been reaped reports nothing signalled, which is the outcome a kill wanted — so a second
+   * call is a success and not a 404. That is what lets a harness call this in a `finally`
+   * without guarding it.
+   */
+  kill(): Promise<void>
+}
+
+/**
+ * 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`.
+ *
+ * This type implements JavaScript's async iterable protocol.
+ * It can be used with `for await...of` loops.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+ */
+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
+ * 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
+  /**
+   * The AWS billing line, or `null` for a phase with no published rate to attribute it
+   * to.
+   */
+  get line(): string | null
+  /**
+   * The consumed quantity, exact, as a string.
+   *
+   * Exact so a reader can check the arithmetic against the rate table, which is the only
+   * defence against a rate that drifts without anyone noticing.
+   */
+  get quantity(): string
+  /** The quantity at display precision, for a column a human scans. */
+  get displayQuantity(): string
+  get unit(): string
+  get amount(): Amount
+  get duration(): Duration | null
+  get note(): 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
+   * `Option` field serializes as `null`, which is the one value that gets summed as zero
+   * by anything permissive. A caller does `JSON.parse`, which is one visible step.
+   */
+  toJson(): string
+  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 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
+}
+
+/**
+ * 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>
+  /**
+   * 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. */
+export declare class RateTable {
+  /**
+   * us-east-1, read 2026-08-07, as recorded in `docs/PLATFORM.md`.
+   *
+   * There is deliberately no constructor taking rates. The core's table has private rate
+   * fields and exactly two doors — this one and `from_catalog`, which refuses a catalog
+   * whose ARM compute line is missing rather than substituting the x86 one, 17.9% higher
+   * (COST-9). A constructor taking five numbers would reopen precisely that.
+   */
+  static pinned(): RateTable
+  get region(): string
+  get sourceUrl(): string
+  /** ISO 8601, matching the Python's `retrieved.isoformat()`. */
+  get retrieved(): string
+  get vcpuSecond(): string
+  get gbSecond(): string
+  /**
+   * Per GB-month. The one derived figure: the API quotes per GB-hour, and this is that
+   * times 730.
+   */
+  get storageGbMonth(): string
+  get snapshotReadGb(): string
+  get snapshotWriteGb(): string
+  /** Snapshot storage bills at least this long however briefly the snapshot exists. */
+  get minimumRetentionSeconds(): number
+  /** Zero: MicroVMs bills per second with no per-request charge. */
+  get perRequest(): string
+  /** True: vCPU and memory are two line items, as the pricing page prices them. */
+  get billsVcpuAndMemorySeparately(): boolean
+  /** False: no published MicroVMs free tier. The Lambda one is Functions-only. */
+  get freeTier(): boolean
+  /**
+   * `null` means **not published**, not one second. Nothing rounds a duration up, because
+   * inventing an increment would overcharge every short exec.
+   */
+  get minimumBillingIncrementSec(): number | null
+  /** How many days ago these rates were read, against today UTC. */
+  ageDays(): number
+  /** The staleness warning, or `null` when the table is fresh. */
+  staleness(): string | null
+}
+
+/** An AWS region, closed over the five that run MicroVMs plus a named escape hatch. */
+export declare class Region {
+  static usEast1(): Region
+  static usEast2(): Region
+  static usWest2(): Region
+  static euWest1(): Region
+  static apNortheast1(): Region
+  /**
+   * One of the five, or a refusal naming the null-message trap.
+   *
+   * The boundary a region name arrives at from an environment variable or a config file,
+   * where it is still a string. The refusal is the core's `FromStr`, message and all —
+   * this is a call, not a check written here.
+   */
+  static parse(name: string): Region
+  /**
+   * Opts into a region this client has not seen carry MicroVMs.
+   *
+   * **This costs you the diagnostic.** If the region does not run MicroVMs, the first
+   * control-plane call answers `AccessDeniedException` with a null message, and you will
+   * spend the next hour reading an IAM policy that is correct. Named rather than a flag so
+   * a reader of the call site can see the opt-in.
+   *
+   * A supported name handed here comes back as its proper region, so
+   * `Region.unlisted("us-east-1")` equals `Region.usEast1()`.
+   */
+  static unlisted(name: string): Region
+  /** Every region this client has seen carry MicroVMs. */
+  static supported(): Array<Region>
+  /** The wire spelling, which is also the endpoint's middle segment. */
+  get name(): string
+  /** Whether this is one of the five rather than an opted-into unlisted name. */
+  get isSupported(): boolean
+  toString(): string
+  /**
+   * Whether two regions are the same one.
+   *
+   * A method and not `===`: JS compares class instances by reference, so two
+   * `Region.usEast1()` calls are different objects. Named `equals` because that is what a
+   * JS reader expects to reach for.
+   */
+  equals(other: Region): boolean
+}
+
+/** Running versus suspended for the same VM over the same wall time. */
+export declare class ResidencyComparison {
+  get size(): SizeClass
+  /**
+   * The wall time both sides cover. Always projected: a comparison is a hypothetical
+   * about a hold nobody has taken yet.
+   */
+  get hold(): Duration
+  get cycles(): number
+  get running(): CostReport
+  get suspended(): CostReport
+  /** How many times more the running VM costs, as an exact decimal string. */
+  get ratio(): string
+  /**
+   * One suspend/resume: a snapshot write plus a read, per GB.
+   *
+   * Without it the honest conclusion inverts — "suspend constantly" reads as free.
+   */
+  perCycle(): EstimatedUsd
+  /**
+   * How long a VM must stay suspended for the cycle to pay for itself, exact, as a
+   * string. The number a pool scheduler needs, and the one a "100x cheaper" headline
+   * hides.
+   */
+  breakEvenSeconds(): string
+  /**
+   * The break-even hold as a number. **Lossy, and named so.**
+   *
+   * Seconds, not dollars: no money figure has a numeric accessor anywhere in this file.
+   */
+  breakEvenSecondsNumber(): number
+  render(): string
+}
+
+/**
+ * A timeout for the `run`, `resume`, `suspend`, or `terminate` hook: 1..=60 seconds.
+ *
+ * A distinct class from [`BuildHookTimeout`] and deliberately not interchangeable with it.
+ */
+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(): 60
+  get seconds(): number
+  toString(): string
+}
+
+/**
+ * One MicroVM's whole life.
+ *
+ * The five transitions are `buildImage`, `run`, `suspend`, `resume`, and `terminate`, and
+ * every state guard lives in the core — see the module docs.
+ */
+export declare class Sandbox {
+  /**
+   * Resolves credentials for `region` and returns a sandbox with nothing launched.
+   *
+   * A factory rather than a constructor because credential resolution is async, and a
+   * `#[napi(constructor)]` cannot be. `region` is a [`Region`] instance and not a string,
+   * which is TRAP-6 at this boundary.
+   */
+  static create(region: Region): Promise<Sandbox>
+  /**
+   * The lifecycle state: `"PENDING"`, `"RUNNING"`, `"SUSPENDING"`, `"SUSPENDED"`,
+   * `"TERMINATING"`, or `"TERMINATED"`.
+   *
+   * Spelled as the service spells it, because a reader compares it against a `GetMicrovm`
+   * response and `Suspended` beside `SUSPENDED` reads like two facts.
+   */
+  lifecycle(): Promise<string>
+  /**
+   * Whether the agent token has been installed (STATE-2).
+   *
+   * Set by the platform reporting RUNNING, not by the launch call: the run hook is what
+   * delivers the token, and a launch that died during startup delivered nothing.
+   */
+  tokenInstalled(): Promise<boolean>
+  /** Whether an image is recorded as existing (STATE-1). */
+  imageExists(): Promise<boolean>
+  /** Whether this VM was ever terminated (STATE-11). */
+  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. */
+  endpoint(): Promise<string | null>
+  /**
+   * The image ARN `run` sent in `RunMicrovm`: the caller's identifier with a bare name
+   * resolved, or the built image's.
+   *
+   * Recorded before the call, so a launch the service refused still names the image it
+   * asked for. `null` until `run` has resolved an image, and on an adopted sandbox.
+   */
+  launchImageArn(): Promise<string | null>
+  /**
+   * Why the VM is in its current state, when the service said.
+   *
+   * The absence is information: TRAP-8's message distinguishes "no stateReason" from an
+   * empty one.
+   */
+  stateReason(): Promise<string | null>
+  /** The image, once built. */
+  image(): Promise<Image | null>
+  /**
+   * The suspended window this sandbox asked for at launch, in seconds.
+   *
+   * `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>
+  /**
+   * 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.
+   *
+   * A new wrapper each call, all reaching the same session under the same lock. There is no
+   * cached instance: caching one would mean a session object that outlives the VM it
+   * addresses, and the indirection exists precisely so a post-terminate call reports the
+   * lifecycle rather than a dangling handle.
+   */
+  session(): Promise<Session | null>
+  /**
+   * Builds an image and waits for it to become usable.
+   *
+   * Every local guard runs **before** the call, which matters because the create happens
+   * 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 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>
+  /**
+   * 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 and resolves with its session. By default it waits for RUNNING
+   * and for the daemon to answer; `wait: false` skips those readiness waits.
+   *
+   * `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
+   *
+   * A second `run` on one sandbox, with **zero** control-plane calls: the agent token is
+   * installed at most once per VM lifetime (STATE-3), and a second VM needs a second
+   * `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 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
+   * `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.
+   *
+   * A freeze and restore rather than a stop and start: the guest keeps its memory, so the
+   * token, the filesystem, and every exec record survive. The one thing that does not is
+   * the guest's view of time — it observes the whole suspension as a single jump, so any
+   * timeout, lease, or TLS session a running command holds expires at once on resume.
+   *
+   * A suspend from anything but RUNNING is refused by the core with zero control-plane
+   * calls (STATE-5). Resolves with the state reached, which may be `"TERMINATED"`: a VM
+   * that dies while suspending is a state to report rather than an error thrown out of the
+   * middle of a teardown.
+   */
+  suspend(): Promise<string>
+  /**
+   * Thaws the VM and resolves with a usable session.
+   *
+   * # What the core refuses, before any wire call
+   *
+   * A resume after `terminate` (STATE-11) — a terminated VM never returns to RUNNING, and
+   * even a call the service accepted would hand back a different machine. A resume from
+   * anything but SUSPENDED (STATE-7). And a resume past the launch-time suspended window
+   * (STATE-12), which is the one worth knowing about: the `idlePolicy` terminates a
+   * suspended VM once that window passes, so there is nothing left to resume, and calling
+   * would cost the full poll timeout to learn something worse.
+   *
+   * Nothing is re-delivered: no run-hook payload, no token, no bootstrap. The in-memory
+   * token survived the freeze, and re-delivering it would hit the daemon's one-shot
+   * bootstrap and be refused — a 409 that reads like a broken VM.
+   */
+  resume(): Promise<Session>
+  /**
+   * Tears down, best-effort, **never rejecting**.
+   *
+   * Order: VM, then image, then the log group last, because the service can recreate a
+   * group deleted before its image.
+   */
+  terminate(options?: TeardownOptions | undefined | null): Promise<TeardownReport>
+}
+
+/** One running MicroVM's control API, with the proxy auth handled for you. */
+export declare class Session {
+  /**
+   * A session against a daemon reached **directly**, with no proxy headers.
+   *
+   * The shape for a local binary, a test server, or a VM reached over a tunnel. There is
+   * deliberately no constructor that takes a proxy token: minting one is the control
+   * plane's job and it happens inside every request (TRAP-9), so a caller handing a token
+   * 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.
+   *
+   * Connection errors on the way are expected rather than exceptional: a VM that has just
+   * reached RUNNING commonly refuses a connection or two before the proxy path is wired
+   * up. A *fatal* error ends the wait at once, because retrying a 401 until the deadline
+   * is the mistake the retryable split exists to prevent.
+   */
+  waitUntilReady(timeout?: number | undefined | null): Promise<Health>
+  /** Starts a command and returns its handle. Does not wait. */
+  run(command: string | Array<string>, options?: ExecOptions | undefined | null): Promise<ExecHandle>
+  /**
+   * Starts a command and returns it as two byte streams, a `wait()`, and a `kill()`.
+   *
+   * The **process** shape, as against [`Self::run`]'s handle shape. Same start request and
+   * the same `ExecOptions` (`cwd`, `env`, `user`, `group`, `shell`, `execId`, `timeoutSec`
+   * all apply), so this is a different view of one exec rather than a different exec:
+   * `spawn` and `run` with the same `execId` address the same server-side child, and the
+   * daemon starts one.
+   *
+   * `stdout` and `stderr` come out as independent `ReadableStream<Uint8Array>`, which is
+   * deliberately the AI SDK harness's `SandboxProcess` shape — see [`crate::process`] for
+   * what that compatibility is and is not, for how one interleaved SSE channel becomes two
+   * streams, and for why an evicted byte range errors the streams by default instead of
+   * being reported out-of-band.
+   *
+   * The reconnect-at-cursor behaviour is unchanged from `stream()`: a stream cut by a
+   * suspend/resume rejoins at the byte offset rather than ending, so a suspend does not look
+   * like a clean exit.
+   */
+  spawn(command: string | Array<string>, options?: SpawnOptions | undefined | null): Promise<ExecProcess>
+  /**
+   * A handle for an exec started earlier, possibly by another process.
+   *
+   * The reattach path. Nothing is checked against the daemon here — the handle is an id
+   * plus a transport, and a poll is what discovers whether the exec exists.
+   */
+  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>
+  /**
+   * Process accounting: every registered exec with its group's live pids.
+   *
+   * The daemon reads `/proc` itself, so this needs no `ps` in the guest. A `ProcGroup` with
+   * `childExited` and a non-empty `pids` is a command that finished while something it
+   * backgrounded did not; pass its `execId` to `kill`.
+   */
+  procs(): Promise<Array<ProcGroup>>
+  /**
+   * Writes one file, creating parents. `mode` is an **octal string** (`"0755"`), which is
+   * the daemon's shape — a number here would be ambiguous between 0o755 and 755.
+   */
+  uploadFile(path: string, data: Uint8Array, mode?: string | undefined | null): Promise<void>
+  /**
+   * 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>
+  /**
+   * Extracts pre-built tar bytes under `remote`.
+   *
+   * Bytes rather than a local path: packing a directory is the caller's, because the
+   * symlink and permission decisions in a pack belong to whoever knows what the tree
+   * means.
+   */
+  uploadTar(remote: string, archive: Uint8Array): Promise<void>
+  /** The raw tar bytes of a remote tree. */
+  downloadTar(remote: string): Promise<Buffer>
+  /**
+   * Both proxy headers for `port`, so a caller can open its **own** connection.
+   *
+   * The `{ url, headers }` shape a provider's `getPortEndpoint` answers with: pair these
+   * with `endpoint()` and nothing outside this addon has to know how a proxy token is
+   * minted or when it refreshes. Minted through the session's existing cache, so calling
+   * this does not burn a second control-plane call and does not open a second TRAP-9
+   * schedule.
+   *
+   * A plain `Record<string, string>` rather than a class, and that is the one place this
+   * crate's own "never `#[napi(object)]` for anything carrying a closure" rule does not
+   * apply: there is no closure here to protect. The value is a **bearer credential**, and
+   * unlike the token itself it necessarily comes out as a string — a header a caller has to
+   * put on a request cannot be opaque. What is still closed is the other direction: no
+   * function in this addon *takes* a header map, so a caller cannot feed a forged or expired
+   * one back in.
+   *
+   * **Empty for a direct session**, which is the true answer rather than a missing one: a
+   * daemon reached directly takes no proxy headers, so an empty object is exactly what its
+   * requests carry.
+   */
+  connectHeaders(port: number): Promise<Record<string, string>>
+  /**
+   * The three WebSocket subprotocols for `port`, in the order a handshake offers them.
+   *
+   * `new WebSocket(url, await session.connectSubprotocols(port))` is the whole use. A
+   * MicroVM endpoint takes the auth and the target port as `Sec-WebSocket-Protocol` values
+   * rather than as headers, because the browser `WebSocket` constructor cannot set a header
+   * — and the platform strips all three before forwarding, so a server inside the VM never
+   * negotiates them and must not be written to expect them.
+   *
+   * `null` for a direct session, and deliberately not an empty array: the subprotocol form
+   * exists only for a request through the endpoint proxy, so there is nothing for a
+   * directly-reached daemon to offer. Answering `["lambda-microvms"]` with no token would
+   * open a handshake refused for a reason naming neither the token nor the port.
+   *
+   * 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.
+   *
+   * Exposed because it is the only observable that distinguishes a client which re-minted
+   * after a resume from one that kept a stale token (STATE-8). The **token itself** is not
+   * exposed and cannot be: the core's `ProxyToken` has no `Display`, no `as_str`, and no
+   * `Deref`, so "treat `authToken` as a string" is as inexpressible here as it is there
+   * (TRAP-7).
+   */
+  proxyMintCount(): Promise<number | null>
+}
+
+/**
+ * One of the five documented size classes.
+ *
+ * `minimumMemoryInMiB` selects a class; it does not size a VM. Both numbers are on the
+ * class or neither.
+ */
+export declare class SizeClass {
+  /**
+   * The class `minimumMemoryInMiB = mib` selects, or a refusal (TRAP-10).
+   *
+   * Off-table figures are refused rather than snapped to a neighbour: the two plausible
+   * 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
+   * guest has no swap.
+   */
+  static defaultClass(): SizeClass
+  /** Every class, smallest first. */
+  static all(): Array<SizeClass>
+  get baselineMib(): number
+  get baselineVcpu(): number
+  get peakMib(): number
+  get peakVcpu(): number
+  /** The figure a GB-second rate multiplies. Always the baseline, never the peak. */
+  get baselineGb(): number
+  /** The peak in GB, which is what the guest reports as `MemTotal`. */
+  get peakGb(): number
+  /** One line naming both numbers. */
+  describe(): string
+}
+
+/**
+ * A report's total, which is a lower bound whenever anything is unpriced.
+ *
+ * The floor is under a name that says what it is — never `total`. A caller reading a field
+ * called `total` would have no reason to check `isLowerBound`.
+ */
+export declare class Total {
+  /** Everything that could be priced. For a lower bound this is **not** the total. */
+  get floor(): EstimatedUsd
+  /** True when line items with no published rate are missing from the floor. */
+  get isLowerBound(): boolean
+  /** Why each unpriced line could not be priced, in report order. */
+  get unpricedReasons(): Array<string>
+  /** `at least ~$X (estimated), plus N unpriced (...)`. */
+  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.
+ *
+ * A distinct class from [`EstimatedUsd`], not `EstimatedUsd("0")`: zero is a claim about
+ * the bill, unpriced is a claim about the documentation.
+ */
+export declare class Unpriced {
+  get reason(): string
+  toString(): string
+}
+
+/** 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. */
+  binary: Uint8Array
+  /** The build role, which must grant logs on `/aws/lambda-microvms/*`. */
+  buildRoleArn: string
+  /**
+   * Where `buildArtifact`'s bytes were uploaded. Required by `buildImage`, ignored by the
+   * name and artifact calls.
+   */
+  codeArtifactUri?: string
+}
+
+/** Everything a launch takes beyond what the layer fixes (egress on, the image). */
+export interface AgentLaunchOptions {
+  /**
+   * 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
+  /** 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
+  /** 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. */
+export interface AgentSpec {
+  /** `"claude-code"` or `"codex"`. */
+  agent: string
+  /** The model this spec resolves to: the override, or the profile's default. */
+  model: string
+  /** The pinned CLI version, or `null` for the registry's latest at build time. */
+  cliVersion?: string
+  /** The exact command `prompt` runs, with `<TASK>` where the quoted task goes. */
+  headlessCommand: string
+}
+
+/**
+ * One agent to install: its name, and the two defaults a caller may override.
+ *
+ * `agent` is `"claude-code"` or `"codex"`; anything else is refused by the core with the
+ * list. `model` defaults to the profile's row (an inference-profile id), `cliVersion` to the
+ * registry's latest at build time; a pin changes the image name.
+ */
+export interface AgentSpecInput {
+  agent: string
+  model?: string
+  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.
+ *
+ * One value rather than two loose strings, because the two **must** agree and used to be able
+ * to disagree: the Python client's default named the managed base for `baseImageArn` while
+ * its Dockerfile hardcoded an unrelated registry literal in its `FROM`, so changing either
+ * left the other pointing somewhere else.
+ *
+ * `#[napi(object)]` is acceptable here where it is not for a guarded type: the pairing is the
+ * point and both halves are required fields, so a structurally-valid object is a valid
+ * pairing. `workingDir` is what `docker inspect` reports for `WorkingDir`, and empty means
+ * the image declares none — a field because a caller with a purpose-built image is the only
+ * one who can say what theirs declares.
+ */
+export interface BaseImageInput {
+  name: string
+  dockerRef: string
+  workingDir?: string
+}
+
+/**
+ * Everything `CreateMicrovmImage` needs.
+ *
+ * # What is deliberately not a field
+ *
+ * A `clientToken`. There is no such field on the core's request type and none here: a
+ * digest-derived token replays the original create and wedges an image in `CREATING` for
+ * fifteen hours with no error at all (TRAP-1). `tokenScope` is a CloudTrail **label** folded
+ * in beside a fresh nonce and cannot become the token.
+ *
+ * A `capabilities` list. `repairGuestIdentity` is a boolean and the request injects `["ALL"]`
+ * itself, so `["CAP_SYS_ADMIN"]` — the request AWS rejects after the artifact upload — is not
+ * something a caller can write (TRAP-3).
+ *
+ * An `architecture`. The model's enum has exactly one value, so the only thing a field could
+ * express is a rejected request.
+ */
+export interface BuildImageOptions {
+  name: string
+  /** The daemon binary's bytes, zipped into the artifact. */
+  binary: Uint8Array
+  /**
+   * 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
+  /**
+   * Whether the daemon should inherit the image's `WORKDIR`. Refused when nothing declares
+   * one, because the inheritance would silently resolve to `/`.
+   */
+  inheritWorkdir?: boolean
+  tags?: Record<string, string>
+  /**
+   * `logging.cloudWatch.logGroup`, or absent for the service default (a service-created
+   * group under `/aws/lambda-microvms/<image-name>` with random stream names). The
+   * build role must grant logs on whatever this names.
+   */
+  logGroup?: string
+  /**
+   * A log-stream name **prefix** inside `logGroup`, never the exact name: the platform
+   * member is an exact stream name (prefixes unsupported) and one build is three VMs
+   * writing three streams, so the client appends `/<16 hex>` per build attempt and the
+   * resolved name comes back on `Image.logStream`. Requires `logGroup`.
+   */
+  logStream?: string
+  /** A CloudTrail-readability **label**, defaulting to the image name. Not the token. */
+  tokenScope?: string
+}
+
+/** 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.
+ *
+ * Leave `cycles` out and the comparison prices one suspend/resume cycle, the core's default
+ * and the one `microvm cost --compare` applies: the per-cycle figure is what keeps the
+ * argument honest. A report's `suspendResumeCycles` defaults to none instead.
+ */
+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.
+ *
+ * The **core's** version and not this crate's: what a caller needs to know is which client
+ * they are talking through, and a binding version that drifted from it would be a second
+ * number nobody can act on.
+ */
+export declare function coreVersion(): string
+
+/**
+ * The documented cost constants, as a JSON string a caller can assert against.
+ *
+ * A JSON string rather than a typed object because it is a transcription of published
+ * facts whose shape may grow, and a `#[napi(object)]` would make every addition a
+ * signature change.
+ */
+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.
+ *
+ * Enumerated from the core's own `ErrorKind::ALL` rather than transcribed, so a kind added
+ * there appears here without an edit — a hand-written list would agree with a typo.
+ */
+export declare function errorCodes(): Array<string>
+
+/**
+ * What a plan will cost, before spending anything (COST-10).
+ *
+ * Takes plain seconds and marks every one projected. That is the difference from
+ * [`run_report`]: not the arithmetic, which is shared, but what the durations admit about
+ * themselves.
+ */
+export declare function estimateRun(size: SizeClass, options?: PlanUsageOptions | undefined | null, rates?: RateTable | undefined | null): CostReport
+
+/** How an exec should be started. Every field optional; the defaults are the daemon's. */
+export interface ExecOptions {
+  /**
+   * `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>
+  /**
+   * 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. */
+  stdin?: boolean
+  /**
+   * The idempotency key. Omitted, one is minted; supplied, the daemon returns success for
+   * a known id without spawning a second child — so a caller whose retry must be safe
+   * across its own restart passes a stable one.
+   */
+  execId?: string
+  /** The client-side deadline for `runSync` only. */
+  timeout?: number
+  /**
+   * Signal the whole process group once the command's own child exits, so nothing it
+   * backgrounded outlives it. Off by default, which keeps the backgrounded-grandchild-output
+   * guarantee for callers who rely on it.
+   */
+  reapGroupOnExit?: boolean
+  /**
+   * 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
+}
+
+/**
+ * An exec's phase and, once it has one, its outcome.
+ *
+ * `#[napi(object)]` is right for this one: it is a pure result with no closure to protect
+ * — there is no `ExecResult` a caller can construct wrongly, because no function takes one
+ * — so a plain JS object with named fields is the friendlier shape and gives up nothing.
+ */
+export interface ExecResult {
+  execId: string
+  /** `"running"`, `"exited"`, or `"acked"`. */
+  phase: string
+  /** `null` when the child died to a signal rather than exiting. */
+  exitCode?: number
+  /** The signal that killed the child, when one did. */
+  signal?: number
+  stdout: string
+  stderr: string
+  /**
+   * Set when either stream hit the output cap and was cut. A flag rather than a sentinel
+   * 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.
+   */
+  writersMayBeAlive: boolean
+  /** Whether the exec has finished, whichever way. */
+  done: boolean
+  /**
+   * Whether the command exited zero. False for a signal death and for a still-running
+   * 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
+}
+
+/**
+ * What to do when the daemon reports evicted output.
+ *
+ * A string union rather than an enum class, because napi renders `#[napi(string_enum)]` as a
+ * TypeScript union of literals — `'error' | 'event'`, which is what a JS caller writes anyway
+ * — and there is no closure here to protect (see `lib.rs` on when a class is required
+ * instead).
+ */
+export declare const enum GapPolicy {
+  /**
+   * **The default.** A gap errors both streams, with the lost range in the message. See the
+   * module docs for why an error rather than an ignorable event.
+   */
+  Error = 'error',
+  /**
+   * A gap is recorded on [`ExecProcess::gaps`] and both streams stay open.
+   *
+   * For a caller that wants the surviving bytes more than the completeness guarantee. The
+   * consumer is then responsible for reading `gaps`, and nothing forces it to.
+   */
+  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. */
+  version: string
+  /** Whether the run hook has landed and the control API is open. */
+  bootstrapped: boolean
+  /**
+   * Bytes available to an unprivileged writer, or `null` when free space could not be
+   * measured.
+   *
+   * `null` is deliberately distinct from zero: unmeasurable is not full, and a monitor
+   * that conflated them would page on a missing `statvfs`.
+   */
+  availableBytes?: number
+  /** Bytes that must stay free before a write is refused. Zero means the guard is off. */
+  reserveBytes?: number
+  /**
+   * Whether a write would be refused right now. Precomputed by the daemon so every
+   * consumer applies the same comparison the write path does.
+   */
+  underPressure?: boolean
+  /**
+   * Whether any startup identity repair step failed — a duplicate machine-id or boot_id
+   * still in place from the shared image.
+   */
+  identityDegraded: boolean
+  /**
+   * False when identity repair was switched off by config. Separate from `degraded` so a
+   * monitor can tell "opted out" from "nothing to do".
+   */
+  identityRepaired: boolean
+  /**
+   * Whether any exec is still running.
+   *
+   * For an orchestrator *outside* the VM deciding whether to keep it alive. The platform
+   * measures idleness by inbound traffic through the endpoint proxy, which terminates
+   * outside the guest, so an in-guest keepalive cannot reset the idle timer — polling this
+   * from outside is both the traffic and the decision. An exec that exited and is awaiting
+   * an ack is not busy.
+   */
+  busy: boolean
+  /**
+   * How many execs are registered, in any phase. `busy: false` with a non-zero count is a
+   * 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. */
+export interface Image {
+  /** The image ARN, which is what `imageIdentifier` takes. */
+  identifier: string
+  name: string
+  version: string
+  state: string
+  /**
+   * The baseline MiB of the class the request selected.
+   *
+   * Carried because billing follows the baseline requested at *create* time, and by the
+   * time anyone asks what a run cost the request is gone.
+   */
+  baselineMib: number
+  /**
+   * `/aws/lambda-microvms/<image-name>`.
+   *
+   * The service creates this itself, so no Terraform stack owns it and `terraform destroy`
+   * leaves it behind — "the stack destroyed cleanly" is not "the account is clean". Six
+   * accumulated before anyone noticed.
+   */
+  buildLogGroup: string
+  /**
+   * The resolved exact log stream this build's logs went to, when `logStream` was
+   * configured — the configured prefix plus the per-build `/<16 hex>` discriminator the
+   * client appends. `null` for an unconfigured build (the service names the streams).
+   *
+   * The only copy of the resolved name: the discriminator is minted fresh inside the
+   * create call, so a caller reads it here or never.
+   */
+  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`.
+ *
+ * Three uploads (the environment file, Codex's config when Codex is among the agents, the
+ * marker) and one root `chown` of `/workspace` to uid 1000. Re-runnable: a fresh token
+ * overwrites the same files, which is how a twelve-hour token is refreshed.
+ */
+export declare function installAgentAccess(session: Session, agents: Array<AgentSpecInput>, token: BearerToken): Promise<void>
+
+/**
+ * The agents a running VM was provisioned with, read from its guest marker.
+ *
+ * For a process holding only a session (`Session.direct` from the identifier triple): how a
+ * credential refresh learns which agents and models to re-provision. A VM with no marker is
+ * refused as a precondition, naming `agent-up`.
+ */
+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. */
+  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
+  /**
+   * 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. */
+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
+}
+
+/**
+ * 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
+  /** 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.
+ *
+ * A SigV4 presign of `POST https://bedrock.amazonaws.com/?Action=CallWithBearerToken`,
+ * base64, prefixed `bedrock-api-key-` — the reference generator's recipe, in process.
+ * `ttlSeconds` defaults to the ceiling, twelve hours; more is refused by the core.
+ */
+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.
+ *
+ * `from` inclusive, `to` exclusive — so `to` is exactly the offset a resume would pass.
+ */
+export interface OutputGap {
+  /**
+   * Which stream lost bytes: `"stdout"` or `"stderr"`.
+   *
+   * Read off the *following* output frame rather than from the gap frame, which carries no
+   * discriminator: the wire's offset space is shared, so a gap is a hole in the combined
+   * stream and the daemon cannot say which side's bytes were in it. `null` when the gap was
+   * the last thing on the stream and nothing followed it to attribute it to.
+   */
+  stream?: string
+  from: number
+  to: number
+}
+
+/**
+ * A plan's phases, in plain seconds, before anything is spent.
+ *
+ * Separate from [`RunUsageOptions`] on purpose (COST-10): every field is a number, so there
+ * is no field an accidentally-measured duration could be written into. The wrapping into
+ * projected durations happens in the core, in one place.
+ */
+export interface PlanUsageOptions {
+  runningSeconds?: number
+  suspendedSeconds?: number
+  imageGb?: number
+  imageRetainedSeconds?: number
+  /**
+   * Each cycle pays a snapshot write plus a read. Left out, the plan counts none, as
+   * `microvm cost --estimate` does.
+   */
+  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.
+ *
+ * `exitCode` and nothing else on purpose, matching the harness contract's
+ * `wait(): PromiseLike<{ exitCode: number }>`. A caller wanting the signal, the truncation
+ * flag, or the buffered output polls [`crate::exec::ExecHandle`] instead, which answers with
+ * the whole record.
+ */
+export interface ProcessExit {
+  /**
+   * The child's exit status.
+   *
+   * **`null` when the child died to a signal**, which is where this shape and the harness's
+   * `{ exitCode: number }` genuinely differ, and it is deliberate. A signal death has no
+   * exit code, and the two available lies are `0` (a killed build reported as passing) and
+   * `128 + signo` (a number the daemon never published, indistinguishable from a child that
+   * really exited with it). A wrapper that must produce a number can pick one at its own
+   * boundary; this handle will not pick for it.
+   */
+  exitCode?: number
+  /**
+   * The signal that killed the child, when one did. Not part of the harness shape; here
+   * because it is the only thing that makes a `null` exit code actionable.
+   */
+  signal?: number
+  /** True when the remote execution deadline expired. */
+  timedOut: boolean
+}
+
+/**
+ * One exec's process group, as `GET /v1/procs` reports it.
+ *
+ * `childExited` beside a non-empty `pids` is the shape worth reading: a command that finished
+ * while something it backgrounded did not, which `Health.busy` cannot show. The `execId`
+ * beside it is what `Session.kill` takes.
+ */
+export interface ProcGroup {
+  /** The exec this group belongs to — what `kill` takes. */
+  execId: string
+  /**
+   * The process group id captured at spawn, or `null` when the child was reaped before it
+   * could be read (then `pids` is empty: there is no group to scan for).
+   */
+  pgid?: number
+  /** Seconds since the epoch on the daemon's clock when the child was spawned. */
+  startedAt: number
+  /** Whether the exec's own child has exited. An acked exec still reads `true`. */
+  childExited: boolean
+  /** Whether the exec was started with `reapGroupOnExit`. */
+  reap: boolean
+  /**
+   * Live pids whose process group is `pgid`, read from `/proc` inside the guest. Zombies
+   * are not listed. Empty once the group is gone.
+   */
+  pids: Array<number>
+}
+
+/** Starts one task for `agent` over `session` and resolves with its handle. Does not wait. */
+export declare function promptAgent(session: Session, agent: AgentSpecInput, task: string, options?: PromptOptions | undefined | null): Promise<ExecHandle>
+
+/** The knobs on one prompt. */
+export interface PromptOptions {
+  /** A daemon-side wall-clock budget for the agent process, in seconds. */
+  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 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, 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.
+   *
+   * Pinning is what makes a canary launch against the version it means to test rather than
+   * against whatever became latest while it was starting, and it is the half of a rollback
+   * that re-points at the known-good build. A version the control plane has set INACTIVE
+   * refuses to launch when named here.
+   */
+  imageVersion?: string
+  /** The execution role. Optional in the model; every real launch needs one. */
+  executionRoleArn?: string
+  /**
+   * The bearer token the daemon will accept, or omitted to mint one.
+   *
+   * Optional because the common case is a per-VM secret nobody needs to see; a caller who
+   * has one already — a harness minting its own, or a retry that must reuse the first
+   * attempt's — passes it. It rides in `runHookPayload`, which is what keeps it out of the
+   * 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.
+   *
+   * Applied *under* each exec's own `env`, so a per-exec value wins on a shared key.
+   * Shares the token's 4096-byte payload budget; the core refuses an over-ceiling
+   * 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
+  /**
+   * Existing VPC network connector ARNs. For no egress, use a VPC without an
+   * internet gateway or NAT gateway. Cannot be combined with `egress: true`.
+   */
+  egressNetworkConnectors?: Array<string>
+  /**
+   * Set advisory HTTP proxy variables. Workloads can ignore or override them;
+   * use a VPC without an internet gateway or NAT gateway for no egress.
+   */
+  denyEgress?: boolean
+  /**
+   * Whether to launch shell-capable: the ingress set becomes the measured pair
+   * `[HTTP_INGRESS, SHELL_INGRESS]`, which is what `microvm shell` attaches to.
+   */
+  shell?: boolean
+  maxIdleSec?: number
+  /** Requested suspended window, in seconds; the service also reports its idle policy. */
+  suspendedSec?: number
+  autoResume?: boolean
+  maxDurationSec?: number
+  /**
+   * 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 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. */
+  logGroup?: string
+  /** An exact log stream inside `logGroup`. */
+  logStream?: string
+  /** Turns per-VM logging off. Cannot be combined with `logGroup` or `logStream`. */
+  disableLogging?: boolean
+}
+
+/**
+ * Per-phase attribution for one sandbox's lifecycle.
+ *
+ * Every duration is a [`Duration`] class and not a number, which is what keeps the
+ * provenance label attached: taking seconds here would need this function to pick a
+ * provenance, and the one it would pick is the stronger claim.
+ */
+export declare function runReport(size: SizeClass, options?: RunUsageOptions | undefined | null, rates?: RateTable | undefined | null): CostReport
+
+/**
+ * Everything a measured report attributes cost to.
+ *
+ * `#[napi(object)]` **is** right here, unlike for the guarded types: this is an options bag
+ * a caller writes as a literal, and every field that carries a closure is a
+ * `ClassInstance<Duration>` rather than a number — so the object shape still cannot express
+ * an unlabelled duration. `ClassInstance` is what makes that hold: it extracts only from a
+ * real `Duration` instance, so `{ running: 3600 }` and `{ running: { seconds: 3600 } }` are
+ * both rejected by napi's conversion before any Rust runs. What the object buys is optional
+ * fields with JS's own `undefined`, which is how "this phase did not happen" is said.
+ */
+export interface RunUsageOptions {
+  /**
+   * Wall-clock time in RUNNING. Bills at baseline whether or not anything is executing —
+   * there is no free I/O wait, which is why suspension rather than idleness is the lever.
+   */
+  running?: Duration
+  /** Time held suspended. Pays storage only: a suspended VM is frozen. */
+  suspended?: Duration
+  /** How long the image build took, if it was timed. Always unpriced. */
+  imageBuild?: Duration
+  /**
+   * The image's size. Passing this adds both an image-storage line *and* the unpriced
+   * build line, so a create-and-destroy report is never complete.
+   */
+  imageGb?: number
+  /**
+   * How long the image was retained. Defaults to the documented one-week minimum, marked
+   * projected — nobody timed that week either.
+   */
+  imageRetained?: Duration
+  /**
+   * Each cycle pays a snapshot write plus a read. Left out, the report counts none, so it has
+   * no suspend or resume line: a report claims only what the caller says happened, as
+   * `microvm cost` does.
+   */
+  suspendResumeCycles?: number
+  /** The suspend snapshot's size. Defaults to the baseline memory footprint. */
+  snapshotGb?: number
+  /**
+   * 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.
+ */
+export declare function sessionConstants(): string
+
+/**
+ * How a `spawn` should behave: the exec's own options, plus the stream's.
+ *
+ * Nested rather than flattened onto [`ExecOptions`], and the reason is that the two sets are
+ * answered by different people. `cwd`/`env`/`user` describe the *child* and are what a caller
+ * composing a command supplies; `offset`/`reconnect`/`gapPolicy` describe how this client
+ * reads the child's output and are what a caller composing a *resume* supplies. Flattening
+ * them would put `maxReconnects` next to `user` in one bag, which is where a caller reaches
+ * for the wrong one.
+ */
+export interface SpawnOptions {
+  /**
+   * How to start the child. Identical to `run`'s options, deliberately: `spawn` is a
+   * different view of one exec rather than a different exec.
+   */
+  exec?: ExecOptions
+  /**
+   * The byte to start reading at. Non-zero resumes output a previous process was reading —
+   * which, with a stable `exec.execId`, is how a spawned process survives *this* process
+   * restarting.
+   */
+  offset?: number
+  /**
+   * Whether to reconnect after a cut. Defaults to true, and turning it off is what makes a
+   * suspend/resume look like a stream that ended.
+   */
+  reconnect?: boolean
+  /** How many reconnects before the streams error. A bound rather than forever. */
+  maxReconnects?: number
+  /** How long the body may be silent before the connection is treated as dead, in seconds. */
+  idleTimeout?: number
+  /**
+   * What to do when the daemon reports evicted output. Defaults to `'error'`; see
+   * [`crate::process`] for why.
+   */
+  gapPolicy?: GapPolicy
+}
+
+/** What a stdin write accomplished. */
+export interface StdinAck {
+  execId: string
+  written: number
+  eof: boolean
+}
+
+/**
+ * One event off an exec's output stream.
+ *
+ * One object with a `kind` discriminant rather than three classes, because JS has no
+ * `instanceof` over a union a caller can `switch` on cleanly and the TypeScript idiom is a
+ * tagged union. `kind` is `"output"`, `"gap"`, or `"exit"`, and the fields for the other
+ * two shapes are `null` — which keeps [`Self::exit_code`] distinguishable from an output
+ * chunk that happens to be last. The absence of an `exit` event is what tells a cut
+ * connection from a finished command; the byte sequences are otherwise identical.
+ */
+export interface StreamEvent {
+  /** `"output"`, `"gap"`, or `"exit"`. */
+  kind: string
+  /**
+   * `"stdout"` or `"stderr"`, for an output event. Both share one offset space, so a
+   * caller holds one cursor rather than two that can disagree about ordering.
+   */
+  stream?: string
+  /** Where an output chunk starts, or where a gap starts. */
+  offset?: number
+  /**
+   * One past an output chunk's last byte, or a gap's exclusive end — either way, where a
+   * cursor resumes. `null` on an exit event, whose offset is a *total* rather than a
+   * position, so resuming from it would ask the daemon to replay from the end.
+   */
+  end?: number
+  /** The bytes, for an output event. */
+  data?: Buffer
+  /** The bytes as text, replacing anything undecodable. `data` is the lossless form. */
+  text?: string
+  /** Total bytes published, on an exit event. */
+  totalOffset?: number
+  exitCode?: number
+  signal?: number
+  truncated?: boolean
+  /** Present on exit: whether the remote execution deadline expired. */
+  timedOut?: boolean
+  writersMayBeAlive?: boolean
+}
+
+/** How a stream should behave. */
+export interface StreamOptionsInput {
+  /** The byte to start at. Non-zero resumes a stream a previous process was reading. */
+  offset?: number
+  /**
+   * Whether to reconnect after a cut. `false` ends the stream at the cut instead, which
+   * is what a caller doing its own reconnection wants.
+   */
+  reconnect?: boolean
+  /**
+   * How many reconnects before giving up. A bound rather than forever, because a stream
+   * that drops every time is a condition a caller needs reported.
+   */
+  maxReconnects?: number
+  /**
+   * Turns a gap into a rejection instead of an event. What a caller that must have
+   * complete output wants.
+   */
+  errorOnGap?: boolean
+  /** How long the body may be silent before the connection is treated as dead. */
+  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.
+ *
+ * Both deletions are opt-in, because both destroy something a caller may still want: the
+ * image is reusable across runs, and the log group is where a failed build's only evidence
+ * lives.
+ */
+export interface TeardownOptions {
+  deleteImage?: boolean
+  /**
+   * **Names** the group in `report.undeleted` rather than deleting it — CloudWatch is not
+   * in the core's dependency set, and reporting a leak beats reporting a clean teardown
+   * over one.
+   */
+  deleteLogGroup?: boolean
+  deleteAttempts?: number
+  deleteBackoff?: number
+  /**
+   * `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"`. `true` waits for TERMINATED up to the core's lifecycle default;
+   * a number of seconds waits up to that instead.
+   */
+  waitForTerminated?: boolean | number
+}
+
+/** What a teardown did, and what it left behind. */
+export interface TeardownReport {
+  /**
+   * Identifiers of everything a caller asked to have deleted that still exists.
+   *
+   * Identifiers rather than a boolean, because a leak nobody can name is a leak nobody can
+   * clean up. Two things land here: a delete that was attempted and failed, and the build
+   * **log group**, which this client cannot delete at all.
+   */
+  undeleted: Array<string>
+  /** Whether the terminate call was accepted. */
+  terminateAccepted: boolean
+  /** Whether the image was deleted, or `null` when deletion was not asked for. */
+  imageDeleted?: boolean
+  /**
+   * The lifecycle state the sandbox ended in.
+   *
+   * Commonly `"TERMINATING"` rather than `"TERMINATED"`: the default teardown does not
+   * wait, so claiming TERMINATED would claim an observation nobody made. Pass
+   * `waitForTerminated: true` to observe it.
+   */
+  lifecycle?: string
+  /**
+   * Every failure the teardown swallowed, in the order it hit them.
+   *
+   * Kept because a teardown that never throws is a teardown whose failures are invisible
+   * otherwise, and the first one is usually the cause of the rest.
+   */
+  failures: Array<string>
+  /** Whether anything a caller asked for was left behind. */
+  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. */
+  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
+}