@secure-exec/core 0.2.1 → 0.3.0-rc.2

package/dist/native-client.d.ts

@@ -0,0 +1,41 @@
+import { StdioSidecarProcess } from "./process.js";
+import type { LiveEventFrame, LiveResponseFrame, LiveSidecarRequestHandler, ProtocolFramePayloadCodec } from "./protocol-frames.js";
+import type { LiveOwnershipScope } from "./ownership.js";
+import type { LiveRequestPayload } from "./request-payloads.js";
+import type { LiveSidecarEventSelector } from "./event-buffer.js";
+export declare const DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120000;
+export declare const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4096;
+export declare const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5000;
+export declare const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2000;
+export interface StdioSidecarProtocolClientSpawnOptions {
+    cwd?: string;
+    command?: string;
+    args?: string[];
+    frameTimeoutMs?: number;
+    eventBufferCapacity?: number;
+    gracefulExitMs?: number;
+    forceExitMs?: number;
+    disposedErrorMessage?: string;
+    payloadCodec?: ProtocolFramePayloadCodec;
+}
+export declare class StdioSidecarProtocolClient {
+    readonly child: StdioSidecarProcess["child"];
+    private readonly sidecarProcess;
+    private readonly protocolClient;
+    private readonly gracefulExitMs;
+    private readonly forceExitMs;
+    private readonly disposedErrorMessage;
+    private constructor();
+    static spawn(options?: StdioSidecarProtocolClientSpawnOptions): StdioSidecarProtocolClient;
+    setSidecarRequestHandler(handler: LiveSidecarRequestHandler | null): void;
+    onEvent(handler: (event: LiveEventFrame) => void): () => void;
+    sendRequest(input: {
+        ownership: LiveOwnershipScope;
+        payload: LiveRequestPayload;
+    }): Promise<LiveResponseFrame>;
+    waitForEvent(matcher: LiveSidecarEventSelector | ((event: LiveEventFrame) => boolean), timeoutMs?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<LiveEventFrame>;
+    dispose(): Promise<void>;
+    failPermanently(error: Error): void;
+}

package/dist/native-client.js

@@ -0,0 +1,124 @@
+import { resolvePublishedSidecarBinary } from "./binary.js";
+import { SidecarProcessExited, StdioSidecarProcess, } from "./process.js";
+import { SidecarProtocolClient } from "./protocol-client.js";
+export const DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120_000;
+export const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4_096;
+export const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5_000;
+export const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2_000;
+export class StdioSidecarProtocolClient {
+    child;
+    sidecarProcess;
+    protocolClient;
+    gracefulExitMs;
+    forceExitMs;
+    disposedErrorMessage;
+    constructor(sidecarProcess, options) {
+        this.sidecarProcess = sidecarProcess;
+        this.child = sidecarProcess.child;
+        this.gracefulExitMs = options.gracefulExitMs;
+        this.forceExitMs = options.forceExitMs;
+        this.disposedErrorMessage = options.disposedErrorMessage;
+        this.protocolClient = new SidecarProtocolClient({
+            stdin: this.child.stdin,
+            stdout: this.child.stdout,
+            frameTimeoutMs: options.frameTimeoutMs,
+            eventBufferCapacity: options.eventBufferCapacity,
+            payloadCodec: options.payloadCodec,
+            stderrText: () => this.sidecarProcess.stderrText(),
+            streamEndedError: () => this.sidecarProcess.currentExitError() ??
+                new SidecarProcessExited({
+                    exitCode: this.child.exitCode,
+                    signal: this.child.signalCode,
+                    stderr: this.sidecarProcess.stderrText(),
+                }),
+            frameError: (error) => this.sidecarProcess.currentExitError() ?? error,
+        });
+        this.sidecarProcess.onExit((error) => {
+            this.failPermanently(error);
+        });
+        this.sidecarProcess.onError((error) => {
+            this.failPermanently(error);
+        });
+    }
+    static spawn(options = {}) {
+        return new StdioSidecarProtocolClient(StdioSidecarProcess.spawn({
+            command: options.command ?? resolvePublishedSidecarBinary(),
+            args: options.args ?? [],
+            cwd: options.cwd,
+        }), {
+            frameTimeoutMs: options.frameTimeoutMs ?? DEFAULT_SIDECAR_FRAME_TIMEOUT_MS,
+            eventBufferCapacity: options.eventBufferCapacity ??
+                DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,
+            gracefulExitMs: options.gracefulExitMs ?? DEFAULT_SIDECAR_GRACEFUL_EXIT_MS,
+            forceExitMs: options.forceExitMs ?? DEFAULT_SIDECAR_FORCE_EXIT_MS,
+            disposedErrorMessage: options.disposedErrorMessage ?? "sidecar client disposed",
+            payloadCodec: options.payloadCodec ?? "bare",
+        });
+    }
+    setSidecarRequestHandler(handler) {
+        this.protocolClient.setSidecarRequestHandler(handler);
+    }
+    onEvent(handler) {
+        return this.protocolClient.onEvent(handler);
+    }
+    async sendRequest(input) {
+        return await this.protocolClient.sendRequest(input);
+    }
+    async waitForEvent(matcher, timeoutMs, options) {
+        return await this.protocolClient.waitForEvent(matcher, timeoutMs, options);
+    }
+    async dispose() {
+        this.protocolClient.failPermanently(new Error(this.disposedErrorMessage));
+        if (!this.child.stdin.destroyed) {
+            try {
+                this.child.stdin.end();
+            }
+            catch {
+                // Stdin may already be closing. The child exit watcher will catch up.
+            }
+        }
+        const exitCode = await this.sidecarProcess.waitForExit(this.gracefulExitMs);
+        if (exitCode === null) {
+            try {
+                this.child.kill("SIGKILL");
+            }
+            catch {
+                // The child may have exited between the timeout and the kill attempt.
+            }
+            await this.sidecarProcess.waitForExit(this.forceExitMs);
+        }
+        this.protocolClient.dispose();
+        try {
+            this.child.stdin.destroy();
+        }
+        catch {
+            // Best effort. The child is gone so the descriptor will close on its own.
+        }
+        try {
+            this.child.stdout.destroy();
+        }
+        catch {
+            // Best effort. The child is gone so the descriptor will close on its own.
+        }
+        try {
+            this.child.stderr.destroy();
+        }
+        catch {
+            // Best effort. The child is gone so the descriptor will close on its own.
+        }
+        if (exitCode !== null &&
+            exitCode !== 0 &&
+            this.child.signalCode === null) {
+            throw new Error(`sidecar exited with code ${exitCode}\nstderr:\n${this.sidecarProcess.stderrText()}`);
+        }
+    }
+    failPermanently(error) {
+        this.protocolClient.failPermanently(error, {
+            replaceExisting: (current, next) => current instanceof SidecarProcessExited &&
+                current.exitCode === null &&
+                current.signal === null &&
+                next instanceof SidecarProcessExited &&
+                (next.exitCode !== null || next.signal !== null),
+        });
+    }
+}

package/dist/node-runtime.d.ts

@@ -0,0 +1,490 @@
+/**
+ * NodeRuntime — ergonomic façade for running guest JavaScript end-to-end.
+ *
+ * Boots a fully virtualized VM (via the native sidecar) and runs guest Node
+ * programs with minimal boilerplate. All of the sidecar spawn, session
+ * handshake, VM creation, root filesystem bootstrap, runtime-driver mounting,
+ * and lifecycle waiting are hidden behind `NodeRuntime.create()`.
+ *
+ * ```ts
+ * const rt = await NodeRuntime.create();
+ * const { stdout, exitCode } = await rt.exec("console.log('hi', 1 + 1)");
+ * await rt.dispose();
+ * ```
+ *
+ * Guest code is written to an ESM module inside the VM and executed as
+ * `node <file>` through the kernel, so all execution stays inside the kernel
+ * isolation boundary — no host escapes, no real Node.js builtins for guest
+ * work.
+ */
+import type { HostToolDefinition, Permissions } from "./test-runtime.js";
+export type { HostToolDefinition, HostToolExample } from "./test-runtime.js";
+/** Options for {@link NodeRuntime.create}. */
+export interface NodeRuntimeCreateOptions {
+    /** Environment variables visible to guest processes. */
+    env?: Record<string, string>;
+    /** Initial working directory for guest processes. Defaults to `/home/user`. */
+    cwd?: string;
+    /**
+     * Permission policy for the VM. Merged over a secure default that **denies
+     * network access** (guest code cannot reach the network until you opt in);
+     * the virtualized filesystem and processes stay enabled so programs run.
+     * Because it merges, a partial policy works: `{ network: "allow" }` grants
+     * the network while keeping the execution essentials. Pass a fuller policy
+     * (rule sets) to further sandbox individual scopes.
+     */
+    permissions?: Permissions;
+    /**
+     * Override the directory containing the WASM command binaries (the source of
+     * the guest `sh`). Defaults to the in-repo build output, or the
+     * `SECURE_EXEC_WASM_COMMANDS_DIR` environment variable when set.
+     */
+    commandsDir?: string;
+    /**
+     * Files to seed into the VM's virtual filesystem before the guest runs,
+     * keyed by absolute guest path. Parent directories are created as needed.
+     * Use this to project host assets, npm packages, or fixtures into the
+     * sandbox so guest code can `import`/`require`/read them. The bytes are
+     * copied into the VM's in-memory filesystem; the host filesystem is never
+     * exposed to the guest.
+     *
+     * ```ts
+     * const rt = await NodeRuntime.create({
+     *   files: { "/root/data.json": '{"ok":true}' },
+     * });
+     * ```
+     */
+    files?: Record<string, string | Uint8Array>;
+    /**
+     * Host directories to project into the VM's virtual filesystem, Docker-style.
+     * Each mount makes a host directory readable at a guest path. Files are read
+     * lazily from the host as the guest accesses them, so large trees (for
+     * example a `node_modules` package such as the TypeScript compiler) are
+     * projected without copying their bytes up front. The guest sees only the
+     * mounted subtree, never the wider host filesystem.
+     *
+     * ```ts
+     * const rt = await NodeRuntime.create({
+     *   mounts: [
+     *     {
+     *       guestPath: "/root/node_modules/typescript",
+     *       hostPath: "/abs/path/to/node_modules/typescript",
+     *       readOnly: true,
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    mounts?: HostDirectoryMount[];
+    /**
+     * Mount a host `node_modules` directory into the VM in one call so guest
+     * `import`/`require` resolve real, host-installed npm packages.
+     *
+     * Pass the absolute host path to a `node_modules` directory (or an object
+     * with that path and an explicit guest location). The whole directory is
+     * projected lazily, Docker-style, at a guest `node_modules` on the resolution
+     * path, so any package inside it resolves the way Node would over a real
+     * filesystem (ancestor `node_modules` walk, `exports`/conditions, symlinks).
+     * This is the ergonomic alternative to wiring up individual `mounts` entries
+     * per package.
+     *
+     * By default the directory is mounted at `/tmp/node_modules`, which is where
+     * the resolution walk for a program run by {@link NodeRuntime.exec} /
+     * {@link NodeRuntime.run} begins (each program is written under `/tmp`). Pass
+     * the object form with `guestPath` to mount it elsewhere on a different
+     * module's resolution path.
+     *
+     * ```ts
+     * const rt = await NodeRuntime.create({
+     *   nodeModules: "/abs/path/to/project/node_modules",
+     * });
+     * await rt.exec(`
+     *   import isNumber from "is-number";
+     *   console.log(isNumber(42));
+     * `);
+     * ```
+     *
+     * The host filesystem is never exposed beyond the mounted `node_modules`
+     * subtree. The mount is read-only.
+     */
+    nodeModules?: string | NodeModulesMount;
+    /**
+     * Host-side tools the guest can invoke as shell commands. Each entry is
+     * registered as a named guest command; when the guest runs it, the
+     * invocation round-trips back to the host and runs the tool's `handler`,
+     * whose return value is delivered back to the guest. This is how you give
+     * sandboxed guest code controlled, named host capabilities (the kind an AI
+     * agent calls as tools) without granting it the underlying access directly.
+     *
+     * The guest invokes a tool by name with JSON input:
+     *
+     * ```ts
+     * const rt = await NodeRuntime.create({
+     *   tools: {
+     *     add: {
+     *       description: "Add two numbers",
+     *       inputSchema: {
+     *         type: "object",
+     *         properties: { a: { type: "number" }, b: { type: "number" } },
+     *         required: ["a", "b"],
+     *       },
+     *       handler: ({ a, b }: { a: number; b: number }) => ({ sum: a + b }),
+     *     },
+     *   },
+     * });
+     * await rt.exec(`
+     *   import { execFileSync } from "node:child_process";
+     *   const out = execFileSync("add", ["add", "--json", JSON.stringify({ a: 2, b: 3 })]);
+     *   console.log(out.toString());
+     * `);
+     * ```
+     *
+     * When `tools` is provided and no `tool` permission scope is set, the `tool`
+     * scope is granted so the registered tools are invocable; pass your own
+     * `permissions.tool` policy to gate individual tools.
+     */
+    tools?: Record<string, HostToolDefinition>;
+    /**
+     * Guest-bound ports that may accept non-loopback connections. By default a
+     * guest server is reachable only over loopback inside the VM; listing a port
+     * here lifts that restriction for that port, letting connections from outside
+     * the loopback interface reach it. Use this for guests that run servers which
+     * must accept external connections (for example a dev server you expose
+     * beyond loopback).
+     *
+     * ```ts
+     * const rt = await NodeRuntime.create({
+     *   permissions: { network: "allow" },
+     *   loopbackExemptPorts: [3000],
+     * });
+     * ```
+     */
+    loopbackExemptPorts?: number[];
+}
+/** A host directory projected into the VM's virtual filesystem. */
+export interface HostDirectoryMount {
+    /** Absolute guest path the directory appears at inside the VM. */
+    guestPath: string;
+    /** Absolute host directory to project (read through the VFS, lazily). */
+    hostPath: string;
+    /** Mount read-only (the default). Pass `false` to allow guest writes. */
+    readOnly?: boolean;
+}
+/**
+ * Object form of the `nodeModules` create option: a host `node_modules`
+ * directory to project, optionally at an explicit guest path. The string form
+ * (`nodeModules: "/abs/node_modules"`) is shorthand for `{ hostPath }`.
+ */
+export interface NodeModulesMount {
+    /** Absolute host `node_modules` directory to project (read lazily). */
+    hostPath: string;
+    /**
+     * Absolute guest path to mount it at. Defaults to `/tmp/node_modules`, where
+     * the resolution walk for {@link NodeRuntime.exec} / {@link NodeRuntime.run}
+     * programs begins. Override to put it on a different module's resolution path.
+     */
+    guestPath?: string;
+}
+/** Result of {@link NodeRuntime.exec}. */
+export interface NodeRuntimeExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Options for a single {@link NodeRuntime.exec} call. */
+export interface NodeRuntimeExecOptions {
+    /** Extra environment variables for this run, merged over the VM env. */
+    env?: Record<string, string>;
+    /** Working directory for this run. */
+    cwd?: string;
+    /** Data piped to the guest program's stdin. */
+    stdin?: string | Uint8Array;
+    /** Abort the run after this many milliseconds. */
+    timeout?: number;
+    /**
+     * Cancel the run when this signal aborts. On abort the guest process is
+     * killed inside the VM (the kernel delivers `SIGTERM`) and the call rejects
+     * with the signal's abort reason. Use this to cancel an in-flight run from
+     * the outside, for example to enforce your own deadline or stop work when a
+     * request is canceled.
+     *
+     * ```ts
+     * const controller = new AbortController();
+     * const pending = rt.exec("while (true) {}", { signal: controller.signal });
+     * controller.abort();
+     * await pending.catch((err) => console.log(err.name)); // "AbortError"
+     * ```
+     */
+    signal?: AbortSignal;
+    /**
+     * Called with each chunk the guest writes to stdout as it is produced,
+     * letting you observe output incrementally instead of waiting for the run to
+     * finish. Chunks arrive as raw bytes; decode with a `TextDecoder` for text.
+     * The complete output is still returned as `result.stdout` when the run ends.
+     */
+    onStdout?: (chunk: Uint8Array) => void;
+    /**
+     * Called with each chunk the guest writes to stderr as it is produced,
+     * letting you observe output incrementally instead of waiting for the run to
+     * finish. Chunks arrive as raw bytes; decode with a `TextDecoder` for text.
+     * The complete output is still returned as `result.stderr` when the run ends.
+     */
+    onStderr?: (chunk: Uint8Array) => void;
+}
+/** The HTTP request {@link NodeRuntime.fetch} drives into the VM. */
+export interface NodeRuntimeFetchInput {
+    /** HTTP method. Defaults to `GET`. */
+    method?: string;
+    /** Request path (and query), e.g. `/api/users?limit=10`. */
+    path: string;
+    /** Request headers. */
+    headers?: Record<string, string>;
+    /** Request body. */
+    body?: string | Uint8Array;
+}
+/** The HTTP response {@link NodeRuntime.fetch} returns from the VM. */
+export interface NodeRuntimeFetchResponse {
+    /** HTTP status code, e.g. `200`. */
+    status: number;
+    /** HTTP status text, e.g. `OK`. */
+    statusText: string;
+    /** Response headers, lower-cased by name. */
+    headers: Record<string, string>;
+    /** Response body decoded as UTF-8 text. */
+    body: string;
+}
+/**
+ * Options for {@link NodeRuntime.spawn}. Inherits the streaming `onStdout` /
+ * `onStderr` hooks from {@link NodeRuntimeExecOptions}.
+ */
+export interface NodeRuntimeSpawnOptions extends NodeRuntimeExecOptions {
+}
+/**
+ * Describes the guest TCP listener to wait for with
+ * {@link NodeRuntime.waitForListener} or look up with
+ * {@link NodeRuntime.findListener}. A listener matches when a guest process is
+ * accepting connections on the given `port` (and `host`/`path` when supplied).
+ */
+export interface NodeRuntimeListenerQuery {
+    /** TCP port the guest listener is bound to, e.g. `3000`. */
+    port: number;
+    /** Bind host to match, e.g. `127.0.0.1`. Omit to match any host. */
+    host?: string;
+    /** Unix socket path to match, for path-bound listeners. */
+    path?: string;
+}
+/**
+ * A matched guest listener returned by {@link NodeRuntime.waitForListener} and
+ * {@link NodeRuntime.findListener}. `processId` identifies the guest process
+ * that owns the listening socket; the `host`/`port`/`path` it is bound to are
+ * reported when known.
+ */
+export interface NodeRuntimeListener {
+    /** The guest process id that owns the listening socket. */
+    processId: string;
+    /** The host the listener is bound to, when reported. */
+    host?: string;
+    /** The port the listener is bound to, when reported. */
+    port?: number;
+    /** The unix socket path the listener is bound to, when reported. */
+    path?: string;
+}
+/** Options for {@link NodeRuntime.waitForListener}. */
+export interface NodeRuntimeWaitForListenerOptions {
+    /**
+     * Give up after this many milliseconds and reject. Defaults to 10000. The
+     * wait also rejects if the bound `signal` aborts first.
+     */
+    timeoutMs?: number;
+    /** Abort the wait early; the returned promise rejects when it fires. */
+    signal?: AbortSignal;
+    /**
+     * How long to wait between listener lookups while polling, in milliseconds.
+     * Defaults to 50.
+     */
+    pollIntervalMs?: number;
+}
+/**
+ * A live handle to a guest process started with {@link NodeRuntime.spawn}.
+ *
+ * Unlike {@link NodeRuntime.exec}, which runs a program to completion and
+ * returns its captured output, a handle is returned immediately while the
+ * process keeps running. Use it to stream stdout/stderr, feed stdin, signal or
+ * kill the process, and await its exit. This is the building block for
+ * long-running guests such as dev servers: start one here, then drive requests
+ * into it with {@link NodeRuntime.fetch}.
+ */
+export interface NodeRuntimeProcess {
+    /** The guest process id. */
+    readonly pid: number;
+    /** Write data to the guest process's stdin. */
+    writeStdin(data: string | Uint8Array): void;
+    /** Close the guest process's stdin, signalling end-of-input. */
+    closeStdin(): void;
+    /**
+     * Send a signal to the guest process. Defaults to `SIGTERM`. Accepts a
+     * signal name (e.g. `"SIGKILL"`) or a raw signal number.
+     */
+    kill(signal?: NodeJS.Signals | number): void;
+    /** Resolve with the guest process's exit code once it terminates. */
+    wait(): Promise<number>;
+    /** The exit code once the process has exited, or `null` while it runs. */
+    readonly exitCode: number | null;
+}
+/** Result of {@link NodeRuntime.run}. */
+export interface NodeRuntimeRunResult<T = unknown> {
+    /** The JSON-decoded value the guest produced, when the run succeeded. */
+    value?: T;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Ergonomic, batteries-included runtime for executing guest JavaScript.
+ *
+ * Construct one with {@link NodeRuntime.create}, run programs with
+ * {@link NodeRuntime.exec} / {@link NodeRuntime.run}, and release the VM with
+ * {@link NodeRuntime.dispose}. A single instance can run many programs; each
+ * call executes a fresh guest process.
+ */
+export declare class NodeRuntime {
+    private readonly kernel;
+    private constructor();
+    /**
+     * Boot a VM and return a ready-to-use runtime. Spawns the sidecar, opens a
+     * session, creates the VM with a bootstrapped root filesystem, mounts the
+     * shell and Node runtimes, and waits for the VM to report ready.
+     */
+    static create(options?: NodeRuntimeCreateOptions): Promise<NodeRuntime>;
+    /**
+     * Run `code` as a guest Node program and capture its output.
+     *
+     * The source is written to an ES module inside the VM and executed with
+     * `node <file>`; it runs as standard ESM (top-level `await`, `import`).
+     */
+    exec(code: string, options?: NodeRuntimeExecOptions): Promise<NodeRuntimeExecResult>;
+    /**
+     * Run an already-written guest program file to completion and capture its
+     * output, honoring a caller-supplied `signal` for cancellation.
+     *
+     * Without a `signal`, this runs the program through the shell (`node <file>`)
+     * exactly as before. With a `signal`, it starts the program as a guest
+     * process so the run can be cancelled: when the signal aborts, the process is
+     * killed inside the VM (the kernel delivers `SIGTERM`) and the call rejects
+     * with the signal's abort reason.
+     */
+    private runProgram;
+    /**
+     * Start `code` as a long-running guest Node program and return a live handle
+     * to it, without waiting for it to finish.
+     *
+     * The source is written to an ES module inside the VM and started with
+     * `node <file>`; it runs as standard ESM (top-level `await`, `import`). The
+     * returned {@link NodeRuntimeProcess} lets you stream output, write to stdin,
+     * signal or kill the process, and await its exit. Pass `onStdout`/`onStderr`
+     * to receive output chunks as they are produced.
+     *
+     * Use this for guests that do not run to completion, such as a dev server you
+     * later drive with {@link NodeRuntime.fetch}:
+     *
+     * ```ts
+     * const server = await rt.spawn(`
+     *   import http from "node:http";
+     *   http.createServer((_, res) => res.end("ok")).listen(3000);
+     * `);
+     * const res = await rt.fetch(3000, { path: "/" });
+     * server.kill();
+     * await server.wait();
+     * ```
+     */
+    spawn(code: string, options?: NodeRuntimeSpawnOptions): Promise<NodeRuntimeProcess>;
+    /**
+     * Run `code` and return the JSON-serializable value it produces.
+     *
+     * The guest exposes a `__return(value)` function; call it with a
+     * JSON-serializable value and that value is decoded on the host as
+     * `result.value`. If `__return` is never called the value is `undefined`.
+     * stdout/stderr/exitCode are still captured.
+     */
+    run<T = unknown>(code: string, options?: NodeRuntimeExecOptions): Promise<NodeRuntimeRunResult<T>>;
+    /**
+     * Drive an HTTP request to a guest HTTP server listening inside the VM and
+     * read the response back on the host.
+     *
+     * Point this at a port a guest program is serving, for example a dev server
+     * started with {@link NodeRuntime.exec}. The
+     * request and response never leave the VM: the connection is made to the
+     * guest's loopback listener through the kernel socket table, so this works
+     * even when guest network egress is denied.
+     *
+     * ```ts
+     * const res = await rt.fetch(3000, { path: "/health" });
+     * console.log(res.status, res.body);
+     * ```
+     */
+    fetch(port: number, input: NodeRuntimeFetchInput): Promise<NodeRuntimeFetchResponse>;
+    /**
+     * Look up a guest TCP listener once and return it, or `null` when nothing is
+     * listening yet.
+     *
+     * This is the immediate, non-blocking check behind
+     * {@link NodeRuntime.waitForListener}: it asks the kernel socket table
+     * whether a guest process is accepting connections on the requested `port`
+     * (optionally narrowed by `host`/`path`) and returns the match, or `null` if
+     * none is up. Use {@link NodeRuntime.waitForListener} when you want to block
+     * until one appears.
+     *
+     * ```ts
+     * const listener = rt.findListener({ port: 3000 });
+     * if (listener) console.log("up on pid", listener.processId);
+     * ```
+     */
+    findListener(query: NodeRuntimeListenerQuery): NodeRuntimeListener | null;
+    /**
+     * Block until a guest TCP listener is accepting connections on the requested
+     * `port` (optionally narrowed by `host`/`path`), then resolve with it.
+     *
+     * This is the companion to {@link NodeRuntime.spawn} and
+     * {@link NodeRuntime.fetch} for dev-server scenarios: start a server, wait
+     * until it is actually listening, then drive requests into it. The kernel
+     * socket table is polled until a matching listener appears or the wait is
+     * cut short. If `timeoutMs` elapses (default 10000) or the supplied `signal`
+     * aborts first, the returned promise rejects.
+     *
+     * ```ts
+     * const server = await rt.spawn(`
+     *   import http from "node:http";
+     *   http.createServer((_, res) => res.end("ok")).listen(3000);
+     * `);
+     * const listener = await rt.waitForListener({ port: 3000 });
+     * const res = await rt.fetch(listener.port ?? 3000, { path: "/" });
+     * server.kill();
+     * await server.wait();
+     * ```
+     */
+    waitForListener(query: NodeRuntimeListenerQuery, options?: NodeRuntimeWaitForListenerOptions): Promise<NodeRuntimeListener>;
+    /**
+     * Register host-side tools the guest can invoke as shell commands, after the
+     * VM is already running. Each entry becomes a named guest command; when the
+     * guest runs it, the invocation round-trips back to the host and runs the
+     * tool's `handler`, whose return value is delivered back to the guest. This
+     * is the same capability as the `tools` create option, exposed for adding
+     * tools to a live runtime. See `tools` on {@link NodeRuntime.create} for the
+     * invocation shape and permission behavior.
+     *
+     * When registering tools this way, make sure the `tool` permission scope is
+     * granted (for example `permissions: { tool: "allow" }` on
+     * {@link NodeRuntime.create}) so the tools are invocable.
+     */
+    registerTools(tools: Record<string, HostToolDefinition>): Promise<void>;
+    /**
+     * Write a file into the VM's virtual filesystem, creating parent
+     * directories as needed. Use this to project assets or npm packages into
+     * the sandbox after boot; the host filesystem is never touched.
+     */
+    writeFile(filePath: string, content: string | Uint8Array): Promise<void>;
+    /** Read a file from the VM's virtual filesystem as raw bytes. */
+    readFile(filePath: string): Promise<Uint8Array>;
+    /** Tear down the VM and release the sidecar. */
+    dispose(): Promise<void>;
+}