@rivet-dev/agentos-runtime-core 0.0.0-main.2f99c77 → 0.0.0-main.5ac5a14

package/dist/kernel-proxy.d.ts

@@ -4,11 +4,15 @@ import type { AuthenticatedSession, CreatedVm, SidecarProcess, SidecarMountDescr
 export interface PlainMountConfig {
     path: string;
     driver: VirtualFileSystem;
+    guestSource?: string;
+    guestFstype?: string;
     readOnly?: boolean;
 }
 export interface NativeMountConfig {
     path: string;
     plugin: NativeMountPluginDescriptor;
+    guestSource?: string;
+    guestFstype?: string;
     readOnly?: boolean;
 }
 export declare function serializeMountConfigForSidecar(mount: PlainMountConfig | NativeMountConfig): SidecarMountDescriptor;

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,
@@ -22,7 +26,7 @@ export function serializeMountConfigForSidecar(mount) {
 }
 const SYNTHETIC_PID_BASE = 1_000_000;
 const MISSING_EXIT_EVENT_GRACE_MS = 500;
-const PROTECTED_READ_ONLY_GUEST_ROOTS = ["/etc/secure-exec"];
+const PROTECTED_READ_ONLY_GUEST_ROOTS = ["/etc/agentos"];
 const TRAILING_OUTPUT_DRAIN_INTERVAL_MS = 10;
 const TRAILING_OUTPUT_DRAIN_MAX_MS = 250;
 const TRAILING_OUTPUT_DRAIN_QUIET_TURNS = 2;
@@ -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
@@ -477,14 +493,22 @@ export class NativeSidecarKernelProxy {
                     return;
                 }
                 entry.pendingKillSignal = signal;
-                void entry.startPromise.then(async () => {
-                    if (entry.exitCode !== null || entry.pendingKillSignal === null) {
+                void entry.startPromise
+                    .then(async () => {
+                    if (entry.pendingKillSignal === null) {
                         return;
                     }
                     const pendingSignal = entry.pendingKillSignal;
                     entry.pendingKillSignal = null;
                     await this.signalProcess(entry, pendingSignal);
+                })
+                    .catch((error) => {
+                    this.handleBackgroundProcessError(entry, error);
                 });
+                if ((signal === 9 || signal === 15) &&
+                    entry.exitCode === null) {
+                    this.finishProcess(entry, 128 + signal);
+                }
             },
             wait: async () => {
                 const exitCode = await this.waitForTrackedProcess(entry);
@@ -506,7 +530,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 +589,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 +600,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 +645,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 +682,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 +841,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 +849,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 +907,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);
@@ -1128,15 +1151,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;
@@ -1307,9 +1321,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)) {
@@ -1524,12 +1556,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);
             },
         };
     }

package/dist/native-client.d.ts

@@ -1,9 +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";
+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;

package/dist/native-client.js

@@ -1,5 +1,5 @@
 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_EVENT_BUFFER_CAPACITY = 4_096;
@@ -18,9 +18,19 @@ export class StdioSidecarProtocolClient {
         this.gracefulExitMs = options.gracefulExitMs;
         this.forceExitMs = options.forceExitMs;
         this.disposedErrorMessage = options.disposedErrorMessage;
+        const transportOptions = this.sidecarProcess.combinedStdio
+            ? {
+                stdin: this.child.stdin,
+                stdout: this.child.stdout,
+                combinedStdio: true,
+            }
+            : {
+                stdin: this.child.stdin,
+                stdout: this.child.stdout,
+                control: this.sidecarProcess.control,
+            };
         this.protocolClient = new SidecarProtocolClient({
-            stdin: this.child.stdin,
-            stdout: this.child.stdout,
+            ...transportOptions,
             eventBufferCapacity: options.eventBufferCapacity,
             payloadCodec: options.payloadCodec,
             silenceTimeoutMs: options.silenceTimeoutMs,
@@ -52,14 +62,15 @@ export class StdioSidecarProtocolClient {
         });
     }
     static spawn(options = {}) {
+        const combinedStdio = typeof globalThis._childProcessSpawnStart !== "undefined";
         return new StdioSidecarProtocolClient(StdioSidecarProcess.spawn({
             command: options.command ?? resolvePublishedSidecarBinary(),
             args: options.args ?? [],
             cwd: options.cwd,
+            combinedStdio,
         }), {
             silenceTimeoutMs: options.silenceTimeoutMs,
-            eventBufferCapacity: options.eventBufferCapacity ??
-                DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,
+            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",
@@ -79,6 +90,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 {
@@ -88,6 +106,14 @@ export class StdioSidecarProtocolClient {
                 // Stdin may already be closing. The child exit watcher will catch up.
             }
         }
+        if (this.sidecarProcess.control && !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 {
@@ -117,11 +143,20 @@ 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) {
+        if (this.sidecarProcess.control) {
+            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,22 +20,22 @@
 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
- * the directory a real `npm install secure-exec` resolves: from the compiled
+ * the directory a real `npm install agentos` resolves: from the compiled
  * `dist/node-runtime.js` it sits at `<package>/commands`. This is the analogue
  * of how the sidecar binary ships inside `@rivet-dev/agentos-runtime-sidecar`.
  */
@@ -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) {
@@ -221,7 +222,7 @@ export class NodeRuntime {
      * `node <file>`; it runs as standard ESM (top-level `await`, `import`).
      */
     async exec(code, options = {}) {
-        const programPath = `/tmp/secure-exec-program-${nextProgramId++}.mjs`;
+        const programPath = `/tmp/agentos-program-${nextProgramId++}.mjs`;
         await this.kernel.writeFile(programPath, withBindingPreamble(code));
         return this.runProgram(programPath, options);
     }
@@ -327,7 +328,7 @@ export class NodeRuntime {
      * ```
      */
     async spawn(code, options = {}) {
-        const programPath = `/tmp/secure-exec-program-${nextProgramId++}.mjs`;
+        const programPath = `/tmp/agentos-program-${nextProgramId++}.mjs`;
         await this.kernel.writeFile(programPath, withBindingPreamble(code));
         const proc = this.kernel.spawn("node", [programPath], {
             env: options.env,
@@ -441,8 +442,8 @@ export class NodeRuntime {
      */
     async run(code, options = {}) {
         const id = nextProgramId++;
-        const resultPath = `/tmp/secure-exec-result-${id}.json`;
-        const programPath = `/tmp/secure-exec-program-${id}.mjs`;
+        const resultPath = `/tmp/agentos-result-${id}.json`;
+        const programPath = `/tmp/agentos-program-${id}.mjs`;
         // Inject the __return helper as a module-level preamble, then the user
         // code at module top level. Import declarations (preamble's and the
         // user's) are hoisted, so __return is defined before the user's
@@ -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,19 +1,23 @@
 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 {
     command: string;
     args?: string[];
     cwd?: string;
+    combinedStdio?: boolean;
 }
 export declare class StdioSidecarProcess {
     readonly child: ChildProcessWithoutNullStreams;
+    readonly control: Duplex | null;
+    readonly combinedStdio: boolean;
     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 | null): StdioSidecarProcess;
     onExit(handler: (error: SidecarProcessExited) => void): () => void;
     onError(handler: (error: SidecarProcessError) => void): () => void;
     stderrText(): string;

package/dist/process.js

@@ -1,13 +1,17 @@
-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;
+    combinedStdio;
     stderrChunks = [];
     exitListeners = new Set();
     errorListeners = new Set();
-    constructor(child) {
+    constructor(child, control) {
         this.child = child;
+        this.control = control;
+        this.combinedStdio = control === null;
         this.child.stderr.on("data", (chunk) => {
             this.stderrChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
         });
@@ -30,13 +34,26 @@ export class StdioSidecarProcess {
         });
     }
     static spawn(options) {
-        return new StdioSidecarProcess(spawn(options.command, options.args ?? [], {
+        const combinedStdio = options.combinedStdio === true;
+        const child = spawn(options.command, options.args ?? [], {
             cwd: options.cwd,
-            stdio: ["pipe", "pipe", "pipe"],
-        }));
+            env: combinedStdio
+                ? { ...process.env, AGENTOS_SIDECAR_COMBINED_STDIO: "1" }
+                : process.env,
+            stdio: combinedStdio
+                ? ["pipe", "pipe", "pipe"]
+                : ["pipe", "pipe", "pipe", "pipe"],
+        });
+        try {
+            return new StdioSidecarProcess(child, combinedStdio ? null : 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 === null ? null : (control ?? requireControlStream(child)));
     }
     onExit(handler) {
         this.exitListeners.add(handler);
@@ -95,3 +112,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;
+}