@supermachine/core 0.7.5 → 0.7.11

package/index.d.ts

@@ -499,9 +499,60 @@ export declare class ExecChild {
    resize(cols: number, rows: number): Promise<void>
   /**
    * Send a signal to the guest-side process. Common values:
-   * 1=SIGHUP, 2=SIGINT, 9=SIGKILL, 15=SIGTERM.
+   * 1=SIGHUP, 2=SIGINT, 9=SIGKILL, 15=SIGTERM. Routes through
+   * the cached signaler so it works even if a concurrent
+   * `wait()` has already consumed the child handle (the
+   * signaler outlives the child; calls become no-ops on the
+   * closed socket).
    */
    signal(signum: number): Promise<void>
+  /**
+   * Return a thread-safe [`ExecSignaler`] handle that can signal
+   * or abort this child from ANY caller (including a different
+   * async task) without holding the ExecChild itself. The handle
+   * can outlive the child — after exit, calls become no-ops on
+   * the closed socket.
+   *
+   * Use this when you want to interrupt a `wait()` from a Ctrl-C
+   * handler, a cancel registry, or a pool-shutdown hook. The
+   * returned object is the JS-side analogue of Rust's
+   * `ExecSignaler` — Send + Sync + Clone, one atomic refcount
+   * inc per clone.
+   *
+   * Idiomatic shape:
+   *
+   * ```js
+   * const child = await vm.spawn({ argv: ["./run.sh"] });
+   * const sig = child.signaler();
+   * process.on("SIGINT", () => sig.kill());
+   * const exit = await child.wait();
+   * ```
+   */
+   signaler(): ExecSignaler
+  /**
+   * Close the host-side socket WITHOUT waiting for a clean exit.
+   * The demux thread observes EOF, a concurrent `wait()` returns
+   * an error within milliseconds. Use this when the agent /
+   * worker is unresponsive — e.g. you've already decided the
+   * process must stop right now and don't care about reaping a
+   * clean exit code.
+   *
+   * Works even AFTER a concurrent `wait()` has consumed the
+   * child handle — routes through the cached signaler so the
+   * host-side shutdown still fires.
+   */
+   abort(): void
+  /**
+   * Non-consuming poll for child exit. Returns `null` if the
+   * child is still running, or an `ExecWaitResult` if it has
+   * exited. Mirrors `std::process::Child::try_wait`. Useful for
+   * loops that want to check status without blocking, and that
+   * pair with a signaler stashed in a registry.
+   *
+   * Returns null also if `wait()` has already consumed the
+   * child (subsequent polls don't error).
+   */
+   tryWait(): ExecWaitResult | null
   /**
    * Wait for the guest-side process to exit and return its
    * status. Consumes the underlying ExecChild — subsequent
@@ -512,6 +563,44 @@ export declare class ExecChild {
    wait(): Promise<ExecWaitResult>
 }
 
+/**
+ * Thread-safe control handle for an [`ExecChild`]. Returned by
+ * [`ExecChild::signaler`]. Send a signal (SIGINT / SIGTERM /
+ * SIGKILL / ...) to the in-guest process from any caller — a
+ * cancel registry, a Ctrl-C handler, a pool-shutdown hook —
+ * without holding the ExecChild itself.
+ *
+ * The handle keeps the underlying socket alive via Arc refcount
+ * (one atomic inc per JS-side wrapper). Calls after the child
+ * has exited or been waited are no-ops on the closed socket;
+ * they don't panic or deadlock.
+ */
+export declare class ExecSignaler {
+  /**
+   * Send a signal (numeric) to the in-guest process. Common
+   * values: 2 = SIGINT, 9 = SIGKILL, 15 = SIGTERM.
+   */
+   signal(signum: number): void
+  /**
+   * Shortcut for `signal(9)` — SIGKILL. Mirrors
+   * `child_process.ChildProcess.kill('SIGKILL')` semantics on
+   * the JS side.
+   */
+   kill(): void
+  /**
+   * Close the host-side socket immediately. Wakes a concurrent
+   * `wait()` on the corresponding ExecChild, regardless of
+   * whether the in-guest agent is still alive. Use this when
+   * the SIGNAL path won't work — e.g. you've already
+   * SIGKILL'd the guest agent, or the worker process is dead
+   * and you want the host-side `await child.wait()` to
+   * return now.
+   *
+   * Idempotent.
+   */
+   abort(): void
+}
+
 /**
  * VM handle. Drop or `release()` to return to the pool. With Node
  * 20+, use the `using` keyword + `Symbol.asyncDispose`.

package/index.js

@@ -239,6 +239,31 @@ function wrapExecChild(native) {
     async wait() {
       return native.wait();
     },
+    // 0.7.11 additions — cancellable-from-anywhere control surface.
+    // See the napi `ExecSignaler` class for the full shape.
+    signaler() {
+      return wrapExecSignaler(native.signaler());
+    },
+    async abort() {
+      return native.abort();
+    },
+    async tryWait() {
+      return native.tryWait();
+    },
+  };
+}
+
+function wrapExecSignaler(native) {
+  return {
+    async signal(signum) {
+      return native.signal(signum);
+    },
+    async kill() {
+      return native.kill();
+    },
+    async abort() {
+      return native.abort();
+    },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supermachine/core",
-  "version": "0.7.5",
+  "version": "0.7.11",
   "description": "Run any OCI/Docker image as a hardware-isolated microVM. Node/Bun/Deno binding for the supermachine Rust crate.",
   "license": "Apache-2.0",
   "main": "index.js",
@@ -22,7 +22,7 @@
     "arm64"
   ],
   "optionalDependencies": {
-    "@supermachine/core-darwin-arm64": "0.7.5"
+    "@supermachine/core-darwin-arm64": "0.7.11"
   },
   "scripts": {
     "build:rust": "TYPE_DEF_TMP_PATH=$(pwd)/scripts/.napi_type_defs.tmp cargo build --release -p supermachine-napi && cargo build --release --bin supermachine-worker -p supermachine",