@rivet-dev/agentos-runtime-core 0.2.8-rc.2 → 0.2.8-rc.3

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,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,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;
+}

package/dist/protocol-client.d.ts

@@ -1,13 +1,19 @@
 import type { Readable, Writable } from "node:stream";
 import { type LiveSidecarEventSelector } from "./event-buffer.js";
-import type { FrameTransport } from "./frame-stream.js";
-import { type LiveEventFrame, type LiveProtocolFrame, type LiveResponseFrame, type LiveSidecarRequestFrame, type LiveSidecarRequestHandler, type ProtocolFramePayloadCodec } from "./protocol-frames.js";
+import { type FrameTransport } from "./frame-stream.js";
 import type { LiveOwnershipScope } from "./ownership.js";
+import { type LiveControlFrame, type LiveEventFrame, type LiveProtocolFrame, type LiveRequestFrame, type LiveResponseFrame, type LiveSidecarRequestFrame, type LiveSidecarRequestHandler, type LiveSidecarResponseFrame, type ProtocolFramePayloadCodec } from "./protocol-frames.js";
 import type { LiveRequestPayload } from "./request-payloads.js";
 export interface SidecarProtocolClientOptions {
+    /** A combined transport remains supported for embedders and focused tests. */
     frameTransport?: FrameTransport<LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame, LiveProtocolFrame>;
+    ordinaryFrameTransport?: FrameTransport<LiveEventFrame, LiveRequestFrame>;
+    controlFrameTransport?: FrameTransport<LiveResponseFrame | LiveSidecarRequestFrame | LiveEventFrame, LiveSidecarResponseFrame | LiveControlFrame>;
     stdin?: Writable;
     stdout?: Readable;
+    control?: Readable & Writable;
+    /** Use one bidirectional stdin/stdout transport when the host cannot inherit fd 3. */
+    combinedStdio?: boolean;
     eventBufferCapacity: number;
     payloadCodec?: ProtocolFramePayloadCodec;
     stderrText?: () => string;
@@ -50,6 +56,7 @@ export declare class SidecarProtocolClient {
         ownership: LiveOwnershipScope;
         payload: LiveRequestPayload;
     }): Promise<LiveResponseFrame>;
+    shutdown(reason: string): Promise<void>;
     waitForEvent(matcher: LiveSidecarEventSelector | ((event: LiveEventFrame) => boolean), timeoutMs?: number, options?: {
         signal?: AbortSignal;
     }): Promise<LiveEventFrame>;

package/dist/protocol-client.js

@@ -1,7 +1,8 @@
-import { SidecarEventBuffer, SidecarEventBufferOverflow, normalizeSidecarEventMatcher, sidecarEventWaitAbortError, } from "./event-buffer.js";
+import { normalizeSidecarEventMatcher, SidecarEventBuffer, SidecarEventBufferOverflow, sidecarEventWaitAbortError, } from "./event-buffer.js";
 import { FrameRpcTransport } from "./frame-rpc.js";
-import { HostProtocolFrameFactory, classifySidecarWrittenProtocolFrame, decodeProtocolFramePayload, encodeProtocolFramePayload, resolveSidecarRequestFramePayload, } from "./protocol-frames.js";
-import { SidecarSilenceTimeout } from "./sidecar-errors.js";
+import { SplitLaneFrameTransport, StdioFrameTransport, } from "./frame-stream.js";
+import { classifySidecarWrittenProtocolFrame, decodeProtocolFramePayload, encodeProtocolFramePayload, HostProtocolFrameFactory, resolveSidecarRequestFramePayload, } from "./protocol-frames.js";
+import { SidecarRejectedError, SidecarSilenceTimeout, } from "./sidecar-errors.js";
 /**
  * How long the host tolerates TOTAL inbound silence (no responses, events,
  * sidecar requests, or heartbeats) before declaring the sidecar dead. The
@@ -30,9 +31,7 @@ export class SidecarProtocolClient {
         this.payloadCodec = options.payloadCodec ?? "bare";
         this.stderrText = options.stderrText ?? (() => "");
         this.frameTransport = new FrameRpcTransport({
-            frameTransport: options.frameTransport,
-            stdin: options.stdin,
-            stdout: options.stdout,
+            frameTransport: resolveProtocolFrameTransport(options, this.payloadCodec),
             encodeFrame: (frame) => encodeProtocolFramePayload(frame, this.payloadCodec),
             decodeFrame: (payload) => decodeProtocolFramePayload(payload, this.payloadCodec),
             classifyFrame: classifySidecarWrittenProtocolFrame,
@@ -109,10 +108,16 @@ export class SidecarProtocolClient {
         // wedged sidecar rejects this via the silence watchdog instead.
         const response = await this.frameTransport.sendFrame(request.request_id, request);
         if (response.payload.type === "rejected") {
-            throw new Error(`sidecar rejected request ${request.request_id}: ${response.payload.code}: ${response.payload.message}`);
+            throw new SidecarRejectedError(request.request_id, response.payload);
         }
         return response;
     }
+    async shutdown(reason) {
+        if (this.closedError) {
+            throw this.closedError;
+        }
+        await this.frameTransport.writeFrame(this.hostFrameFactory.createControlFrame({ type: "shutdown", reason }));
+    }
     async waitForEvent(matcher, timeoutMs, options) {
         if (this.closedError instanceof SidecarEventBufferOverflow) {
             throw this.closedError;
@@ -188,6 +193,20 @@ export class SidecarProtocolClient {
         await this.frameTransport.writeFrame(frame);
     }
     async dispatchSidecarRequest(request) {
+        // A callback can arrive immediately before the response that acknowledges
+        // the command which created it. Let the inbound decoder finish that turn
+        // before writing a callback response; otherwise a very fast host callback
+        // can complete and reap the guest process while its execute request is
+        // still being admitted, leaving the host waiting for an exit it missed.
+        await new Promise((resolve) => {
+            const scheduleImmediate = globalThis.setImmediate;
+            if (scheduleImmediate) {
+                scheduleImmediate(resolve);
+            }
+            else {
+                setTimeout(resolve, 0);
+            }
+        });
         const payload = await resolveSidecarRequestFramePayload(request, this.sidecarRequestHandler);
         try {
             await this.writeFrame(this.hostFrameFactory.createSidecarResponseFrame({
@@ -240,3 +259,104 @@ export class SidecarProtocolClient {
         this.eventWaiters.clear();
     }
 }
+function resolveProtocolFrameTransport(options, payloadCodec) {
+    const hasSplitTransport = options.ordinaryFrameTransport !== undefined ||
+        options.controlFrameTransport !== undefined;
+    const hasStdio = options.stdin !== undefined ||
+        options.stdout !== undefined ||
+        options.control !== undefined;
+    if (options.combinedStdio) {
+        if (options.frameTransport ||
+            hasSplitTransport ||
+            options.control !== undefined ||
+            !options.stdin ||
+            !options.stdout) {
+            throw new Error("SidecarProtocolClient combinedStdio requires only stdin and stdout streams");
+        }
+        return new StdioFrameTransport({
+            stdin: options.stdin,
+            stdout: options.stdout,
+            encodeFrame: (frame) => encodeProtocolFramePayload(frame, payloadCodec),
+            decodeFrame: (payload) => decodeProtocolFramePayload(payload, payloadCodec),
+        });
+    }
+    if (options.frameTransport) {
+        if (hasSplitTransport || hasStdio) {
+            throw new Error("SidecarProtocolClient frameTransport cannot be combined with split-lane transports or streams");
+        }
+        return options.frameTransport;
+    }
+    let ordinary = options.ordinaryFrameTransport;
+    let control = options.controlFrameTransport;
+    if (hasSplitTransport) {
+        if (!ordinary || !control || hasStdio) {
+            throw new Error("SidecarProtocolClient requires both ordinaryFrameTransport and controlFrameTransport, without stdio streams");
+        }
+    }
+    else {
+        if (!options.stdin || !options.stdout || !options.control) {
+            throw new Error("SidecarProtocolClient requires a combined frameTransport or stdin/stdout/control streams");
+        }
+        ordinary = new StdioFrameTransport({
+            stdin: options.stdin,
+            stdout: options.stdout,
+            encodeFrame: (frame) => encodeProtocolFramePayload(frame, payloadCodec),
+            decodeFrame: (payload) => {
+                const frame = decodeProtocolFramePayload(payload, payloadCodec);
+                validateOrdinaryInboundFrame(frame);
+                return frame;
+            },
+        });
+        control = new StdioFrameTransport({
+            stdin: options.control,
+            stdout: options.control,
+            encodeFrame: (frame) => encodeProtocolFramePayload(frame, payloadCodec),
+            decodeFrame: (payload) => {
+                const frame = decodeProtocolFramePayload(payload, payloadCodec);
+                validateControlInboundFrame(frame);
+                return frame;
+            },
+        });
+    }
+    return new SplitLaneFrameTransport({
+        ordinary,
+        control,
+        validateOrdinaryFrame: validateOrdinaryInboundFrame,
+        validateControlFrame: validateControlInboundFrame,
+        selectWriteLane: (frame) => {
+            switch (frame.frame_type) {
+                case "request":
+                    return "ordinary";
+                case "sidecar_response":
+                case "control":
+                    return "control";
+                default: {
+                    const invalidFrame = frame;
+                    throw new Error(`host frame ${invalidFrame.frame_type} is not valid on either writable protocol lane`);
+                }
+            }
+        },
+    });
+}
+function validateOrdinaryInboundFrame(frame) {
+    if (frame.frame_type !== "event") {
+        throw new Error(`sidecar frame ${frame.frame_type} is not valid on the ordinary protocol lane`);
+    }
+    if (isHeartbeatFrame(frame)) {
+        throw new Error("sidecar heartbeat event is not valid on the ordinary protocol lane");
+    }
+}
+function validateControlInboundFrame(frame) {
+    if (frame.frame_type === "response" ||
+        frame.frame_type === "sidecar_request") {
+        return;
+    }
+    if (frame.frame_type === "event" &&
+        isHeartbeatFrame(frame)) {
+        return;
+    }
+    throw new Error(`sidecar frame ${frame.frame_type} is not valid on the control protocol lane`);
+}
+function isHeartbeatFrame(frame) {
+    return (frame.payload.type === "structured" && frame.payload.name === "heartbeat");
+}

package/dist/protocol-frames.d.ts

@@ -1,7 +1,7 @@
-import { type TransportPayloadCodec } from "./frame-payload-codec.js";
-import type { ClassifiedFrame } from "./frame-rpc.js";
 import { type LiveSidecarRequestPayload, type LiveSidecarResponsePayload } from "./callbacks.js";
 import { type LiveSidecarEventPayload } from "./event-buffer.js";
+import { type TransportPayloadCodec } from "./frame-payload-codec.js";
+import type { ClassifiedFrame } from "./frame-rpc.js";
 import * as protocol from "./generated-protocol.js";
 import { type LiveOwnershipScope } from "./ownership.js";
 import { SIDECAR_PROTOCOL_SCHEMA } from "./protocol-schema.js";
@@ -41,7 +41,16 @@ export interface LiveSidecarResponseFrame {
     ownership: LiveOwnershipScope;
     payload: LiveSidecarResponsePayload;
 }
-export type LiveProtocolFrame = LiveRequestFrame | LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame | LiveSidecarResponseFrame;
+export type LiveControlPayload = {
+    type: "shutdown";
+    reason: string;
+};
+export interface LiveControlFrame {
+    frame_type: "control";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    payload: LiveControlPayload;
+}
+export type LiveProtocolFrame = LiveRequestFrame | LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame | LiveSidecarResponseFrame | LiveControlFrame;
 export type LiveSidecarWrittenProtocolFrame = LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame;
 export type ProtocolFramePayloadCodec = TransportPayloadCodec;
 export type ClassifiedSidecarWrittenProtocolFrame = ClassifiedFrame<LiveResponseFrame, LiveEventFrame, LiveSidecarRequestFrame>;
@@ -56,6 +65,7 @@ export declare class HostProtocolFrameFactory {
         request: LiveSidecarRequestFrame;
         payload: LiveSidecarResponsePayload;
     }): LiveSidecarResponseFrame;
+    createControlFrame(payload: LiveControlPayload): LiveControlFrame;
 }
 export declare function resolveSidecarRequestFramePayload(request: LiveSidecarRequestFrame, handler: LiveSidecarRequestHandler | null): Promise<LiveSidecarResponsePayload>;
 export declare function toGeneratedProtocolFrame(frame: LiveProtocolFrame): protocol.ProtocolFrame;
@@ -65,4 +75,5 @@ export declare function encodeProtocolFramePayload(frame: LiveProtocolFrame, cod
 export declare function decodeProtocolFramePayload(payload: Uint8Array, codec: ProtocolFramePayloadCodec): LiveSidecarWrittenProtocolFrame;
 export declare function classifySidecarWrittenProtocolFrame(frame: LiveSidecarWrittenProtocolFrame): ClassifiedSidecarWrittenProtocolFrame;
 export declare function fromGeneratedSidecarWrittenProtocolFrame(frame: protocol.ProtocolFrame): LiveSidecarWrittenProtocolFrame;
+export declare function toGeneratedControlPayload(payload: LiveControlPayload): protocol.ControlPayload;
 export declare function toLiveProtocolSchema(schema: protocol.ProtocolSchema): typeof SIDECAR_PROTOCOL_SCHEMA;

package/dist/protocol-frames.js

@@ -1,7 +1,7 @@
 import { toExactUint8Array } from "./bytes.js";
-import { decodeJsonFramePayload, encodeJsonFramePayload, } from "./frame-payload-codec.js";
 import { errorSidecarResponsePayload, fromGeneratedSidecarRequestPayload, isMatchingSidecarResponsePayload, toGeneratedSidecarResponsePayload, } from "./callbacks.js";
 import { fromGeneratedEventPayload, } from "./event-buffer.js";
+import { decodeJsonFramePayload, encodeJsonFramePayload, } from "./frame-payload-codec.js";
 import * as protocol from "./generated-protocol.js";
 import { bigIntToSafeNumber } from "./numbers.js";
 import { fromGeneratedOwnershipScope, toGeneratedOwnershipScope, } from "./ownership.js";
@@ -28,6 +28,13 @@ export class HostProtocolFrameFactory {
             payload: input.payload,
         };
     }
+    createControlFrame(payload) {
+        return {
+            frame_type: "control",
+            schema: SIDECAR_PROTOCOL_SCHEMA,
+            payload,
+        };
+    }
 }
 export async function resolveSidecarRequestFramePayload(request, handler) {
     try {
@@ -66,6 +73,14 @@ export function toGeneratedProtocolFrame(frame) {
                     payload: toGeneratedSidecarResponsePayload(frame.payload),
                 },
             };
+        case "control":
+            return {
+                tag: "ControlFrame",
+                val: {
+                    schema: frame.schema,
+                    payload: toGeneratedControlPayload(frame.payload),
+                },
+            };
         case "response":
         case "event":
         case "sidecar_request":
@@ -131,9 +146,19 @@ export function fromGeneratedSidecarWrittenProtocolFrame(frame) {
             };
         case "RequestFrame":
         case "SidecarResponseFrame":
+        case "ControlFrame":
             throw new Error(`unsupported BARE protocol frame tag: ${frame.tag}`);
     }
 }
+export function toGeneratedControlPayload(payload) {
+    switch (payload.type) {
+        case "shutdown":
+            return {
+                tag: "ShutdownControl",
+                val: { reason: payload.reason },
+            };
+    }
+}
 export function toLiveProtocolSchema(schema) {
     return validateSidecarProtocolSchema(schema);
 }