@rivet-dev/agentos-runtime-core 0.2.20-rc.1 → 0.2.21

package/dist/node-runtime.d.ts

@@ -17,13 +17,14 @@
  * isolation boundary — no host escapes, no real Node.js builtins for guest
  * work.
  */
-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 { HostFunctionCollections, HostFunctionSchemas } from "./host-functions.js";
 import type { SidecarProcess } from "./sidecar-process.js";
-export type { BindingDefinition, BindingExample, VirtualDirEntry, } from "./test-runtime.js";
+import type { KernelBootTiming, Permissions, VirtualDirEntry, VirtualFileSystem } from "./test-runtime.js";
+export type { HostFunctionExample, VirtualDirEntry, } from "./test-runtime.js";
 export { resolveNodeRuntimeSidecarBinary } from "./test-runtime.js";
-export type NodeRuntimeBootTimingPhase = KernelBootTiming["phase"] | "runtime_mount_wasm" | "runtime_mount_node" | "bindings";
+export type NodeRuntimeBootTimingPhase = KernelBootTiming["phase"] | "runtime_mount_wasm" | "runtime_mount_node" | "hostFunctions";
 export interface NodeRuntimeBootTiming {
     phase: NodeRuntimeBootTimingPhase;
     durationMs: number;
@@ -50,7 +51,7 @@ export declare function resolveNodeRuntimeCommandsDir(explicit?: string): string
  * Options that translate into sidecar VM JSON must also stay aligned with
  * `crates/vm-config/src/lib.rs::CreateVmConfig`.
  */
-export interface NodeRuntimeCreateOptions {
+export interface NodeRuntimeCreateOptions<HOST_FUNCTIONS extends HostFunctionSchemas = HostFunctionSchemas> {
     /**
      * Caller-owned filesystem used only by this low-level compatibility runtime.
      * AgentOS clients do not create a TypeScript filesystem implicitly; normal
@@ -64,12 +65,11 @@ export interface NodeRuntimeCreateOptions {
     /** 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);
-     * 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.
+     * Permission policy for the VM, merged over the sidecar's default: the
+     * virtual filesystem, processes, environment, bindings, listeners, and
+     * loopback networking work, while external network access is denied. A partial
+     * policy works: `{ network: "allow" }` grants external access and keeps every
+     * other scope at its default.
      */
     permissions?: Permissions;
     /**
@@ -163,41 +163,43 @@ export interface NodeRuntimeCreateOptions {
      */
     nodeModules?: string | NodeModulesMount;
     /**
-     * Host-side bindings 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 binding'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.
+     * Host-side functions the guest can invoke as shell commands, as a record of
+     * collections. The keys name everything: the collection key becomes the guest
+     * command `agentos-{name}` and each function key becomes one of its
+     * subcommands. When the guest runs it the invocation round-trips back to the
+     * host, runs the function's `execute`, and its 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 binding by name with JSON input:
+     * This is the same shape `AgentOs.create()` takes. A function needs only a
+     * Zod `inputSchema` and an `execute` handler; `.describe()` on the schema is
+     * what the agent reads.
      *
      * ```ts
      * const rt = await NodeRuntime.create({
-     *   bindings: {
-     *     add: {
-     *       description: "Add two numbers",
-     *       inputSchema: {
-     *         type: "object",
-     *         properties: { a: { type: "number" }, b: { type: "number" } },
-     *         required: ["a", "b"],
+     *   hostFunctions: {
+     *     math: {
+     *       add: {
+     *         inputSchema: z
+     *           .object({ a: z.number(), b: z.number() })
+     *           .describe("Add two numbers"),
+     *         execute: ({ a, b }) => ({ sum: 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 })]);
+     *   const out = execFileSync("agentos-math", ["add", "--json", JSON.stringify({ a: 2, b: 3 })]);
      *   console.log(out.toString());
      * `);
      * ```
      *
-     * When `bindings` is provided and no `binding` permission scope is set, the
-     * `binding` scope is granted so the registered bindings are invocable; pass
-     * your own `permissions.binding` policy to gate individual bindings.
+     * The `hostFunction` permission scope is allowed by default; pass your own
+     * `permissions.hostFunction` policy to gate individual host functions.
      */
-    bindings?: Record<string, BindingDefinition>;
+    hostFunctions?: HostFunctionCollections<HOST_FUNCTIONS>;
     /**
      * 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
@@ -449,7 +451,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<HOST_FUNCTIONS extends HostFunctionSchemas>(callerOptions: NodeRuntimeCreateOptions<HOST_FUNCTIONS>): Promise<NodeRuntime>;
     createResidentRunner(_options?: NodeRuntimeResidentRunnerOptions): Promise<NodeRuntimeResidentRunner>;
     /**
      * Run `code` as a guest Node program and capture its output.
@@ -571,19 +573,18 @@ export declare class NodeRuntime {
      */
     waitForListener(query: NodeRuntimeListenerQuery, options?: NodeRuntimeWaitForListenerOptions): Promise<NodeRuntimeListener>;
     /**
-     * Register host-side bindings the guest can invoke as shell commands, after
+     * Register host-side hostFunctions 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
-     * binding's `handler`, whose return value is delivered back to the guest. This
-     * is the same capability as the `bindings` create option, exposed for adding
-     * bindings to a live runtime. See `bindings` on {@link NodeRuntime.create} for
+     * hostFunction's `handler`, whose return value is delivered back to the guest. This
+     * is the same capability as the `hostFunctions` create option, exposed for adding
+     * host functions to a live runtime. See `hostFunctions` on {@link NodeRuntime.create} for
      * the invocation shape and permission behavior.
      *
-     * When registering bindings this way, make sure the `binding` permission scope
-     * is granted (for example `permissions: { binding: "allow" }` on
-     * {@link NodeRuntime.create}) so the bindings are invocable.
+     * The `hostFunction` permission scope is allowed by default, so these host
+     * functions are invocable unless the runtime's policy restricts them.
      */
-    registerBindings(bindings: Record<string, BindingDefinition>): Promise<void>;
+    registerHostFunctions(hostFunctions: HostFunctionCollections): 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

package/dist/node-runtime.js

@@ -20,8 +20,8 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { createKernel, createNodeRuntime, createWasmVmRuntime, NodeFileSystem, } from "./test-runtime.js";
 import { parseNodeRuntimeCreateOptions } from "./node-runtime-options-schema.js";
+import { createKernel, createNodeRuntime, createWasmVmRuntime, NodeFileSystem, } from "./test-runtime.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));
@@ -66,47 +66,30 @@ export function resolveNodeRuntimeCommandsDir(explicit) {
     }
     return BUNDLED_COMMANDS_DIR;
 }
-/**
- * Secure-by-default permission policy applied when the caller passes no
- * `permissions`. Outward-facing capabilities are denied: there is **no network
- * access** (and no host callbacks) by default — guest code cannot reach the
- * network until you opt in. The filesystem, child-process, process, and env
- * scopes are allowed because they are fully virtualized (the guest only ever
- * sees the VM's in-memory filesystem and kernel-managed processes, never the
- * real host) and are required for the runtime to execute a guest program at
- * all. Tighten or widen any scope by passing your own `permissions`.
- */
-const DEFAULT_PERMISSIONS = {
-    fs: "allow",
-    childProcess: "allow",
-    process: "allow",
-    env: "allow",
-    network: "deny",
-};
 /** Guest path a `nodeModules` mount is projected at by default. */
 const DEFAULT_NODE_MODULES_GUEST_PATH = "/tmp/node_modules";
 let nextProgramId = 0;
 let nextResidentRequestId = 0;
 /**
- * Guest preamble exposing `globalThis.callBinding(name, input?)`: an ergonomic
- * async wrapper over the binding invocation path. It runs the registered binding
- * as the guest would by hand (`<binding> --json <input>` through
+ * Guest preamble exposing `globalThis.callHostFunction(name, input?)`: an ergonomic
+ * async wrapper over the hostFunction invocation path. It runs the registered hostFunction
+ * as the guest would by hand (`<host-function> --json <input>` through
  * `node:child_process`), so it inherits every security property of that path:
- * the `binding` permission scope, the binding's input-schema validation, and the
+ * the `hostFunction` permission scope, the host function's input-schema validation, and the
  * host-side handler all still apply. It adds no new trust surface; it only
  * removes the manual `execFile`/JSON boilerplate so guest and agent code can do
- * `const out = await callBinding("add", { a, b })`. The value is a single line
+ * `const out = await callHostFunction("add", { a, b })`. The value is a single line
  * so it shifts guest source line numbers by at most one in stack traces.
  *
- * Note: the binding still runs through a guest process. Eliminating that spawn
- * would require a dedicated async guest-to-host binding channel (the synchronous
+ * Note: the hostFunction still runs through a guest process. Eliminating that spawn
+ * would require a dedicated async guest-to-host hostFunction channel (the synchronous
  * sync-RPC path cannot be used: it runs on the sidecar's main sync-RPC thread and
  * a host round-trip would block it); that is a separate, test-gated change.
  */
-const BINDING_PREAMBLE = `globalThis.callBinding = (name, input = {}) => import("node:child_process").then(({ execFile }) => new Promise((resolve, reject) => { execFile(name, [name, "--json", JSON.stringify(input)], { maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => { if (error) { reject(new Error(String(stderr || "").trim() || error.message)); return; } const text = String(stdout ?? "").trim(); let reply; try { reply = text ? JSON.parse(text) : undefined; } catch { reject(new Error("binding returned invalid JSON: " + text)); return; } if (reply && reply.ok === false) { reject(new Error(reply.error || "binding failed")); return; } resolve(reply && typeof reply === "object" && "result" in reply ? reply.result : reply); }); }));`;
-/** Prepend the binding helper preamble to guest program source. */
-function withBindingPreamble(code) {
-    return `${BINDING_PREAMBLE}\n${code}`;
+const HOST_FUNCTION_PREAMBLE = `globalThis.callHostFunction = (name, input = {}) => import("node:child_process").then(({ execFile }) => new Promise((resolve, reject) => { execFile(name, [name, "--json", JSON.stringify(input)], { maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => { if (error) { reject(new Error(String(stderr || "").trim() || error.message)); return; } const text = String(stdout ?? "").trim(); let reply; try { reply = text ? JSON.parse(text) : undefined; } catch { reject(new Error("host function returned invalid JSON: " + text)); return; } if (reply && reply.ok === false) { reject(new Error(reply.error || "host function failed")); return; } resolve(reply && typeof reply === "object" && "result" in reply ? reply.result : reply); }); }));`;
+/** Prepend the hostFunction helper preamble to guest program source. */
+function withHostFunctionPreamble(code) {
+    return `${HOST_FUNCTION_PREAMBLE}\n${code}`;
 }
 const RESIDENT_READY_PREFIX = "__AGENTOS_RESIDENT_READY__";
 const RESIDENT_RESULT_PREFIX = "__AGENTOS_RESIDENT_RESULT__";
@@ -128,8 +111,10 @@ 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) {
-        options = parseNodeRuntimeCreateOptions(options);
+    static async create(callerOptions) {
+        // The generic exists only so each `execute` infers its input from its own
+        // `inputSchema`; past this point the concrete schemas carry no meaning.
+        const options = parseNodeRuntimeCreateOptions(callerOptions);
         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
@@ -163,24 +148,12 @@ export class NodeRuntime {
             fs: new NodeFileSystem({ root: mount.hostPath }),
             readOnly: mount.readOnly ?? true,
         }));
-        // Grant the `binding` scope when the caller registers bindings but does not
-        // set their own binding policy, so the registered bindings are invocable.
-        const bindingDefaults = options.bindings &&
-            Object.keys(options.bindings).length > 0 &&
-            options.permissions?.binding === undefined
-            ? { binding: "allow" }
-            : {};
         const kernel = createKernel({
             filesystem,
             mounts: mounts.length > 0 ? mounts : undefined,
-            // Merge the caller's policy over the secure default so partial
-            // opt-ins work: `{ network: "allow" }` enables the network while the
-            // execution essentials (fs/childProcess/process/env) stay granted.
-            permissions: {
-                ...DEFAULT_PERMISSIONS,
-                ...bindingDefaults,
-                ...options.permissions,
-            },
+            // The sidecar owns the defaults and merges this policy over them, so
+            // only the scopes the caller set are sent.
+            permissions: options.permissions,
             env: options.env,
             cwd: options.cwd,
             user: options.user,
@@ -199,11 +172,11 @@ export class NodeRuntime {
                 commandDirs: [commandsDir, ...(options.wasmCommandDirs ?? [])],
             })));
             await measureBootTiming("runtime_mount_node", options.onBootTiming, () => kernel.mount(createNodeRuntime()));
-            // Register bindings after the runtimes are mounted so they are
+            // Register hostFunctions after the runtimes are mounted so they are
             // 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.registerBindings(bindings));
+            const hostFunctions = options.hostFunctions;
+            if (hostFunctions && Object.keys(hostFunctions).length > 0) {
+                await measureBootTiming("hostFunctions", options.onBootTiming, () => kernel.registerHostFunctions(hostFunctions));
             }
         }
         catch (error) {
@@ -223,7 +196,7 @@ export class NodeRuntime {
      */
     async exec(code, options = {}) {
         const programPath = `/tmp/agentos-program-${nextProgramId++}.mjs`;
-        await this.kernel.writeFile(programPath, withBindingPreamble(code));
+        await this.kernel.writeFile(programPath, withHostFunctionPreamble(code));
         return this.runProgram(programPath, options);
     }
     /**
@@ -329,7 +302,7 @@ export class NodeRuntime {
      */
     async spawn(code, options = {}) {
         const programPath = `/tmp/agentos-program-${nextProgramId++}.mjs`;
-        await this.kernel.writeFile(programPath, withBindingPreamble(code));
+        await this.kernel.writeFile(programPath, withHostFunctionPreamble(code));
         const proc = this.kernel.spawn("node", [programPath], {
             env: options.env,
             cwd: options.cwd,
@@ -453,7 +426,7 @@ export class NodeRuntime {
         // statements inside a function and make them a SyntaxError.
         const wrapped = [
             `import { writeFileSync as __writeFileSync } from "node:fs";`,
-            BINDING_PREAMBLE,
+            HOST_FUNCTION_PREAMBLE,
             `globalThis.__return = (value) => {`,
             `  __writeFileSync(${JSON.stringify(resultPath)}, JSON.stringify(value === undefined ? null : value));`,
             `};`,
@@ -576,20 +549,19 @@ export class NodeRuntime {
         }
     }
     /**
-     * Register host-side bindings the guest can invoke as shell commands, after
+     * Register host-side hostFunctions 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
-     * binding's `handler`, whose return value is delivered back to the guest. This
-     * is the same capability as the `bindings` create option, exposed for adding
-     * bindings to a live runtime. See `bindings` on {@link NodeRuntime.create} for
+     * hostFunction's `handler`, whose return value is delivered back to the guest. This
+     * is the same capability as the `hostFunctions` create option, exposed for adding
+     * host functions to a live runtime. See `hostFunctions` on {@link NodeRuntime.create} for
      * the invocation shape and permission behavior.
      *
-     * When registering bindings this way, make sure the `binding` permission scope
-     * is granted (for example `permissions: { binding: "allow" }` on
-     * {@link NodeRuntime.create}) so the bindings are invocable.
+     * The `hostFunction` permission scope is allowed by default, so these host
+     * functions are invocable unless the runtime's policy restricts them.
      */
-    async registerBindings(bindings) {
-        await this.kernel.registerBindings(bindings);
+    async registerHostFunctions(hostFunctions) {
+        await this.kernel.registerHostFunctions(hostFunctions);
     }
     /**
      * Write a file into the VM's virtual filesystem, creating parent

package/dist/permissions.d.ts

@@ -22,7 +22,7 @@ export interface LivePermissionsPolicy {
     child_process?: LivePermissionScope<LivePatternPermissionRule>;
     process?: LivePermissionScope<LivePatternPermissionRule>;
     env?: LivePermissionScope<LivePatternPermissionRule>;
-    binding?: LivePermissionScope<LivePatternPermissionRule>;
+    host_function?: LivePermissionScope<LivePatternPermissionRule>;
 }
 export declare function toGeneratedPermissionsPolicy(policy: LivePermissionsPolicy | undefined): protocol.PermissionsPolicy | null;
 export declare function toGeneratedFilesystemPermissionScope(scope: LivePermissionScope<LiveFsPermissionRule>): protocol.FsPermissionScope;

package/dist/permissions.js

@@ -19,9 +19,9 @@ export function toGeneratedPermissionsPolicy(policy) {
         env: policy.env === undefined
             ? null
             : toGeneratedPatternPermissionScope(policy.env),
-        binding: policy.binding === undefined
+        hostFunction: policy.host_function === undefined
             ? null
-            : toGeneratedPatternPermissionScope(policy.binding),
+            : toGeneratedPatternPermissionScope(policy.host_function),
     };
 }
 export function toGeneratedFilesystemPermissionScope(scope) {

package/dist/process.d.ts

@@ -12,7 +12,13 @@ export declare class StdioSidecarProcess {
     readonly child: ChildProcessWithoutNullStreams;
     readonly control: Duplex | null;
     readonly combinedStdio: boolean;
-    private readonly stderrChunks;
+    /** First bytes of sidecar stderr; the root cause usually appears here. */
+    private readonly stderrHead;
+    private stderrHeadBytes;
+    /** Most recent bytes of sidecar stderr; the fatal error appears here. */
+    private readonly stderrTail;
+    private stderrTailBytes;
+    private stderrDroppedBytes;
     private readonly exitListeners;
     private readonly errorListeners;
     private constructor();
@@ -20,6 +26,12 @@ export declare class StdioSidecarProcess {
     static fromChild(child: ChildProcessWithoutNullStreams, control?: Duplex | null): StdioSidecarProcess;
     onExit(handler: (error: SidecarProcessExited) => void): () => void;
     onError(handler: (error: SidecarProcessError) => void): () => void;
+    /**
+     * Retain the first STDERR_HEAD_MAX_BYTES and the most recent
+     * STDERR_TAIL_MAX_BYTES of sidecar stderr, counting everything in between
+     * as dropped.
+     */
+    private retainStderr;
     stderrText(): string;
     currentExitError(): SidecarProcessExited | null;
     waitForExit(timeoutMs: number): Promise<number | null>;

package/dist/process.js

@@ -1,19 +1,39 @@
 import { spawn } from "node:child_process";
 export { SidecarProcessError, SidecarProcessExited, } from "./sidecar-errors.js";
 import { SidecarProcessError, SidecarProcessExited } from "./sidecar-errors.js";
+/**
+ * Bounds on the sidecar stderr excerpt retained for SidecarProcessExited and
+ * SidecarProcessError. Live stderr is always forwarded to host stderr, so these
+ * bound only the postmortem copy. Sidecar diagnostics can be guest-triggered,
+ * so the retained copy must never grow without limit.
+ */
+const STDERR_HEAD_MAX_BYTES = 16 * 1024;
+const STDERR_TAIL_MAX_BYTES = 48 * 1024;
 export class StdioSidecarProcess {
     child;
     control;
     combinedStdio;
-    stderrChunks = [];
+    /** First bytes of sidecar stderr; the root cause usually appears here. */
+    stderrHead = [];
+    stderrHeadBytes = 0;
+    /** Most recent bytes of sidecar stderr; the fatal error appears here. */
+    stderrTail = [];
+    stderrTailBytes = 0;
+    stderrDroppedBytes = 0;
     exitListeners = new Set();
     errorListeners = new Set();
     constructor(child, control) {
         this.child = child;
         this.control = control;
         this.combinedStdio = control === null;
+        // Forward live sidecar stderr so warnings from a sidecar that survives a
+        // guest-triggered failure stay host-visible. This matches the Rust
+        // client, which spawns the sidecar with inherited stderr. Only a bounded
+        // excerpt is retained for exit/error reports.
         this.child.stderr.on("data", (chunk) => {
-            this.stderrChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+            process.stderr.write(buffer);
+            this.retainStderr(buffer);
         });
         this.child.on("exit", (code, signal) => {
             const error = new SidecarProcessExited({
@@ -67,8 +87,50 @@ export class StdioSidecarProcess {
             this.errorListeners.delete(handler);
         };
     }
+    /**
+     * Retain the first STDERR_HEAD_MAX_BYTES and the most recent
+     * STDERR_TAIL_MAX_BYTES of sidecar stderr, counting everything in between
+     * as dropped.
+     */
+    retainStderr(buffer) {
+        let rest = buffer;
+        const headRoom = STDERR_HEAD_MAX_BYTES - this.stderrHeadBytes;
+        if (headRoom > 0) {
+            const take = rest.subarray(0, headRoom);
+            this.stderrHead.push(take);
+            this.stderrHeadBytes += take.length;
+            rest = rest.subarray(take.length);
+        }
+        if (rest.length === 0)
+            return;
+        this.stderrTail.push(rest);
+        this.stderrTailBytes += rest.length;
+        while (this.stderrTailBytes > STDERR_TAIL_MAX_BYTES) {
+            const oldest = this.stderrTail[0];
+            const excess = this.stderrTailBytes - STDERR_TAIL_MAX_BYTES;
+            if (oldest.length <= excess) {
+                this.stderrTail.shift();
+                this.stderrTailBytes -= oldest.length;
+                this.stderrDroppedBytes += oldest.length;
+            }
+            else {
+                // Trim within the chunk so the bound holds for any chunking.
+                this.stderrTail[0] = oldest.subarray(excess);
+                this.stderrTailBytes -= excess;
+                this.stderrDroppedBytes += excess;
+            }
+        }
+    }
     stderrText() {
-        return Buffer.concat(this.stderrChunks).toString("utf8").trim();
+        const head = Buffer.concat(this.stderrHead).toString("utf8");
+        const tail = Buffer.concat(this.stderrTail).toString("utf8");
+        const gap = this.stderrDroppedBytes > 0
+            ? `\n... [${this.stderrDroppedBytes} bytes of sidecar stderr dropped; ` +
+                `retained the first ${STDERR_HEAD_MAX_BYTES} and last ` +
+                `${STDERR_TAIL_MAX_BYTES} bytes; the full output was forwarded ` +
+                `to host stderr] ...\n`
+            : "";
+        return `${head}${gap}${tail}`.trim();
     }
     currentExitError() {
         if (this.child.exitCode === null && this.child.signalCode === null) {

package/dist/request-payloads.d.ts

@@ -42,7 +42,7 @@ export type LiveRequestPayload = {
     packages?: LivePackageDescriptor[];
     packages_mount_at?: string;
     bootstrap_commands?: string[];
-    binding_shim_commands?: string[];
+    host_function_shim_commands?: string[];
 } | {
     type: "link_package";
     package: LivePackageDescriptor;

package/dist/request-payloads.js

@@ -58,7 +58,7 @@ export function toGeneratedRequestPayload(payload) {
                     packages: (payload.packages ?? []).map(toGeneratedPackageDescriptor),
                     packagesMountAt: payload.packages_mount_at ?? "",
                     bootstrapCommands: payload.bootstrap_commands ?? [],
-                    bindingShimCommands: payload.binding_shim_commands ?? [],
+                    hostFunctionShimCommands: payload.host_function_shim_commands ?? [],
                 },
             };
         case "link_package":

package/dist/sidecar-process.d.ts

@@ -176,7 +176,7 @@ export interface SidecarPermissionsPolicy {
     childProcess?: SidecarPermissionScope<SidecarPatternPermissionRule>;
     process?: SidecarPermissionScope<SidecarPatternPermissionRule>;
     env?: SidecarPermissionScope<SidecarPatternPermissionRule>;
-    binding?: SidecarPermissionScope<SidecarPatternPermissionRule>;
+    hostFunction?: SidecarPermissionScope<SidecarPatternPermissionRule>;
 }
 export interface SidecarProjectedModuleDescriptor {
     packageName: string;
@@ -247,7 +247,7 @@ export declare class SidecarProcess {
         packages?: SidecarPackageDescriptor[];
         packagesMountAt?: string;
         bootstrapCommands?: string[];
-        bindingShimCommands?: string[];
+        hostFunctionShimCommands?: string[];
     }): Promise<SidecarVmConfiguredResponse>;
     /**
      * Runtime dynamic `linkSoftware`: project one package into the live

package/dist/sidecar-process.js

@@ -147,7 +147,7 @@ export class SidecarProcess {
                     ? { packages_mount_at: options.packagesMountAt }
                     : {}),
                 bootstrap_commands: options.bootstrapCommands ?? [],
-                binding_shim_commands: options.bindingShimCommands ?? [],
+                host_function_shim_commands: options.hostFunctionShimCommands ?? [],
             },
         });
         if (response.payload.type !== "vm_configured") {
@@ -1074,7 +1074,7 @@ function toWirePermissionsPolicy(policy) {
         child_process: policy.childProcess,
         process: policy.process,
         env: policy.env,
-        binding: policy.binding,
+        host_function: policy.hostFunction,
     };
 }
 function toWireProjectedModuleDescriptor(descriptor) {

package/dist/test-runtime.d.ts

@@ -96,7 +96,7 @@ export type NetworkPermissions = PermissionMode | RulePermissions<PatternPermiss
 export type ChildProcessPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
 export type ProcessPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
 export type EnvPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
-export type BindingPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
+export type HostFunctionPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
 export interface ProcessInfo {
     pid: number;
     ppid: number;
@@ -185,43 +185,18 @@ export interface Permissions {
     childProcess?: ChildProcessPermissions;
     process?: ProcessPermissions;
     env?: EnvPermissions;
-    binding?: BindingPermissions;
-}
-/** A worked example shown alongside a registered binding. */
-export interface BindingExample {
-    /** What this example demonstrates. */
-    description: string;
-    /** Example input matching the binding's input schema. */
-    input: unknown;
+    hostFunction?: HostFunctionPermissions;
 }
 /**
- * A host-side binding that guest code can invoke as a shell command. The guest
- * runs the binding by name and the invocation round-trips back to the host JS
- * `handler`, whose return value is passed back to the guest. Bindings never run
+ * A host-side function that guest code can invoke as a shell command. The guest
+ * runs the host function by name and the invocation round-trips back to the host JS
+ * `handler`, whose return value is passed back to the guest. Host functions never run
  * inside the guest: they execute on the host, so they are the bridge for giving
  * sandboxed guest code controlled, named capabilities (the kind AI agents call
  * as tools).
  */
-export interface BindingDefinition {
-    /** Human-readable description of what the binding does. */
-    description: string;
-    /** JSON Schema describing the binding's input. */
-    inputSchema: object;
-    /** Abort the invocation after this many milliseconds. */
-    timeoutMs?: number;
-    /** Worked examples shown alongside the binding. */
-    examples?: BindingExample[];
-    /**
-     * Extra command names the guest can use to invoke this binding, in addition
-     * to the key it is registered under.
-     */
-    commandAliases?: string[];
-    /**
-     * Host handler invoked when guest code runs the binding. Receives the parsed
-     * input and returns a JSON-serializable result delivered back to the guest.
-     */
-    handler: (input: unknown) => unknown | Promise<unknown>;
-}
+import { type HostFunctionCollections } from "./host-functions.js";
+export type { HostFunction, HostFunctionCollection, HostFunctionCollections, HostFunctionExample, } from "./host-functions.js";
 export interface ResourceBudgets {
     maxOutputBytes?: number;
     maxBridgeCalls?: number;
@@ -347,7 +322,7 @@ export interface Kernel extends KernelInterface {
         streamId?: string;
         maxBytes?: number;
     }): Promise<string>;
-    registerBindings(bindings: Record<string, BindingDefinition>): Promise<void>;
+    registerHostFunctions(hostFunctions: HostFunctionCollections): Promise<void>;
     getResourceSnapshot(): Promise<{
         runningProcesses: number;
         exitedProcesses: number;
@@ -390,10 +365,10 @@ export interface Kernel extends KernelInterface {
     readonly timerTable: Record<string, never>;
     readonly zombieTimerCount: number;
 }
-export interface BindingTree {
-    [key: string]: BindingFunction | BindingTree;
+export interface HostFunctionTree {
+    [key: string]: HostFunctionHandler | HostFunctionTree;
 }
-export type BindingFunction = (...args: unknown[]) => unknown;
+export type HostFunctionHandler = (...args: unknown[]) => unknown;
 export interface ModuleAccessOptions {
     cwd?: string;
 }
@@ -415,7 +390,7 @@ export interface NodeRuntimeOptions {
     permissions?: Partial<Permissions>;
     memoryLimit?: number;
     moduleAccessPaths?: string[];
-    bindings?: BindingTree;
+    hostFunctions?: HostFunctionTree;
     loopbackExemptPorts?: number[];
     moduleAccessCwd?: string;
     packageRoots?: Array<{