@theagenticguy/microvms 0.1.0-rc.1

package/index.d.ts

@@ -0,0 +1,1075 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * 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 timeout for the `ready` or `validate` image-build hook: 1..=3600 seconds. */
+export declare class BuildHookTimeout {
+  /** A build-family timeout, or a refusal naming both ceilings. */
+  constructor(seconds: number)
+  /** The service ceiling for this family: 3600. */
+  get maxSecs(): number
+  get seconds(): number
+  toString(): 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
+   * `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
+  /**
+   * The `cli.py:688 report_to_dict` shape as a JSON **string**.
+   *
+   * 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
+}
+
+/**
+ * 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 JS async iterator over an exec's output.
+ *
+ * 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 {
+
+}
+
+/** 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
+  /**
+   * The `cli.py` `_line_to_dict` shape 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
+}
+
+/** 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(): number
+  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>
+  /** The VM id, once launched. */
+  microvmId(): Promise<string | null>
+  /** The proxy endpoint, once launched. */
+  endpoint(): 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 a launch, and for a sandbox that did not send the launch — this client is
+   * the only party that can name the number, because `suspendedDurationSeconds` exists only
+   * in the `RunMicrovm` request.
+   */
+  suspendedWindowSecondsAsync(): Promise<number | 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>
+  /**
+   * The artifact bytes to upload to `codeArtifactUri`.
+   *
+   * The upload is the caller's: S3 is not in the core's dependency set. Takes the same
+   * options as [`Self::build_image`] so the bytes a caller puts in the bucket are the bytes
+   * the build will receive.
+   */
+  buildArtifact(options: BuildImageOptions, size?: SizeClass | undefined | null, runHookTimeout?: RunHookTimeout | undefined | null, buildHookTimeout?: BuildHookTimeout | undefined | null): Promise<Buffer>
+  /**
+   * Launches a MicroVM, waits for RUNNING, and resolves with its session.
+   *
+   * # 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>
+  /**
+   * 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
+  /** The endpoint this session addresses. */
+  endpoint(): Promise<string>
+  /** The port the proxy token is scoped to. */
+  port(): Promise<number>
+  /** Unauthenticated liveness. */
+  health(): Promise<Health>
+  /**
+   * 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>
+  /**
+   * 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>
+  /** Signals an exec's whole process group. Returns whether anything was signalled. */
+  kill(execId: string): Promise<boolean>
+  /**
+   * 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. */
+  downloadFile(path: string): Promise<Buffer>
+  /** 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>
+  /**
+   * 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 platform's default, 2048 MiB. Not the smallest — a 0.5 GB baseline hands someone
+   * a sandbox that 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 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 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. This client does not upload — S3 is not in the
+   * core's dependency set — so the caller puts the bytes there and passes the URI.
+   */
+  codeArtifactUri: string
+  /** The build role, which must grant logs on `/aws/lambda-microvms/*`. */
+  buildRoleArn: string
+  baseImage?: BaseImageInput
+  /** A caller-supplied Dockerfile, checked against the base image's `FROM`. */
+  dockerfile?: 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>
+  /** 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
+
+/** The warm-pool argument, with its own counter-argument attached. */
+export declare function compareResidency(size: SizeClass, holdSeconds: number, cycles?: number | undefined | null, rates?: RateTable | undefined | null): ResidencyComparison
+
+/**
+ * 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
+
+/**
+ * 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 {
+  /** A single script string rather than an argv. Requires `shell: true`. */
+  shell?: boolean
+  cwd?: string
+  env?: Record<string, string>
+  user?: number
+  group?: number
+  /** 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
+}
+
+/**
+ * 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
+  /**
+   * 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 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
+}
+
+/** 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
+}
+
+/**
+ * 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
+  suspendResumeCycles?: number
+  snapshotGb?: number
+  launched?: boolean
+  label?: string
+}
+
+/** Everything a launch needs. */
+export interface RunOptions {
+  /** The image to launch, or omitted for the one `buildImage` built. */
+  imageIdentifier?: 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
+  /** Whether to request the egress connector. Off means no outbound network. */
+  egress?: boolean
+  maxIdleSec?: number
+  /**
+   * The window a resume is refused past (STATE-12). Exists **only** in the launch request:
+   * `GetMicrovm` does not return it, so this client is the only party that can name it.
+   */
+  suspendedSec?: number
+  autoResume?: boolean
+  maxDurationSec?: number
+  /** How long to wait for RUNNING. */
+  readyTimeout?: number
+  /** A label for the run token. Never the token. */
+  tokenScope?: string
+}
+
+/**
+ * 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. */
+  suspendResumeCycles?: number
+  /** The suspend snapshot's size. Defaults to the baseline memory footprint. */
+  snapshotGb?: number
+  /** Whether a launch happened. A launch reads a snapshot. */
+  launched?: boolean
+  label?: string
+}
+
+/**
+ * The daemon's protocol constants, as a JSON string, for a caller asserting against the
+ * wire contract.
+ */
+export declare function sessionConstants(): string
+
+/** 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
+  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
+}
+
+/**
+ * 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"`.
+   */
+  waitForTerminated?: boolean
+}
+
+/** 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
+}
+
+/** Every daemon-status class, as `err.cause.cause.message` names them. */
+export declare function wireKinds(): Array<string>