@rivet-dev/agentos-runtime-core 0.0.0-codex-actor-plugin-contract-coverage.115ca8a → 0.0.0-fix-main-wasm-ownership.150c49a

package/dist/kernel-proxy.js

@@ -4,6 +4,8 @@ export function serializeMountConfigForSidecar(mount) {
     if ("driver" in mount) {
         return {
             guestPath: mount.path,
+            guestSource: mount.guestSource ?? "js_bridge",
+            guestFstype: mount.guestFstype ?? "js_bridge",
             readOnly: mount.readOnly ?? false,
             plugin: {
                 id: "js_bridge",
@@ -13,6 +15,8 @@ export function serializeMountConfigForSidecar(mount) {
     }
     return {
         guestPath: mount.path,
+        guestSource: mount.guestSource ?? mount.plugin.id,
+        guestFstype: mount.guestFstype ?? mount.plugin.id,
         readOnly: mount.readOnly ?? false,
         plugin: {
             id: mount.plugin.id,
@@ -70,6 +74,15 @@ const PREFERRED_SIGNAL_NAMES = [
     "SIGEMT",
     "SIGINFO",
 ];
+const NON_TERMINATING_SIGNALS = new Set([
+    "0",
+    "SIGCHLD",
+    "SIGCONT",
+    "SIGSTOP",
+    "SIGURG",
+    "SIGWINCH",
+]);
+const LOCALLY_TERMINATING_SIGNALS = new Set(["SIGKILL", "SIGTERM"]);
 const NON_CANONICAL_SIGNAL_NAMES = new Set([
     "SIGCLD",
     "SIGIOT",
@@ -262,7 +275,10 @@ export class NativeSidecarKernelProxy {
         this.eventPumpAbortController.abort();
         const liveProcesses = [...this.trackedProcesses.values()].filter((entry) => entry.exitCode === null);
         await Promise.allSettled(liveProcesses.map((entry) => this.signalProcess(entry, 15)));
-        await this.client.disposeVm(this.session, this.vm).catch(() => { });
+        await Promise.race([
+            this.client.disposeVm(this.session, this.vm),
+            new Promise((resolve) => setTimeout(resolve, 1000)),
+        ]).catch(() => { });
         for (const entry of liveProcesses) {
             if (entry.exitCode === null) {
                 // The sidecar dispose path already performs TERM/KILL escalation for any
@@ -478,13 +494,17 @@ export class NativeSidecarKernelProxy {
                 }
                 entry.pendingKillSignal = signal;
                 void entry.startPromise.then(async () => {
-                    if (entry.exitCode !== null || entry.pendingKillSignal === null) {
+                    if (entry.pendingKillSignal === null) {
                         return;
                     }
                     const pendingSignal = entry.pendingKillSignal;
                     entry.pendingKillSignal = null;
                     await this.signalProcess(entry, pendingSignal);
                 });
+                if ((signal === 9 || signal === 15) &&
+                    entry.exitCode === null) {
+                    this.finishProcess(entry, 128 + signal);
+                }
             },
             wait: async () => {
                 const exitCode = await this.waitForTrackedProcess(entry);
@@ -506,7 +526,7 @@ export class NativeSidecarKernelProxy {
         return proc;
     }
     openShell(options) {
-        const stdoutHandlers = new Set();
+        const terminalHandlers = new Set();
         const stderrHandlers = new Set();
         const command = options?.command ?? "sh";
         const args = options?.args ??
@@ -565,7 +585,7 @@ export class NativeSidecarKernelProxy {
             const normalized = normalizeSyntheticTerminalText(text);
             updateSyntheticCursor(normalized);
             const chunk = textEncoder.encode(normalized);
-            for (const handler of stdoutHandlers) {
+            for (const handler of terminalHandlers) {
                 handler(chunk);
             }
         };
@@ -576,7 +596,7 @@ export class NativeSidecarKernelProxy {
             const normalized = normalizeSyntheticTerminalText(text);
             updateSyntheticCursor(normalized);
             const chunk = textEncoder.encode(normalized);
-            for (const handler of stdoutHandlers) {
+            for (const handler of terminalHandlers) {
                 handler(chunk);
             }
         };
@@ -621,7 +641,7 @@ export class NativeSidecarKernelProxy {
             commandInFlight = false;
             const promptPrefix = syntheticCursorAtLineStart ? "" : "\r\n";
             const promptChunk = textEncoder.encode(`${promptPrefix}${promptText}`);
-            for (const handler of stdoutHandlers) {
+            for (const handler of terminalHandlers) {
                 handler(promptChunk);
             }
             syntheticCursorAtLineStart = false;
@@ -658,7 +678,7 @@ export class NativeSidecarKernelProxy {
             }
         };
         let onData = null;
-        stdoutHandlers.add((data) => onData?.(data));
+        terminalHandlers.add((data) => onData?.(data));
         if (options?.onStderr) {
             stderrHandlers.add(options.onStderr);
         }
@@ -817,7 +837,7 @@ export class NativeSidecarKernelProxy {
             cwd: options?.cwd,
             streamStdin: true,
             onStdout: (chunk) => {
-                for (const handler of stdoutHandlers) {
+                for (const handler of terminalHandlers) {
                     handler(chunk);
                 }
                 if (commandInFlight) {
@@ -825,6 +845,11 @@ export class NativeSidecarKernelProxy {
                 }
             },
             onStderr: (chunk) => {
+                // `onData` is the ordered PTY rendering stream. `onStderr` remains an
+                // optional channel-specific diagnostic tap and must not also be rendered.
+                for (const handler of terminalHandlers) {
+                    handler(chunk);
+                }
                 for (const handler of stderrHandlers) {
                     handler(chunk);
                 }
@@ -878,13 +903,7 @@ export class NativeSidecarKernelProxy {
         const stdin = process.stdin;
         const stdout = process.stdout;
         const { onData, ...shellOptions } = options ?? {};
-        const shell = this.openShell({
-            ...shellOptions,
-            onStderr: shellOptions.onStderr ??
-                ((data) => {
-                    process.stderr.write(data);
-                }),
-        });
+        const shell = this.openShell(shellOptions);
         const outputHandler = onData ??
             ((data) => {
                 stdout.write(data);
@@ -985,6 +1004,10 @@ export class NativeSidecarKernelProxy {
         }
         return this.client.rename(this.session, this.vm, oldPath, newPath);
     }
+    // Test-runtime only: runtime mounts registered here stay host-side local
+    // compat mounts and are not delivered to the sidecar. The production proxy
+    // in @rivet-dev/agentos-core reconfigures sidecar mounts on every
+    // mountFs/unmountFs.
     mountFs(path, driver, options) {
         this.localMounts.unshift({
             path: posixPath.normalize(path),
@@ -1124,15 +1147,6 @@ export class NativeSidecarKernelProxy {
         if (entry.onStdout.size === 0 && entry.onStderr.size === 0) {
             return;
         }
-        if (entry.exitViaEvent) {
-            // The sidecar drains process output before it emits `process_exited`,
-            // the stdio frame stream is FIFO, and this pump dispatches events in
-            // order. Once the exit event reaches this entry, no trailing output can
-            // follow it; one zero-delay turn is cheap insurance for same-tick
-            // listener scheduling.
-            await drainTrailingProcessOutputTurn(0);
-            return;
-        }
         let observedGeneration = entry.outputGeneration;
         let quietTurns = 0;
         let delayMs = 0;
@@ -1303,9 +1317,27 @@ export class NativeSidecarKernelProxy {
         return entry.waitWithFallbackPromise;
     }
     async signalProcess(entry, signal) {
-        await this.signalRefreshes.get(entry.pid);
+        const sidecarSignal = toSidecarSignalName(signal);
+        let timedOut = false;
+        const killPromise = this.client.killProcess(this.session, this.vm, entry.processId, sidecarSignal);
         try {
-            await this.client.killProcess(this.session, this.vm, entry.processId, toSidecarSignalName(signal));
+            await Promise.race([
+                killPromise,
+                new Promise((resolve) => setTimeout(() => {
+                    timedOut = true;
+                    resolve();
+                }, 1000)),
+            ]);
+            if (timedOut) {
+                void killPromise.catch(() => { });
+            }
+            const hasGuestHandler = this.signalStates.get(entry.pid)?.handlers.has(signal) ?? false;
+            if (entry.exitCode === null &&
+                !hasGuestHandler &&
+                LOCALLY_TERMINATING_SIGNALS.has(sidecarSignal) &&
+                (entry.driver === "wasmvm" || timedOut)) {
+                this.finishProcess(entry, 128 + signal);
+            }
         }
         catch (error) {
             if (isNoSuchProcessError(error) || isUnknownVmError(error)) {
@@ -1520,12 +1552,12 @@ export class NativeSidecarKernelProxy {
                 return this.client.pread(this.session, this.vm, path, offset, length);
             },
             pwrite: async (path, offset, data) => {
-                const bytes = await this.createFilesystemView(includeLocalMounts).readFile(path);
-                const nextSize = Math.max(bytes.length, offset + data.length);
-                const updated = new Uint8Array(nextSize);
-                updated.set(bytes);
-                updated.set(data, offset);
-                await this.createFilesystemView(includeLocalMounts).writeFile(path, updated);
+                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
+                if (local) {
+                    this.assertLocalWritable(local.mount);
+                    return local.mount.fs.pwrite(local.relativePath, offset, data);
+                }
+                return this.client.pwrite(this.session, this.vm, path, offset, data);
             },
         };
     }
@@ -1727,21 +1759,27 @@ function isMissingHostProcessError(error) {
 function errnoError(code, message) {
     return Object.assign(new Error(`${code}: ${message}`), { code });
 }
+// VirtualStat is a numeric, Node-default-shaped view: u64 fields above
+// Number.MAX_SAFE_INTEGER lose precision here, same as Node's non-bigint
+// fs.stat on the host.
 function toVirtualStat(stat) {
     return {
         mode: stat.mode,
-        size: stat.size,
-        blocks: stat.blocks,
-        dev: stat.dev,
-        rdev: stat.rdev,
+        size: Number(stat.size),
+        sizeExact: stat.size,
+        blocks: Number(stat.blocks),
+        dev: Number(stat.dev),
+        rdev: Number(stat.rdev),
         isDirectory: stat.is_directory,
         isSymbolicLink: stat.is_symbolic_link,
         atimeMs: stat.atime_ms,
         mtimeMs: stat.mtime_ms,
         ctimeMs: stat.ctime_ms,
         birthtimeMs: stat.birthtime_ms,
-        ino: stat.ino,
-        nlink: stat.nlink,
+        ino: Number(stat.ino),
+        inoExact: stat.ino,
+        nlink: Number(stat.nlink),
+        nlinkExact: stat.nlink,
         uid: stat.uid,
         gid: stat.gid,
     };
@@ -1774,4 +1812,4 @@ function socketLookupKey(kind, request) {
         path: request.path ?? null,
     });
 }
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./sidecar-process.js";
+export { SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./sidecar-process.js";

package/dist/native-client.d.ts

@@ -1,10 +1,9 @@
+import type { LiveSidecarEventSelector } from "./event-buffer.js";
+import type { LiveOwnershipScope } from "./ownership.js";
 import { StdioSidecarProcess } from "./process.js";
-import type { SidecarProcessTransport } from "./sidecar-client.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;
+import type { SidecarProcessTransport } from "./sidecar-client.js";
 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;
@@ -12,12 +11,17 @@ export interface StdioSidecarProtocolClientSpawnOptions {
     cwd?: string;
     command?: string;
     args?: string[];
-    frameTimeoutMs?: number;
     eventBufferCapacity?: number;
     gracefulExitMs?: number;
     forceExitMs?: number;
     disposedErrorMessage?: string;
     payloadCodec?: ProtocolFramePayloadCodec;
+    /**
+     * Override the silence watchdog window (default 30s). Tests only — the
+     * window is a fixed protocol constant paired with the sidecar's 10s
+     * heartbeat cadence, not an operator tunable.
+     */
+    silenceTimeoutMs?: number;
 }
 export declare class StdioSidecarProtocolClient implements SidecarProcessTransport {
     readonly child: StdioSidecarProcess["child"];

package/dist/native-client.js

@@ -1,8 +1,7 @@
 import { resolvePublishedSidecarBinary } from "./binary.js";
-import { SidecarProcessExited, StdioSidecarProcess, } from "./process.js";
+import { SidecarProcessExited, StdioSidecarProcess } from "./process.js";
 import { SidecarProtocolClient } from "./protocol-client.js";
 import { registerSidecarProcessSpawnFactory } from "./sidecar-process.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;
@@ -22,9 +21,21 @@ export class StdioSidecarProtocolClient {
         this.protocolClient = new SidecarProtocolClient({
             stdin: this.child.stdin,
             stdout: this.child.stdout,
-            frameTimeoutMs: options.frameTimeoutMs,
+            control: this.sidecarProcess.control,
             eventBufferCapacity: options.eventBufferCapacity,
             payloadCodec: options.payloadCodec,
+            silenceTimeoutMs: options.silenceTimeoutMs,
+            // A silent sidecar is dead or wedged; reap the process so it cannot
+            // linger as a zombie holding VM resources. The watchdog then rejects
+            // all in-flight requests with `SidecarSilenceTimeout`.
+            onSilenceExpired: () => {
+                try {
+                    this.child.kill("SIGKILL");
+                }
+                catch {
+                    // The child may have exited between the check and the kill.
+                }
+            },
             stderrText: () => this.sidecarProcess.stderrText(),
             streamEndedError: () => this.sidecarProcess.currentExitError() ??
                 new SidecarProcessExited({
@@ -47,9 +58,8 @@ export class StdioSidecarProtocolClient {
             args: options.args ?? [],
             cwd: options.cwd,
         }), {
-            frameTimeoutMs: options.frameTimeoutMs ?? DEFAULT_SIDECAR_FRAME_TIMEOUT_MS,
-            eventBufferCapacity: options.eventBufferCapacity ??
-                DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,
+            silenceTimeoutMs: options.silenceTimeoutMs,
+            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",
@@ -69,6 +79,13 @@ export class StdioSidecarProtocolClient {
         return await this.protocolClient.waitForEvent(matcher, timeoutMs, options);
     }
     async dispose() {
+        let shutdownError = null;
+        try {
+            await this.protocolClient.shutdown(this.disposedErrorMessage);
+        }
+        catch (error) {
+            shutdownError = error instanceof Error ? error : new Error(String(error));
+        }
         this.protocolClient.failPermanently(new Error(this.disposedErrorMessage));
         if (!this.child.stdin.destroyed) {
             try {
@@ -78,6 +95,14 @@ export class StdioSidecarProtocolClient {
                 // Stdin may already be closing. The child exit watcher will catch up.
             }
         }
+        if (!this.sidecarProcess.control.destroyed) {
+            try {
+                this.sidecarProcess.control.end();
+            }
+            catch {
+                // The control socket may already be closing with the child.
+            }
+        }
         const exitCode = await this.sidecarProcess.waitForExit(this.gracefulExitMs);
         if (exitCode === null) {
             try {
@@ -107,11 +132,18 @@ export class StdioSidecarProtocolClient {
         catch {
             // Best effort. The child is gone so the descriptor will close on its own.
         }
-        if (exitCode !== null &&
-            exitCode !== 0 &&
-            this.child.signalCode === null) {
+        try {
+            this.sidecarProcess.control.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()}`);
         }
+        if (shutdownError && this.child.exitCode !== 0) {
+            throw shutdownError;
+        }
     }
     failPermanently(error) {
         this.protocolClient.failPermanently(error, {

package/dist/node-runtime-options-schema.d.ts

@@ -114,4 +114,4 @@ export declare const nodeRuntimePermissionsSchema: z.ZodObject<{
  * the Rust VM config.
  */
 export declare const nodeRuntimeCreateOptionsSchema: z.ZodType<NodeRuntimeCreateOptions>;
-export declare function parseNodeRuntimeCreateOptions(options?: NodeRuntimeCreateOptions): NodeRuntimeCreateOptions;
+export declare function parseNodeRuntimeCreateOptions(options: NodeRuntimeCreateOptions): NodeRuntimeCreateOptions;

package/dist/node-runtime-options-schema.js

@@ -1,6 +1,46 @@
 import { z } from "zod";
 const permissionModeSchema = z.enum(["allow", "deny"]);
 const stringArray = z.array(z.string());
+const vmIdSchema = z.number().int().min(0).max(0xffffffff);
+const vmAccountNameSchema = z
+    .string()
+    .min(1)
+    .refine((value) => !/[:\s\0]/u.test(value), "Invalid account name");
+const vmGuestPathSchema = z.string().startsWith("/");
+const vmUserAccountSchema = z
+    .object({
+    uid: vmIdSchema,
+    gid: vmIdSchema,
+    username: vmAccountNameSchema,
+    homedir: vmGuestPathSchema,
+    shell: vmGuestPathSchema,
+    gecos: z.string().optional(),
+    supplementaryGids: z.array(vmIdSchema).max(64),
+})
+    .strict();
+const vmGroupSchema = z
+    .object({
+    gid: vmIdSchema,
+    name: vmAccountNameSchema,
+    members: z.array(vmAccountNameSchema),
+})
+    .strict();
+const vmUserConfigSchema = z
+    .object({
+    uid: vmIdSchema.optional(),
+    gid: vmIdSchema.optional(),
+    euid: vmIdSchema.optional(),
+    egid: vmIdSchema.optional(),
+    username: z.string().optional(),
+    homedir: z.string().optional(),
+    shell: z.string().optional(),
+    gecos: z.string().optional(),
+    groupName: z.string().optional(),
+    supplementaryGids: z.array(vmIdSchema).max(64).optional(),
+    accounts: z.array(vmUserAccountSchema).max(64).optional(),
+    groups: z.array(vmGroupSchema).max(128).optional(),
+})
+    .strict();
 const fsPermissionRuleSchema = z
     .object({
     mode: permissionModeSchema,
@@ -91,8 +131,10 @@ const bindingDefinitionSchema = z
  */
 export const nodeRuntimeCreateOptionsSchema = z
     .object({
+    filesystem: z.custom((value) => typeof value === "object" && value !== null, { message: "Expected caller-owned VirtualFileSystem object" }),
     env: z.record(z.string(), z.string()).optional(),
     cwd: z.string().optional(),
+    user: vmUserConfigSchema.optional(),
     permissions: nodeRuntimePermissionsSchema.optional(),
     commandsDir: z.string().optional(),
     wasmCommandDirs: stringArray.optional(),
@@ -116,6 +158,6 @@ export const nodeRuntimeCreateOptionsSchema = z
     jsRuntime: jsRuntimeSchema.optional(),
 })
     .strict();
-export function parseNodeRuntimeCreateOptions(options = {}) {
+export function parseNodeRuntimeCreateOptions(options) {
     return nodeRuntimeCreateOptionsSchema.parse(options);
 }

package/dist/node-runtime.d.ts

@@ -17,10 +17,11 @@
  * isolation boundary — no host escapes, no real Node.js builtins for guest
  * work.
  */
-import type { BindingDefinition, KernelBootTiming, Permissions, VirtualDirEntry } from "./test-runtime.js";
+import type { BindingDefinition, KernelBootTiming, Permissions, VirtualDirEntry, VirtualFileSystem } from "./test-runtime.js";
 import type { JsRuntimeConfig } from "./generated/JsRuntimeConfig.js";
+import type { VmUserConfig } from "./generated/VmUserConfig.js";
 import type { SidecarProcess } from "./sidecar-process.js";
-export type { BindingDefinition, HostToolExample, VirtualDirEntry, } from "./test-runtime.js";
+export type { BindingDefinition, BindingExample, VirtualDirEntry, } from "./test-runtime.js";
 export { resolveNodeRuntimeSidecarBinary } from "./test-runtime.js";
 export type NodeRuntimeBootTimingPhase = KernelBootTiming["phase"] | "runtime_mount_wasm" | "runtime_mount_node" | "bindings";
 export interface NodeRuntimeBootTiming {
@@ -50,10 +51,18 @@ export declare function resolveNodeRuntimeCommandsDir(explicit?: string): string
  * `crates/vm-config/src/lib.rs::CreateVmConfig`.
  */
 export interface NodeRuntimeCreateOptions {
+    /**
+     * Caller-owned filesystem used only by this low-level compatibility runtime.
+     * AgentOS clients do not create a TypeScript filesystem implicitly; normal
+     * product code should use the sidecar-owned VFS through `AgentOs`.
+     */
+    filesystem: VirtualFileSystem;
     /** Environment variables visible to guest processes. */
     env?: Record<string, string>;
     /** Initial working directory for guest processes. Defaults to `/workspace`. */
     cwd?: string;
+    /** Initial virtual Linux credentials and account record. Defaults to `1000:1000` (`agentos`). */
+    user?: VmUserConfig;
     /**
      * Permission policy for the VM. Merged over a secure default that **denies
      * network access** (guest code cannot reach the network until you opt in);
@@ -440,7 +449,7 @@ export declare class NodeRuntime {
      * 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>;
+    static create(options: NodeRuntimeCreateOptions): Promise<NodeRuntime>;
     createResidentRunner(_options?: NodeRuntimeResidentRunnerOptions): Promise<NodeRuntimeResidentRunner>;
     /**
      * Run `code` as a guest Node program and capture its output.

package/dist/node-runtime.js

@@ -20,18 +20,18 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { createInMemoryFileSystem, createKernel, createNodeRuntime, createWasmVmRuntime, NodeFileSystem, } from "./test-runtime.js";
+import { createKernel, createNodeRuntime, createWasmVmRuntime, NodeFileSystem, } from "./test-runtime.js";
 import { parseNodeRuntimeCreateOptions } from "./node-runtime-options-schema.js";
 export { resolveNodeRuntimeSidecarBinary } from "./test-runtime.js";
 /** Repository root, used to locate the in-repo WASM command build output. */
 const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
 /**
  * In-repo build output for the WASM coreutils/shell command binaries, produced
- * by the Rust command build (`make -C registry/native wasm`). Only present in a
+ * by the Rust command build (`make -C toolchain wasm`). Only present in a
  * developer checkout; preferred when it exists so local edits are picked up
  * without re-vendoring.
  */
-const REPO_COMMANDS_DIR = path.join(REPO_ROOT, "registry/native/target/wasm32-wasip1/release/commands");
+const REPO_COMMANDS_DIR = path.join(REPO_ROOT, "toolchain/target/wasm32-wasip1/release/commands");
 /**
  * Commands vendored into the published `@rivet-dev/agentos-runtime-core` package by
  * `scripts/copy-wasm-commands.mjs` (listed in `files` as `commands`). This is
@@ -128,14 +128,14 @@ export class NodeRuntime {
      * session, creates the VM with a bootstrapped root filesystem, mounts the
      * shell and Node runtimes, and waits for the VM to report ready.
      */
-    static async create(options = {}) {
+    static async create(options) {
         options = parseNodeRuntimeCreateOptions(options);
         const commandsDir = resolveNodeRuntimeCommandsDir(options.commandsDir);
         // Seed caller-provided files into the VM's in-memory filesystem before
         // boot so they are part of the root filesystem snapshot the guest sees
         // (e.g. projected npm packages or fixtures). The host filesystem is
         // never exposed; only these bytes are copied in.
-        const filesystem = createInMemoryFileSystem();
+        const filesystem = options.filesystem;
         if (options.files) {
             for (const [filePath, content] of Object.entries(options.files)) {
                 await filesystem.writeFile(filePath, content);
@@ -183,6 +183,7 @@ export class NodeRuntime {
             },
             env: options.env,
             cwd: options.cwd,
+            user: options.user,
             sidecar: options.sidecar,
             onBootTiming: (timing) => options.onBootTiming?.(timing),
             loopbackExemptPorts: options.loopbackExemptPorts,
@@ -202,7 +203,7 @@ export class NodeRuntime {
             // installed as guest commands the moment the VM is ready.
             const bindings = options.bindings;
             if (bindings && Object.keys(bindings).length > 0) {
-                await measureBootTiming("bindings", options.onBootTiming, () => kernel.registerHostTools(bindings));
+                await measureBootTiming("bindings", options.onBootTiming, () => kernel.registerBindings(bindings));
             }
         }
         catch (error) {
@@ -588,7 +589,7 @@ export class NodeRuntime {
      * {@link NodeRuntime.create}) so the bindings are invocable.
      */
     async registerBindings(bindings) {
-        await this.kernel.registerHostTools(bindings);
+        await this.kernel.registerBindings(bindings);
     }
     /**
      * Write a file into the VM's virtual filesystem, creating parent

package/dist/process.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { Duplex } from "node:stream";
 export { SidecarProcessError, SidecarProcessExited, } from "./sidecar-errors.js";
 import { SidecarProcessError, SidecarProcessExited } from "./sidecar-errors.js";
 export interface StdioSidecarProcessSpawnOptions {
@@ -8,12 +9,13 @@ export interface StdioSidecarProcessSpawnOptions {
 }
 export declare class StdioSidecarProcess {
     readonly child: ChildProcessWithoutNullStreams;
+    readonly control: Duplex;
     private readonly stderrChunks;
     private readonly exitListeners;
     private readonly errorListeners;
     private constructor();
     static spawn(options: StdioSidecarProcessSpawnOptions): StdioSidecarProcess;
-    static fromChild(child: ChildProcessWithoutNullStreams): StdioSidecarProcess;
+    static fromChild(child: ChildProcessWithoutNullStreams, control?: Duplex): StdioSidecarProcess;
     onExit(handler: (error: SidecarProcessExited) => void): () => void;
     onError(handler: (error: SidecarProcessError) => void): () => void;
     stderrText(): string;

package/dist/process.js

@@ -1,13 +1,15 @@
-import { spawn, } from "node:child_process";
+import { spawn } from "node:child_process";
 export { SidecarProcessError, SidecarProcessExited, } from "./sidecar-errors.js";
-import { SidecarProcessError, SidecarProcessExited, } from "./sidecar-errors.js";
+import { SidecarProcessError, SidecarProcessExited } from "./sidecar-errors.js";
 export class StdioSidecarProcess {
     child;
+    control;
     stderrChunks = [];
     exitListeners = new Set();
     errorListeners = new Set();
-    constructor(child) {
+    constructor(child, control) {
         this.child = child;
+        this.control = control;
         this.child.stderr.on("data", (chunk) => {
             this.stderrChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
         });
@@ -30,13 +32,20 @@ export class StdioSidecarProcess {
         });
     }
     static spawn(options) {
-        return new StdioSidecarProcess(spawn(options.command, options.args ?? [], {
+        const child = spawn(options.command, options.args ?? [], {
             cwd: options.cwd,
-            stdio: ["pipe", "pipe", "pipe"],
-        }));
+            stdio: ["pipe", "pipe", "pipe", "pipe"],
+        });
+        try {
+            return new StdioSidecarProcess(child, requireControlStream(child));
+        }
+        catch (error) {
+            child.kill("SIGKILL");
+            throw error;
+        }
     }
-    static fromChild(child) {
-        return new StdioSidecarProcess(child);
+    static fromChild(child, control) {
+        return new StdioSidecarProcess(child, control ?? requireControlStream(child));
     }
     onExit(handler) {
         this.exitListeners.add(handler);
@@ -95,3 +104,13 @@ export class StdioSidecarProcess {
         });
     }
 }
+function requireControlStream(child) {
+    const stream = child.stdio[3];
+    if (!stream ||
+        typeof stream.write !== "function" ||
+        typeof stream.on !== "function" ||
+        typeof stream.read !== "function") {
+        throw new Error("sidecar process did not expose a full-duplex fd 3");
+    }
+    return stream;
+}