@theagenticguy/microvms 0.1.0-rc.1 → 0.2.0

package/index.d.ts

@@ -173,6 +173,77 @@ export declare class ExecHandle {
   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.
  *
@@ -516,6 +587,26 @@ export declare class Session {
   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.
    *
@@ -546,6 +637,45 @@ export declare class Session {
   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>
   /**
    * How many proxy tokens this session has minted, or `null` for a direct session.
    *
@@ -784,6 +914,29 @@ export interface ExecResult {
   ok: 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'
+}
+
 /** The daemon's liveness answer. `bootstrapped` is the useful field. */
 export interface Health {
   /** The daemon's own version, distinct from the protocol version. */
@@ -815,6 +968,21 @@ export interface Health {
    * 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
 }
 
 /** A built image, and the log group the service created alongside it. */
@@ -841,6 +1009,25 @@ export interface Image {
   buildLogGroup: 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.
  *
@@ -859,10 +1046,46 @@ export interface PlanUsageOptions {
   label?: string
 }
 
+/**
+ * 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
+}
+
 /** Everything a launch needs. */
 export interface RunOptions {
   /** The image to launch, or omitted for the one `buildImage` built. */
   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
   /**
@@ -874,6 +1097,15 @@ export interface RunOptions {
    * shared image snapshot.
    */
   agentToken?: 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>
   /** Whether to request the egress connector. Off means no outbound network. */
   egress?: boolean
   maxIdleSec?: number
@@ -945,6 +1177,44 @@ export interface RunUsageOptions {
  */
 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

package/index.js

@@ -75,10 +75,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-android-arm64')
-        const bindingPackageVersion = require('microvms-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-android-arm64')
+        const bindingPackageVersion = require('@theagenticguy/microvms-android-arm64/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -91,10 +91,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-android-arm-eabi')
-        const bindingPackageVersion = require('microvms-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-android-arm-eabi')
+        const bindingPackageVersion = require('@theagenticguy/microvms-android-arm-eabi/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -112,10 +112,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-win32-x64-gnu')
-        const bindingPackageVersion = require('microvms-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-win32-x64-gnu')
+        const bindingPackageVersion = require('@theagenticguy/microvms-win32-x64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -128,10 +128,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-win32-x64-msvc')
-        const bindingPackageVersion = require('microvms-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-win32-x64-msvc')
+        const bindingPackageVersion = require('@theagenticguy/microvms-win32-x64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -145,10 +145,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-win32-ia32-msvc')
-        const bindingPackageVersion = require('microvms-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-win32-ia32-msvc')
+        const bindingPackageVersion = require('@theagenticguy/microvms-win32-ia32-msvc/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -161,10 +161,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-win32-arm64-msvc')
-        const bindingPackageVersion = require('microvms-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-win32-arm64-msvc')
+        const bindingPackageVersion = require('@theagenticguy/microvms-win32-arm64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -180,10 +180,10 @@ function requireNative() {
       loadErrors.push(e)
     }
     try {
-      const binding = require('microvms-darwin-universal')
-      const bindingPackageVersion = require('microvms-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      const binding = require('@theagenticguy/microvms-darwin-universal')
+      const bindingPackageVersion = require('@theagenticguy/microvms-darwin-universal/package.json').version
+      if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -196,10 +196,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-darwin-x64')
-        const bindingPackageVersion = require('microvms-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-darwin-x64')
+        const bindingPackageVersion = require('@theagenticguy/microvms-darwin-x64/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -212,10 +212,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-darwin-arm64')
-        const bindingPackageVersion = require('microvms-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-darwin-arm64')
+        const bindingPackageVersion = require('@theagenticguy/microvms-darwin-arm64/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -232,10 +232,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-freebsd-x64')
-        const bindingPackageVersion = require('microvms-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-freebsd-x64')
+        const bindingPackageVersion = require('@theagenticguy/microvms-freebsd-x64/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -248,10 +248,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-freebsd-arm64')
-        const bindingPackageVersion = require('microvms-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-freebsd-arm64')
+        const bindingPackageVersion = require('@theagenticguy/microvms-freebsd-arm64/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -269,10 +269,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-x64-musl')
-          const bindingPackageVersion = require('microvms-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-x64-musl')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-x64-musl/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -285,10 +285,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-x64-gnu')
-          const bindingPackageVersion = require('microvms-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-x64-gnu')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-x64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -303,10 +303,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-arm64-musl')
-          const bindingPackageVersion = require('microvms-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-arm64-musl')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm64-musl/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -319,10 +319,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-arm64-gnu')
-          const bindingPackageVersion = require('microvms-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-arm64-gnu')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -337,10 +337,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-arm-musleabihf')
-          const bindingPackageVersion = require('microvms-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-arm-musleabihf')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm-musleabihf/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -353,10 +353,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-arm-gnueabihf')
-          const bindingPackageVersion = require('microvms-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-arm-gnueabihf')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-arm-gnueabihf/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -371,10 +371,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-loong64-musl')
-          const bindingPackageVersion = require('microvms-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-loong64-musl')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-loong64-musl/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -387,10 +387,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-loong64-gnu')
-          const bindingPackageVersion = require('microvms-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-loong64-gnu')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-loong64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -405,10 +405,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-riscv64-musl')
-          const bindingPackageVersion = require('microvms-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-riscv64-musl')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-riscv64-musl/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -421,10 +421,10 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          const binding = require('microvms-linux-riscv64-gnu')
-          const bindingPackageVersion = require('microvms-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const binding = require('@theagenticguy/microvms-linux-riscv64-gnu')
+          const bindingPackageVersion = require('@theagenticguy/microvms-linux-riscv64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -438,10 +438,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-linux-ppc64-gnu')
-        const bindingPackageVersion = require('microvms-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-linux-ppc64-gnu')
+        const bindingPackageVersion = require('@theagenticguy/microvms-linux-ppc64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -454,10 +454,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-linux-s390x-gnu')
-        const bindingPackageVersion = require('microvms-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-linux-s390x-gnu')
+        const bindingPackageVersion = require('@theagenticguy/microvms-linux-s390x-gnu/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -474,10 +474,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-openharmony-arm64')
-        const bindingPackageVersion = require('microvms-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-openharmony-arm64')
+        const bindingPackageVersion = require('@theagenticguy/microvms-openharmony-arm64/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -490,10 +490,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-openharmony-x64')
-        const bindingPackageVersion = require('microvms-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-openharmony-x64')
+        const bindingPackageVersion = require('@theagenticguy/microvms-openharmony-x64/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -506,10 +506,10 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        const binding = require('microvms-openharmony-arm')
-        const bindingPackageVersion = require('microvms-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        const binding = require('@theagenticguy/microvms-openharmony-arm')
+        const bindingPackageVersion = require('@theagenticguy/microvms-openharmony-arm/package.json').version
+        if (bindingPackageVersion !== '0.2.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -643,16 +643,16 @@ if (!nativeBinding || forceWasi) {
     let candidateError = null
     let candidateFailed = false
     try {
-      candidateError = __napiWasiResolveCandidate('microvms-wasm32-wasi', true, undefined)
+      candidateError = __napiWasiResolveCandidate('@theagenticguy/microvms-wasm32-wasi', true, undefined)
       candidateFailed = candidateError !== null
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          const bindingPackageVersion = require('microvms-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '0.1.0') {
-            throw new Error(`WASI binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          const bindingPackageVersion = require('@theagenticguy/microvms-wasm32-wasi/package.json').version
+          if (bindingPackageVersion !== '0.2.0') {
+            throw new Error(`WASI binding package version mismatch, expected 0.2.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
-        wasiBinding = require('microvms-wasm32-wasi')
+        wasiBinding = require('@theagenticguy/microvms-wasm32-wasi')
         nativeBinding = wasiBinding
         wasiBindingLoaded = true
       }
@@ -706,6 +706,7 @@ module.exports.CostReport = nativeBinding.CostReport
 module.exports.Duration = nativeBinding.Duration
 module.exports.EstimatedUsd = nativeBinding.EstimatedUsd
 module.exports.ExecHandle = nativeBinding.ExecHandle
+module.exports.ExecProcess = nativeBinding.ExecProcess
 module.exports.ExecStream = nativeBinding.ExecStream
 module.exports.LineItem = nativeBinding.LineItem
 module.exports.RateTable = nativeBinding.RateTable
@@ -724,6 +725,7 @@ module.exports.costConstants = nativeBinding.costConstants
 module.exports.defaultBaseImage = nativeBinding.defaultBaseImage
 module.exports.errorCodes = nativeBinding.errorCodes
 module.exports.estimateRun = nativeBinding.estimateRun
+module.exports.GapPolicy = nativeBinding.GapPolicy
 module.exports.runReport = nativeBinding.runReport
 module.exports.sessionConstants = nativeBinding.sessionConstants
 module.exports.wireKinds = nativeBinding.wireKinds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theagenticguy/microvms",
-  "version": "0.1.0-rc.1",
+  "version": "0.2.0",
   "description": "Node bindings over microvms-core: the MicroVMs client with every trap closure",
   "license": "Apache-2.0",
   "author": "Laith Al-Saadoon",
@@ -26,7 +26,8 @@
   "files": [
     "index.js",
     "index.d.ts",
-    "README.md"
+    "README.md",
+    "*.node"
   ],
   "publishConfig": {
     "access": "public"
@@ -51,11 +52,5 @@
   },
   "engines": {
     "node": ">=22.13.0"
-  },
-  "optionalDependencies": {
-    "@theagenticguy/microvms-linux-x64-gnu": "0.1.0-rc.1",
-    "@theagenticguy/microvms-linux-arm64-gnu": "0.1.0-rc.1",
-    "@theagenticguy/microvms-darwin-arm64": "0.1.0-rc.1",
-    "@theagenticguy/microvms-win32-x64-msvc": "0.1.0-rc.1"
   }
-}
+}