@rivet-dev/agentos-core 0.0.0-nathan-agentos-combined.e833bb7 → 0.2.0

package/dist/agent-os.d.ts

@@ -378,6 +378,7 @@ export declare class AgentOs {
     private _hostMounts;
     private _env;
     private _rootFilesystem;
+    private readonly _additionalInstructions;
     private _sidecarLease;
     private readonly _sidecarClient;
     private readonly _sidecarSession;

package/dist/agent-os.js

@@ -50,7 +50,7 @@ import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-
 import { createHostDirBackend } from "./host-dir-mount.js";
 import { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
-import { processSoftware, resolvePackageDir, } from "./packages.js";
+import { processSoftware, resolveAgentSnapshotBundle, resolvePackageDir, } from "./packages.js";
 import { allowAll } from "./runtime-compat.js";
 import { AcpRuntimeKind, decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
 import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
@@ -802,6 +802,16 @@ function collectSidecarMountPlan(options) {
     }
     for (const mount of options.mounts ?? []) {
         if (!isNativeMountConfig(mount)) {
+            sidecarMounts.push({
+                guestPath: mount.path,
+                readOnly: isOverlayMountConfig(mount)
+                    ? (mount.filesystem.mode ?? "ephemeral") === "read-only"
+                    : (mount.readOnly ?? false),
+                plugin: {
+                    id: "js_bridge",
+                    config: {},
+                },
+            });
             continue;
         }
         pushMount(mount);
@@ -1044,7 +1054,7 @@ async function handleHostCallback(request, context) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            error: `EACCES: blocked by tool.invoke policy for ${payload.callback_key}`,
+            error: `EACCES: blocked by binding.invoke policy for ${payload.callback_key}`,
         };
     }
     const parsed = tool.inputSchema.safeParse(payload.input);
@@ -1079,6 +1089,134 @@ function buildToolMap(toolKits) {
     }
     return toolMap;
 }
+function bridgeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function toBridgeArgs(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("js_bridge args must be an object");
+    }
+    return value;
+}
+function bridgePath(mountId, value) {
+    if (!mountId.startsWith("/")) {
+        throw new Error(`Unsupported js_bridge mount id: ${mountId}`);
+    }
+    if (typeof value !== "string") {
+        throw new Error("js_bridge path argument must be a string");
+    }
+    return posixPath.normalize(posixPath.join(mountId, value));
+}
+function requireBridgeNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`js_bridge args.${field} must be a number`);
+    }
+    return value;
+}
+function decodeBridgeBytes(value, field) {
+    if (typeof value === "string") {
+        return new Uint8Array(Buffer.from(value, "base64"));
+    }
+    if (Array.isArray(value) &&
+        value.every((entry) => Number.isInteger(entry) && entry >= 0 && entry <= 255)) {
+        return new Uint8Array(value);
+    }
+    throw new Error(`js_bridge args.${field} must be base64 bytes`);
+}
+async function handleJsBridgeCall(request, context) {
+    try {
+        const args = toBridgeArgs(request.args);
+        const fs = context.filesystem;
+        const path = () => bridgePath(request.mount_id, args.path);
+        let result;
+        switch (request.operation) {
+            case "readFile":
+                result = Buffer.from(await fs.readFile(path())).toString("base64");
+                break;
+            case "readDir":
+                result = await fs.readDir(path());
+                break;
+            case "readDirWithTypes":
+                result = await fs.readDirWithTypes(path());
+                break;
+            case "writeFile":
+                await fs.writeFile(path(), decodeBridgeBytes(args.content, "content"));
+                break;
+            case "createDir":
+                await fs.createDir(path());
+                break;
+            case "mkdir":
+                await fs.mkdir(path(), { recursive: args.recursive !== false });
+                break;
+            case "exists":
+                result = await fs.exists(path());
+                break;
+            case "stat":
+                result = await fs.stat(path());
+                break;
+            case "removeFile":
+                await fs.removeFile(path());
+                break;
+            case "removeDir":
+                await fs.removeDir(path());
+                break;
+            case "rename":
+                await fs.rename(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
+                break;
+            case "realpath":
+                result = await fs.realpath(path());
+                break;
+            case "symlink": {
+                if (typeof args.target !== "string") {
+                    throw new Error("js_bridge args.target must be a string");
+                }
+                await fs.symlink(args.target, bridgePath(request.mount_id, args.linkPath));
+                break;
+            }
+            case "readlink":
+                result = await fs.readlink(path());
+                break;
+            case "lstat":
+                result = await fs.lstat(path());
+                break;
+            case "link":
+                await fs.link(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
+                break;
+            case "chmod":
+                await fs.chmod(path(), requireBridgeNumber(args.mode, "mode"));
+                break;
+            case "chown":
+                await fs.chown(path(), requireBridgeNumber(args.uid, "uid"), requireBridgeNumber(args.gid, "gid"));
+                break;
+            case "utimes":
+                await fs.utimes(path(), requireBridgeNumber(args.atimeMs, "atimeMs"), requireBridgeNumber(args.mtimeMs, "mtimeMs"));
+                break;
+            case "truncate":
+                await fs.truncate(path(), requireBridgeNumber(args.length, "length"));
+                break;
+            case "pread":
+                result = Buffer.from(await fs.pread(path(), requireBridgeNumber(args.offset, "offset"), requireBridgeNumber(args.length, "length"))).toString("base64");
+                break;
+            case "pwrite":
+                await fs.pwrite(path(), requireBridgeNumber(args.offset, "offset"), decodeBridgeBytes(args.content, "content"));
+                break;
+            default:
+                throw new Error(`Unsupported js_bridge operation: ${request.operation}`);
+        }
+        return {
+            type: "js_bridge_result",
+            call_id: request.call_id,
+            ...(result === undefined ? {} : { result }),
+        };
+    }
+    catch (error) {
+        return {
+            type: "js_bridge_result",
+            call_id: request.call_id,
+            error: bridgeErrorMessage(error),
+        };
+    }
+}
 function parseHostCommandCallbackInput(input) {
     const value = asRecord(input);
     if (value.type !== "command" ||
@@ -1159,7 +1297,7 @@ async function invokeHostTool({ toolKit, toolName, args, cwd, context, }) {
     const callbackKey = `${toolKit.name}:${toolName}`;
     const permissionMode = toolPermissionMode(context.permissions, callbackKey);
     if (permissionMode !== "allow") {
-        throw new Error(`EACCES: blocked by tool.invoke policy for ${callbackKey}`);
+        throw new Error(`EACCES: blocked by binding.invoke policy for ${callbackKey}`);
     }
     const input = await parseHostToolInput(tool, args, cwd, context.readFile);
     return executeHostTool(tool, callbackKey, input);
@@ -1315,7 +1453,7 @@ function describeToolPayload(toolKit, toolName) {
     };
 }
 function toolPermissionMode(permissions, callbackKey) {
-    const scope = permissions.tool;
+    const scope = permissions.binding;
     if (!scope) {
         return "deny";
     }
@@ -1403,13 +1541,14 @@ export class AgentOs {
     _hostMounts;
     _env;
     _rootFilesystem;
+    _additionalInstructions;
     _sidecarLease = null;
     _sidecarClient;
     _sidecarSession;
     _sidecarVm;
     _disposeSidecarEventListener;
     _agentStderrHandler;
-    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, agentStderrHandler) {
+    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, agentStderrHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
         this._softwareRoots = softwareRoots;
@@ -1420,6 +1559,7 @@ export class AgentOs {
         this._sidecarClient = sidecarClient;
         this._sidecarSession = sidecarSession;
         this._sidecarVm = sidecarVm;
+        this._additionalInstructions = additionalInstructions;
         this._agentStderrHandler = agentStderrHandler;
         this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
             this._handleSidecarEvent(event);
@@ -1443,11 +1583,17 @@ export class AgentOs {
             ? (options.software ?? [])
             : [commonSoftware, ...(options?.software ?? [])];
         const processed = processSoftware(software);
+        // Agent-SDK snapshot bundle (loaded once per sidecar into the V8 startup
+        // snapshot, reused across sessions) for any snapshot-enabled agent.
+        const snapshotUserlandCode = resolveAgentSnapshotBundle(software);
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
         const toolKits = options?.toolKits;
         if (toolKits && toolKits.length > 0) {
             validateToolkits(toolKits);
         }
+        // Resolve the sidecar handle up front so every VM created here leases the
+        // one shared native sidecar process owned by that handle.
+        const sidecar = resolveAgentOsSidecar(options?.sidecar);
         const createVmAdmin = async () => {
             const preparedCommandDirs = prepareCommandDirs(processed.commandPackages);
             const toolBootstrapCommands = collectToolkitBootstrapCommands(toolKits ?? []);
@@ -1460,6 +1606,8 @@ export class AgentOs {
             let rootBridge = null;
             let kernel = null;
             let client = null;
+            let createdNativeVm = null;
+            let nativeSession = null;
             let toolShimDir = null;
             let cleanedUp = false;
             const cleanup = async () => {
@@ -1498,16 +1646,15 @@ export class AgentOs {
                     commandDirs: preparedCommandDirs.commandDirs,
                     shimDir: toolShimDir,
                 });
-                client = SidecarProcess.spawn({
-                    cwd: REPO_ROOT,
-                    command: ensureNativeSidecarBinary(),
-                    args: [],
-                    frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
-                });
-                const session = await client.authenticateAndOpenSession();
+                // Reuse the sidecar handle's single shared native process; this VM
+                // becomes another tenant of it rather than spawning its own process.
+                const shared = await ensureSharedSidecarNativeProcess(sidecar);
+                client = shared.client;
+                const session = shared.session;
+                nativeSession = session;
                 const hostPermissions = options?.permissions ?? {
                     ...allowAll,
-                    tool: "allow",
+                    binding: "allow",
                 };
                 const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
                 const createVmConfig = {
@@ -1522,12 +1669,18 @@ export class AgentOs {
                     // module resolution keep their engine defaults (full Node
                     // emulation), matching the prior behavior where Agent OS only
                     // constrained the builtin allow-list.
-                    ...(options?.allowedNodeBuiltins !== undefined
+                    ...(options?.allowedNodeBuiltins !== undefined ||
+                        snapshotUserlandCode !== undefined
                         ? {
                             jsRuntime: {
                                 platform: "node",
                                 moduleResolution: "node",
-                                allowedBuiltins: options.allowedNodeBuiltins,
+                                ...(options?.allowedNodeBuiltins !== undefined
+                                    ? { allowedBuiltins: options.allowedNodeBuiltins }
+                                    : {}),
+                                ...(snapshotUserlandCode !== undefined
+                                    ? { snapshotUserlandCode }
+                                    : {}),
                             },
                         }
                         : {}),
@@ -1536,8 +1689,13 @@ export class AgentOs {
                     runtime: "java_script",
                     config: createVmConfig,
                 });
+                createdNativeVm = nativeVm;
+                // Scope the readiness wait to THIS VM's ownership; on a shared process
+                // other VMs are emitting their own lifecycle events concurrently.
                 await client.waitForEvent((event) => event.payload.type === "vm_lifecycle" &&
-                    event.payload.state === "ready", 10_000);
+                    event.payload.state === "ready" &&
+                    event.ownership.scope === "vm" &&
+                    event.ownership.vm_id === nativeVm.vmId, 10_000);
                 await client.configureVm(session, nativeVm, {
                     mounts: sidecarMounts,
                     permissions: sidecarPermissions,
@@ -1558,8 +1716,15 @@ export class AgentOs {
                     env,
                     cwd: "/workspace",
                     localMounts,
+                    sidecarMounts,
+                    permissions: sidecarPermissions,
+                    commandPermissions: processed.commandPermissions,
+                    loopbackExemptPorts: options?.loopbackExemptPorts,
                     commandGuestPaths,
                     onDispose: cleanup,
+                    // The native process is owned by the AgentOsSidecar handle and
+                    // shared across VMs; disposing this VM must not kill the process.
+                    ownsClient: false,
                 });
                 await bootstrapLiveBootstrapDirectories(client, session, nativeVm, options?.rootFilesystem);
                 kernel = rootBridge;
@@ -1569,6 +1734,10 @@ export class AgentOs {
                     hostMounts,
                     kernel,
                     rootView: rootBridge.createRootView(),
+                    sidecarMounts,
+                    sidecarPermissions,
+                    commandPermissions: processed.commandPermissions,
+                    loopbackExemptPorts: options?.loopbackExemptPorts,
                     sidecarClient: client,
                     sidecarSession: session,
                     sidecarVm: nativeVm,
@@ -1593,6 +1762,8 @@ export class AgentOs {
                 };
             }
             catch (error) {
+                // The native process is shared and owned by the sidecar handle, so
+                // never dispose the client here — only tear down this VM's resources.
                 if (kernel) {
                     await kernel.dispose().catch(() => { });
                 }
@@ -1600,20 +1771,23 @@ export class AgentOs {
                     await rootBridge.dispose().catch(() => { });
                 }
                 else {
-                    await client?.dispose().catch(() => { });
+                    if (createdNativeVm && nativeSession && client) {
+                        await client
+                            .disposeVm(nativeSession, createdNativeVm)
+                            .catch(() => { });
+                    }
                     await cleanup();
                 }
                 throw error;
             }
         };
-        const sidecar = resolveAgentOsSidecar(options?.sidecar);
         let sidecarLease = null;
         try {
             sidecarLease = await leaseAgentOsSidecarVm(sidecar, {
                 createVm: async () => createVmAdmin(),
             });
             const vmAdmin = sidecarLease.admin;
-            const vm = new AgentOs(vmAdmin.kernel, sidecar, processed.softwareRoots, processed.agentConfigs, vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.onAgentStderr ?? defaultAgentStderrHandler);
+            const vm = new AgentOs(vmAdmin.kernel, sidecar, processed.softwareRoots, processed.agentConfigs, vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.additionalInstructions, options?.onAgentStderr ?? defaultAgentStderrHandler);
             vm._sidecarLease = sidecarLease;
             vm._toolKits = vmAdmin.toolKits;
             vm._toolReference = vmAdmin.toolReference;
@@ -1929,7 +2103,7 @@ export class AgentOs {
     }
     async delete(path, options) {
         this._assertSafeAbsolutePath(path);
-        const s = await this.#kernel.stat(path);
+        const s = await this._vfs().lstat(path);
         if (s.isDirectory) {
             if (options?.recursive) {
                 const entries = await this.#kernel.readdir(path);
@@ -2585,7 +2759,10 @@ export class AgentOs {
                 mcpServers: JSON.stringify(options?.mcpServers ?? []),
                 protocolVersion: ACP_PROTOCOL_VERSION,
                 clientCapabilities: JSON.stringify(defaultAcpClientCapabilities()),
-                additionalInstructions: combineInstructions(options?.additionalInstructions, this._toolReference),
+                additionalInstructions: combineInstructions([this._additionalInstructions, options?.additionalInstructions]
+                    .map((part) => part?.trim())
+                    .filter((part) => Boolean(part))
+                    .join("\n\n") || undefined, this._toolReference),
                 skipOsInstructions: options?.skipOsInstructions ?? false,
             },
         });
@@ -2672,6 +2849,10 @@ export class AgentOs {
         }
         const { sessionId: liveSessionId, mode } = response.val;
         // Register + hydrate the live session so subsequent prompts route to it.
+        const existing = this._sessions.get(liveSessionId);
+        if (existing !== undefined && !existing.closed) {
+            throw new Error(`session id collision: ${liveSessionId}`);
+        }
         const session = sessionEntryFromInit(liveSessionId, String(agentType), {});
         this._closedSessionIds.delete(liveSessionId);
         this._sessions.set(liveSessionId, session);
@@ -2755,11 +2936,7 @@ export class AgentOs {
                 case "host_callback":
                     return handleHostCallback(request, context);
                 case "js_bridge_call":
-                    return Promise.resolve({
-                        type: "js_bridge_result",
-                        call_id: request.payload.call_id,
-                        error: `unsupported sidecar request type: ${request.payload.type}`,
-                    });
+                    return handleJsBridgeCall(request.payload, { filesystem: this.#kernel.vfs });
                 case "ext":
                     return this._handleAcpExtSidecarRequest(request.payload.envelope);
             }
@@ -3476,6 +3653,42 @@ function resolveAgentOsSidecar(config) {
 }
 const sidecarStates = new WeakMap();
 const sharedSidecars = new Map();
+/**
+ * Spawn-once accessor for a sidecar handle's shared native process. Concurrent
+ * callers await the same promise, so one `AgentOsSidecar` maps to exactly one
+ * `agent-os-sidecar` OS process for its whole lifetime.
+ */
+function ensureSharedSidecarNativeProcess(sidecar) {
+    const state = getSidecarState(sidecar);
+    if (!state.nativeProcess) {
+        state.nativeProcess = (async () => {
+            const client = SidecarProcess.spawn({
+                cwd: REPO_ROOT,
+                command: ensureNativeSidecarBinary(),
+                args: [],
+                frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
+            });
+            const session = await client.authenticateAndOpenSession();
+            return { client, session };
+        })();
+    }
+    return state.nativeProcess;
+}
+/** Dispose a sidecar handle's shared native process, if one was spawned. */
+async function disposeSharedSidecarNativeProcess(state) {
+    const pending = state.nativeProcess;
+    if (!pending) {
+        return;
+    }
+    state.nativeProcess = undefined;
+    try {
+        const { client } = await pending;
+        await client.dispose();
+    }
+    catch {
+        // Process may have already exited; nothing to reclaim.
+    }
+}
 export class AgentOsSidecar {
     constructor(sidecarId, placement, sharedPool) {
         sidecarStates.set(this, {
@@ -3510,6 +3723,8 @@ export class AgentOsSidecar {
         }
         state.activeLeases.clear();
         state.description.activeVmCount = 0;
+        // Tear down the shared native process after all leased VMs are gone.
+        await disposeSharedSidecarNativeProcess(state);
         state.description.state = "disposed";
         if (state.sharedPool && sharedSidecars.get(state.sharedPool) === this) {
             sharedSidecars.delete(state.sharedPool);

package/dist/host-tools.js

@@ -8,16 +8,25 @@ export function hostTool(def) {
 export function toolKit(def) {
     return def;
 }
+const TOOLKIT_COMMAND_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function validateToolCommandName(kind, name) {
+    if (TOOLKIT_COMMAND_NAME_RE.test(name)) {
+        return;
+    }
+    throw new Error(`${kind} name "${name}" must be lowercase alphanumeric with optional single hyphen separators`);
+}
 /**
  * Validate all description lengths in the given toolkits.
  * Throws if any toolkit or tool description exceeds MAX_TOOL_DESCRIPTION_LENGTH.
  */
 export function validateToolkits(toolKits) {
     for (const tk of toolKits) {
+        validateToolCommandName("Toolkit", tk.name);
         if (tk.description.length > MAX_TOOL_DESCRIPTION_LENGTH) {
             throw new Error(`Toolkit "${tk.name}" description is ${tk.description.length} characters, max is ${MAX_TOOL_DESCRIPTION_LENGTH}`);
         }
         for (const [toolName, tool] of Object.entries(tk.tools)) {
+            validateToolCommandName("Tool", toolName);
             if (tool.description.length > MAX_TOOL_DESCRIPTION_LENGTH) {
                 throw new Error(`Tool "${tk.name}/${toolName}" description is ${tool.description.length} characters, max is ${MAX_TOOL_DESCRIPTION_LENGTH}`);
             }

package/dist/options-schema.d.ts

@@ -87,7 +87,7 @@ export declare const permissionsSchema: z.ZodObject<{
             patterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
     }, z.core.$strict>]>>;
-    tool: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+    binding: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
         allow: "allow";
         deny: "deny";
     }>, z.ZodObject<{
@@ -344,7 +344,7 @@ export declare const agentOsOptionFieldSchemas: {
                 patterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
         }, z.core.$strict>]>>;
-        tool: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        binding: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
             allow: "allow";
             deny: "deny";
         }>, z.ZodObject<{

package/dist/options-schema.js

@@ -42,7 +42,7 @@ export const permissionsSchema = z
     childProcess: patternPermissionsSchema.optional(),
     process: patternPermissionsSchema.optional(),
     env: patternPermissionsSchema.optional(),
-    tool: patternPermissionsSchema.optional(),
+    binding: patternPermissionsSchema.optional(),
 })
     .strict();
 export const agentOsLimitsSchema = z

package/dist/packages.d.ts

@@ -25,6 +25,19 @@ export interface AgentSoftwareDescriptor extends SoftwareDescriptor {
         acpAdapter: string;
         /** npm package name of the agent CLI. Must be in requires. */
         agentPackage: string;
+        /**
+         * Whether to evaluate this agent's SDK into the per-sidecar V8 heap
+         * snapshot so it is loaded once per sidecar and reused across sessions
+         * (instead of re-evaluated on every `createSession`). Opt-in: the agent's
+         * SDK must be **snapshot-safe** — its module-init must not create native
+         * (`.node` addon / WASM / External) handles, open fds/sockets, start
+         * timers, read per-session config, or leave pending promises. SDKs that
+         * are not snapshot-safe (or where snapshot creation fails) automatically
+         * fall back to the per-session dynamic-import path, so this flag is a
+         * safety/performance switch, not a correctness requirement. Defaults to
+         * `false`. See the Custom Agents / dependencies docs for the full rules.
+         */
+        snapshot?: boolean;
         /** Static env vars passed when spawning the adapter. */
         staticEnv?: Record<string, string>;
         /** Dynamic env vars computed at boot time. */
@@ -103,6 +116,15 @@ export interface CommandPackageMetadata {
  * validates the descriptor shape at compile time.
  */
 export declare function defineSoftware<T extends AnySoftwareDescriptor>(desc: T): T;
+/**
+ * Resolve the agent-SDK snapshot bundle (an esbuild IIFE at
+ * `<packageDir>/dist/sdk-snapshot.js`) for the first snapshot-enabled agent in
+ * the software set. Returns its source so it can be evaluated once into the
+ * per-sidecar V8 startup snapshot (`jsRuntime.snapshotUserlandCode`) and reused
+ * across sessions. Returns `undefined` when no agent opts in (`agent.snapshot`)
+ * or the bundle is absent — the runtime then keeps the per-session import path.
+ */
+export declare function resolveAgentSnapshotBundle(software: SoftwareInput[]): string | undefined;
 /** Result of processing all software descriptors at boot time. */
 export interface ProcessedSoftware {
     /** WASM command directories to pass to the WasmVM driver. */

package/dist/packages.js

@@ -118,6 +118,29 @@ function createSoftwareContext(packageDir, requires) {
 export function defineSoftware(desc) {
     return desc;
 }
+/**
+ * Resolve the agent-SDK snapshot bundle (an esbuild IIFE at
+ * `<packageDir>/dist/sdk-snapshot.js`) for the first snapshot-enabled agent in
+ * the software set. Returns its source so it can be evaluated once into the
+ * per-sidecar V8 startup snapshot (`jsRuntime.snapshotUserlandCode`) and reused
+ * across sessions. Returns `undefined` when no agent opts in (`agent.snapshot`)
+ * or the bundle is absent — the runtime then keeps the per-session import path.
+ */
+export function resolveAgentSnapshotBundle(software) {
+    const descriptors = software.flat();
+    for (const desc of descriptors) {
+        if (desc.type !== "agent")
+            continue;
+        const agent = desc;
+        if (!agent.agent.snapshot)
+            continue;
+        const bundlePath = join(agent.packageDir, "dist", "sdk-snapshot.js");
+        if (existsSync(bundlePath)) {
+            return readFileSync(bundlePath, "utf-8");
+        }
+    }
+    return undefined;
+}
 /** Check if a descriptor is a typed software descriptor (has a `type` field). */
 function isTypedDescriptor(desc) {
     return ("type" in desc && typeof desc.type === "string");
@@ -270,6 +293,10 @@ export function processSoftware(software) {
         if (!isTypedDescriptor(pkg)) {
             // Duck-typed: any object with commandDir is a WASM command source.
             const commandMetadata = collectCommandMetadata(pkg);
+            if (!existsSync(commandMetadata.commandDir)) {
+                console.warn(`[agentos] skipping WASM command source with missing commandDir: ${commandMetadata.commandDir} (build its wasm artifacts to enable these commands)`);
+                continue;
+            }
             commandDirs.push(commandMetadata.commandDir);
             commandPackages.push(commandMetadata);
             collectRegistryPackagePermissions(commandPermissions, pkg);
@@ -278,6 +305,10 @@ export function processSoftware(software) {
         switch (pkg.type) {
             case "wasm-commands": {
                 const commandMetadata = collectCommandMetadata(pkg);
+                if (!existsSync(commandMetadata.commandDir)) {
+                    console.warn(`[agentos] skipping WASM command source with missing commandDir: ${commandMetadata.commandDir} (build its wasm artifacts to enable these commands)`);
+                    break;
+                }
                 commandDirs.push(commandMetadata.commandDir);
                 commandPackages.push(commandMetadata);
                 collectTypedDescriptorPermissions(commandPermissions, pkg);

package/dist/runtime-compat.d.ts

@@ -81,7 +81,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 ToolPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
+export type BindingPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
 export interface ProcessInfo {
     pid: number;
     ppid: number;
@@ -168,7 +168,7 @@ export interface Permissions {
     childProcess?: ChildProcessPermissions;
     process?: ProcessPermissions;
     env?: EnvPermissions;
-    tool?: ToolPermissions;
+    binding?: BindingPermissions;
 }
 export interface ResourceBudgets {
     maxOutputBytes?: number;

package/dist/runtime-compat.js

@@ -119,7 +119,7 @@ export class InMemoryFileSystem {
             throw errnoError("ENOENT", `open '${targetPath}'`);
         }
         entry.atimeMs = Date.now();
-        return entry.data;
+        return new Uint8Array(entry.data);
     }
     async readTextFile(targetPath) {
         return new TextDecoder().decode(await this.readFile(targetPath));
@@ -152,7 +152,9 @@ export class InMemoryFileSystem {
     async writeFile(targetPath, content) {
         const normalized = normalizePath(targetPath);
         await this.mkdir(dirnameVirtual(normalized), { recursive: true });
-        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        const data = typeof content === "string"
+            ? new TextEncoder().encode(content)
+            : new Uint8Array(content);
         const existing = this.entries.get(normalized);
         if (existing?.type === "file") {
             existing.data = data;
@@ -212,7 +214,7 @@ export class InMemoryFileSystem {
         return this.toStat(entry);
     }
     async removeFile(targetPath) {
-        const resolved = this.resolvePath(targetPath);
+        const resolved = normalizePath(targetPath);
         const entry = this.entries.get(resolved);
         if (!entry || entry.type === "dir") {
             throw errnoError("ENOENT", `unlink '${targetPath}'`);
@@ -374,7 +376,7 @@ export class InMemoryFileSystem {
         const nextSize = Math.max(entry.data.length, offset + data.length);
         const updated = new Uint8Array(nextSize);
         updated.set(entry.data);
-        updated.set(data, offset);
+        updated.set(new Uint8Array(data), offset);
         entry.data = updated;
         entry.mtimeMs = Date.now();
         entry.ctimeMs = Date.now();
@@ -1607,6 +1609,35 @@ function bindLiveFilesystem(target, getFilesystem) {
         },
     };
 }
+function serializeLocalCompatMountForSidecar(mount) {
+    return (mount.sidecarMount ??
+        (mount.fs instanceof NodeFileSystem
+            ? serializeMountConfigForSidecar({
+                path: mount.path,
+                readOnly: mount.readOnly,
+                plugin: {
+                    id: "host_dir",
+                    config: {
+                        hostPath: mount.fs.rootPath,
+                        readOnly: mount.readOnly,
+                    },
+                },
+            })
+            : serializeMountConfigForSidecar({
+                path: mount.path,
+                driver: mount.fs,
+                readOnly: mount.readOnly,
+            })));
+}
+function makeLocalCompatMount(options) {
+    const localMount = {
+        path: normalizePath(options.path),
+        fs: options.fs,
+        readOnly: options.readOnly ?? false,
+    };
+    localMount.sidecarMount = serializeLocalCompatMountForSidecar(localMount);
+    return localMount;
+}
 class NativeKernel {
     options;
     env;
@@ -1646,11 +1677,11 @@ class NativeKernel {
         };
         this.loopbackExemptPorts = [...(options.loopbackExemptPorts ?? [])];
         for (const mount of options.mounts ?? []) {
-            this.pendingLocalMounts.push({
-                path: normalizePath(mount.path),
+            this.pendingLocalMounts.push(makeLocalCompatMount({
+                path: mount.path,
                 fs: mount.fs,
-                readOnly: mount.readOnly ?? false,
-            });
+                readOnly: mount.readOnly,
+            }));
         }
         this.vfs = new DeferredFileSystem(() => this.rootFilesystem);
         this.liveFilesystemBinding = bindLiveFilesystem(this.options.filesystem, () => this.rootFilesystem);
@@ -1696,23 +1727,7 @@ class NativeKernel {
                 },
             },
         }));
-        const localMounts = this.pendingLocalMounts.map((mount) => mount.fs instanceof NodeFileSystem
-            ? serializeMountConfigForSidecar({
-                path: mount.path,
-                readOnly: mount.readOnly,
-                plugin: {
-                    id: "host_dir",
-                    config: {
-                        hostPath: mount.fs.rootPath,
-                        readOnly: mount.readOnly,
-                    },
-                },
-            })
-            : serializeMountConfigForSidecar({
-                path: mount.path,
-                driver: mount.fs,
-                readOnly: mount.readOnly,
-            }));
+        const localMounts = this.pendingLocalMounts.map((mount) => serializeLocalCompatMountForSidecar(mount));
         await this.client.configureVm(this.session, this.vm, {
             mounts: [...localMounts, ...sidecarMounts],
             loopbackExemptPorts: this.loopbackExemptPorts,
@@ -1818,17 +1833,27 @@ class NativeKernel {
         return this.proxy.connectTerminal(options);
     }
     mountFs(mountPath, filesystem, options) {
+        const localMount = makeLocalCompatMount({
+            path: mountPath,
+            fs: filesystem,
+            readOnly: options?.readOnly,
+        });
+        this.pendingLocalMounts.unshift(localMount);
+        this.pendingLocalMounts.sort((left, right) => right.path.length - left.path.length);
         if (!this.proxy) {
-            this.pendingLocalMounts.push({
-                path: normalizePath(mountPath),
-                fs: filesystem,
-                readOnly: options?.readOnly ?? false,
-            });
             return;
         }
-        this.proxy.mountFs(mountPath, filesystem, options);
+        this.proxy.mountFs(mountPath, filesystem, {
+            readOnly: localMount.readOnly,
+            sidecarMount: localMount.sidecarMount,
+        });
     }
     unmountFs(mountPath) {
+        const normalized = normalizePath(mountPath);
+        const pendingIndex = this.pendingLocalMounts.findIndex((mount) => mount.path === normalized);
+        if (pendingIndex >= 0) {
+            this.pendingLocalMounts.splice(pendingIndex, 1);
+        }
         this.proxy?.unmountFs(mountPath);
     }
     async readFile(targetPath) {
@@ -1955,33 +1980,23 @@ class NativeKernel {
             await materializeSnapshotEntriesIntoVm(client, session, vm, snapshotEntries);
         }
         if (rootPassthroughPlan.mounts.length > 0) {
-            this.pendingLocalMounts.push(...rootPassthroughPlan.mounts);
+            this.pendingLocalMounts.push(...rootPassthroughPlan.mounts.map((mount) => makeLocalCompatMount({
+                path: mount.path,
+                fs: mount.fs,
+                readOnly: mount.readOnly,
+            })));
         }
         if (this.pendingLocalMounts.length > 0 ||
             this.loopbackExemptPorts.length > 0 ||
             requestedPermissions) {
+            const sidecarMounts = this.pendingLocalMounts.map((mount) => serializeLocalCompatMountForSidecar(mount));
             await client.configureVm(session, vm, {
-                mounts: this.pendingLocalMounts.map((mount) => mount.fs instanceof NodeFileSystem
-                    ? serializeMountConfigForSidecar({
-                        path: mount.path,
-                        readOnly: mount.readOnly,
-                        plugin: {
-                            id: "host_dir",
-                            config: {
-                                hostPath: mount.fs.rootPath,
-                                readOnly: mount.readOnly,
-                            },
-                        },
-                    })
-                    : serializeMountConfigForSidecar({
-                        path: mount.path,
-                        driver: mount.fs,
-                        readOnly: mount.readOnly,
-                    })),
+                mounts: sidecarMounts,
                 permissions: requestedPermissions,
                 loopbackExemptPorts: this.loopbackExemptPorts,
             });
         }
+        const configuredSidecarMounts = this.pendingLocalMounts.map((mount) => serializeLocalCompatMountForSidecar(mount));
         const proxy = new NativeSidecarKernelProxy({
             client,
             session,
@@ -1990,6 +2005,9 @@ class NativeKernel {
             cwd: this.cwd,
             defaultExecCwd: this.options.cwd === undefined ? "/workspace" : this.cwd,
             localMounts: this.pendingLocalMounts,
+            sidecarMounts: configuredSidecarMounts,
+            permissions: requestedPermissions,
+            loopbackExemptPorts: this.loopbackExemptPorts,
             commandGuestPaths: new Map(),
             onWasmCommandResolved: (command) => {
                 this.recordModuleExecution(command);

package/dist/runtime.d.ts

@@ -76,7 +76,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 ToolPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
+export type BindingPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
 export interface ProcessInfo {
     pid: number;
     ppid: number;
@@ -163,7 +163,7 @@ export interface Permissions {
     childProcess?: ChildProcessPermissions;
     process?: ProcessPermissions;
     env?: EnvPermissions;
-    tool?: ToolPermissions;
+    binding?: BindingPermissions;
 }
 export interface ResourceBudgets {
     maxOutputBytes?: number;

package/dist/sidecar/native-process-client.d.ts

@@ -1,3 +1,5 @@
 import "@secure-exec/core/native-client";
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarProcess as NativeSidecarProcessClient, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "@secure-exec/core/sidecar-client";
+import { SidecarProcess } from "@secure-exec/core/sidecar-client";
+export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarEventBufferOverflow, SidecarProcess, SidecarProcessError, SidecarProcessExited, } from "@secure-exec/core/sidecar-client";
+export declare const NativeSidecarProcessClient: typeof SidecarProcess;
 export type { AuthenticatedSession, CreatedVm, ExtEnvelope, GuestFilesystemStat, RootFilesystemEntry, RootFilesystemLowerDescriptor, SidecarEventSelector, SidecarFsPermissionRule, SidecarMountDescriptor, SidecarMountPluginDescriptor, SidecarPatternPermissionRule, SidecarPermissionMode, SidecarPermissionScope, SidecarPermissionsPolicy, SidecarProcessSnapshotEntry, SidecarProjectedModuleDescriptor, SidecarRegisteredHostCallbackDefinition, SidecarRegisteredHostCallbackExample, SidecarRequestFrame, SidecarRequestHandler, SidecarRequestPayload, SidecarResponseFrame, SidecarResponsePayload, SidecarRulePermissions, SidecarSessionState, SidecarSignalHandlerRegistration, SidecarSignalState, SidecarSocketStateEntry, SidecarSoftwareDescriptor, SidecarSpawnOptions, SidecarSpawnOptions as NativeSidecarSpawnOptions, SidecarZombieTimerCount, } from "@secure-exec/core/sidecar-client";

package/dist/sidecar/native-process-client.js

@@ -3,4 +3,6 @@
 // separately-registered factory; importing native-client wires it up so
 // SidecarProcess.spawn works in this native runtime.
 import "@secure-exec/core/native-client";
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarProcess as NativeSidecarProcessClient, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "@secure-exec/core/sidecar-client";
+import { SidecarProcess } from "@secure-exec/core/sidecar-client";
+export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarEventBufferOverflow, SidecarProcess, SidecarProcessError, SidecarProcessExited, } from "@secure-exec/core/sidecar-client";
+export const NativeSidecarProcessClient = SidecarProcess;

package/dist/sidecar/permissions.js

@@ -47,8 +47,8 @@ export function serializePermissionsForSidecar(permissions) {
         env: typeof permissions.env === "string" || !permissions.env
             ? permissions.env
             : serializePatternScope(permissions.env),
-        binding: typeof permissions.tool === "string" || !permissions.tool
-            ? permissions.tool
-            : serializePatternScope(permissions.tool),
+        binding: typeof permissions.binding === "string" || !permissions.binding
+            ? permissions.binding
+            : serializePatternScope(permissions.binding),
     };
 }

package/dist/sidecar/rpc-client.d.ts

@@ -2,12 +2,13 @@ import type { RootFilesystemConfig as VmConfigRootFilesystemConfig, RootFilesyst
 import type { NativeMountConfig, PlainMountConfig, RootFilesystemConfig } from "../agent-os.js";
 import type { RootSnapshotExport } from "../layers.js";
 import type { ConnectTerminalOptions, KernelExecOptions, KernelExecResult, KernelSpawnOptions, ManagedProcess, OpenShellOptions, ProcessInfo, ShellHandle, VirtualFileSystem, VirtualStat } from "../runtime-compat.js";
-import type { AuthenticatedSession, CreatedVm, SidecarProcess, SidecarSignalHandlerRegistration } from "./native-process-client.js";
+import type { AuthenticatedSession, CreatedVm, SidecarProcess, SidecarPermissionsPolicy, SidecarSignalHandlerRegistration } from "./native-process-client.js";
 export declare function toSidecarSignalName(signal: number): string;
 export interface LocalCompatMount {
     path: string;
     fs: VirtualFileSystem;
     readOnly: boolean;
+    sidecarMount?: SidecarMountDescriptor;
 }
 interface KernelSocketSnapshot {
     processId: string;
@@ -30,9 +31,21 @@ interface NativeSidecarKernelProxyOptions {
     cwd: string;
     defaultExecCwd?: string;
     localMounts: LocalCompatMount[];
+    sidecarMounts: SidecarMountDescriptor[];
+    permissions?: SidecarPermissionsPolicy;
+    commandPermissions?: Parameters<SidecarProcess["configureVm"]>[2]["commandPermissions"];
+    loopbackExemptPorts?: number[];
     commandGuestPaths: ReadonlyMap<string, string>;
     onWasmCommandResolved?: (command: string) => void;
     onDispose?: () => Promise<void>;
+    /**
+     * Whether this proxy owns the underlying sidecar process. When VMs share one
+     * sidecar process (the default for VMs leased from an `AgentOsSidecar`
+     * handle), each proxy tears down only its own VM on `dispose()`; the shared
+     * process is disposed when the sidecar handle is disposed. Defaults to true
+     * for the legacy one-process-per-VM path.
+     */
+    ownsClient?: boolean;
 }
 export declare class NativeSidecarKernelProxy {
     readonly env: Record<string, string>;
@@ -44,7 +57,12 @@ export declare class NativeSidecarKernelProxy {
     private readonly client;
     private readonly session;
     private readonly vm;
+    private readonly ownsClient;
     private readonly localMounts;
+    private readonly baseSidecarMounts;
+    private readonly permissions;
+    private readonly commandPermissions;
+    private readonly loopbackExemptPorts;
     private readonly commandDrivers;
     private readonly onWasmCommandResolved;
     private readonly onDispose;
@@ -62,6 +80,7 @@ export declare class NativeSidecarKernelProxy {
     private zombieTimerCountRefresh;
     private disposed;
     private pumpError;
+    private mountReconfigurePromise;
     private nextSyntheticPid;
     private readonly eventPumpAbortController;
     private readonly eventPump;
@@ -86,8 +105,12 @@ export declare class NativeSidecarKernelProxy {
     rename(oldPath: string, newPath: string): Promise<void>;
     mountFs(path: string, driver: VirtualFileSystem, options?: {
         readOnly?: boolean;
+        sidecarMount?: SidecarMountDescriptor;
     }): void;
     unmountFs(path: string): void;
+    private desiredSidecarMounts;
+    private reconfigureSidecarMounts;
+    private waitForMountReconfigure;
     snapshotProcesses(): ProcessInfo[];
     findListener(request: {
         host?: string;
@@ -125,8 +148,8 @@ export declare class NativeSidecarKernelProxy {
     private assertLocalWritable;
     private updateTrackedProcessSnapshot;
 }
-export type { AuthenticatedSession, CreatedVm, GuestFilesystemStat, SidecarSpawnOptions, RootFilesystemEntry, SidecarEventSelector, SidecarPermissionsPolicy, SidecarRegisteredHostCallbackDefinition, SidecarRequestFrame, SidecarResponsePayload, SidecarSessionState, SidecarSignalHandlerRegistration, SidecarSocketStateEntry, } from "./native-process-client.js";
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./native-process-client.js";
+export type { AuthenticatedSession, CreatedVm, GuestFilesystemStat, RootFilesystemEntry, SidecarEventSelector, SidecarPermissionsPolicy, SidecarRegisteredHostCallbackDefinition, SidecarRequestFrame, SidecarResponsePayload, SidecarSessionState, SidecarSignalHandlerRegistration, SidecarSocketStateEntry, SidecarSpawnOptions, } from "./native-process-client.js";
+export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarProcessClient, SidecarEventBufferOverflow, SidecarProcess, SidecarProcessError, SidecarProcessExited, } from "./native-process-client.js";
 export type AgentOsSidecarPlacement = {
     kind: "shared";
     pool?: string;

package/dist/sidecar/rpc-client.js

@@ -181,7 +181,12 @@ export class NativeSidecarKernelProxy {
     client;
     session;
     vm;
+    ownsClient;
     localMounts;
+    baseSidecarMounts;
+    permissions;
+    commandPermissions;
+    loopbackExemptPorts;
     commandDrivers;
     onWasmCommandResolved;
     onDispose;
@@ -199,6 +204,7 @@ export class NativeSidecarKernelProxy {
     zombieTimerCountRefresh = null;
     disposed = false;
     pumpError = null;
+    mountReconfigurePromise = null;
     nextSyntheticPid = SYNTHETIC_PID_BASE;
     eventPumpAbortController = new AbortController();
     eventPump;
@@ -206,10 +212,17 @@ export class NativeSidecarKernelProxy {
         this.client = options.client;
         this.session = options.session;
         this.vm = options.vm;
+        this.ownsClient = options.ownsClient ?? true;
         this.env = { ...options.env };
         this.cwd = options.cwd;
         this.defaultExecCwd = options.defaultExecCwd;
         this.localMounts = [...options.localMounts].sort((left, right) => right.path.length - left.path.length);
+        const localMountPaths = new Set(this.localMounts.map((mount) => mount.path));
+        this.baseSidecarMounts = options.sidecarMounts.filter((mount) => mount.plugin.id !== "js_bridge" ||
+            !localMountPaths.has(posixPath.normalize(mount.guestPath)));
+        this.permissions = options.permissions;
+        this.commandPermissions = options.commandPermissions;
+        this.loopbackExemptPorts = options.loopbackExemptPorts;
         this.commandDrivers = buildCommandMap(options.commandGuestPaths);
         this.onWasmCommandResolved = options.onWasmCommandResolved;
         this.onDispose = options.onDispose;
@@ -239,6 +252,7 @@ export class NativeSidecarKernelProxy {
         }
         this.disposed = true;
         this.eventPumpAbortController.abort();
+        await this.mountReconfigurePromise?.catch(() => { });
         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(() => { });
@@ -251,7 +265,12 @@ export class NativeSidecarKernelProxy {
                 this.finishProcess(entry, 143);
             }
         }
-        await this.client.dispose().catch(() => { });
+        // Only tear down the shared sidecar process when this proxy owns it. VMs
+        // leased from an `AgentOsSidecar` handle share one process, which is
+        // disposed when the handle is disposed.
+        if (this.ownsClient) {
+            await this.client.dispose().catch(() => { });
+        }
         await this.eventPump.catch(() => { });
         await this.onDispose?.().catch(() => { });
     }
@@ -1011,14 +1030,57 @@ export class NativeSidecarKernelProxy {
             path: posixPath.normalize(path),
             fs: driver,
             readOnly: options?.readOnly ?? false,
+            sidecarMount: options?.sidecarMount,
         });
         this.localMounts.sort((left, right) => right.path.length - left.path.length);
+        void this.reconfigureSidecarMounts().catch(() => { });
     }
     unmountFs(path) {
         const normalized = posixPath.normalize(path);
         const index = this.localMounts.findIndex((mount) => mount.path === normalized);
         if (index >= 0) {
             this.localMounts.splice(index, 1);
+            void this.reconfigureSidecarMounts().catch(() => { });
+        }
+    }
+    desiredSidecarMounts() {
+        return [
+            ...this.baseSidecarMounts,
+            ...this.localMounts.map((mount) => mount.sidecarMount ?? {
+                guestPath: mount.path,
+                readOnly: mount.readOnly,
+                plugin: {
+                    id: "js_bridge",
+                    config: {},
+                },
+            }),
+        ];
+    }
+    reconfigureSidecarMounts() {
+        const run = async () => {
+            if (this.disposed) {
+                return;
+            }
+            await this.client.configureVm(this.session, this.vm, {
+                mounts: this.desiredSidecarMounts(),
+                permissions: this.permissions,
+                commandPermissions: this.commandPermissions,
+                loopbackExemptPorts: this.loopbackExemptPorts,
+            });
+        };
+        const previous = this.mountReconfigurePromise ?? Promise.resolve();
+        const next = previous.then(run, run);
+        const tracked = next.finally(() => {
+            if (this.mountReconfigurePromise === tracked) {
+                this.mountReconfigurePromise = null;
+            }
+        });
+        this.mountReconfigurePromise = tracked;
+        return tracked;
+    }
+    async waitForMountReconfigure() {
+        if (this.mountReconfigurePromise) {
+            await this.mountReconfigurePromise;
         }
     }
     snapshotProcesses() {
@@ -1132,6 +1194,7 @@ export class NativeSidecarKernelProxy {
         }
     }
     async startTrackedProcess(entry) {
+        await this.waitForMountReconfigure();
         const started = await this.client.execute(this.session, this.vm, {
             processId: entry.processId,
             command: entry.command,
@@ -1157,11 +1220,14 @@ export class NativeSidecarKernelProxy {
         }
     }
     async runEventPump() {
+        // Scope the pump to THIS VM's ownership so multiple proxies can share one
+        // sidecar process: events for other VMs stay buffered for their own pumps
+        // rather than being consumed (and dropped) here.
+        const vmId = this.vm.vmId;
         while (!this.disposed) {
             try {
-                const event = await this.client.waitForEvent({ any: true }, undefined, {
-                    signal: this.eventPumpAbortController.signal,
-                });
+                const event = await this.client.waitForEvent((frame) => frame.ownership.scope === "vm" &&
+                    frame.ownership.vm_id === vmId, undefined, { signal: this.eventPumpAbortController.signal });
                 if (event.payload.type === "process_output") {
                     const entry = this.trackedProcessesById.get(event.payload.process_id);
                     if (!entry) {
@@ -1580,7 +1646,8 @@ export class NativeSidecarKernelProxy {
         }
         return this.dispatchNativeRead(path);
     }
-    dispatchNativeRead(path) {
+    async dispatchNativeRead(path) {
+        await this.waitForMountReconfigure();
         return this.client.readFile(this.session, this.vm, path);
     }
     async dispatchWrite(path, handler, nativeHandler, includeLocalMounts = true) {
@@ -1591,6 +1658,7 @@ export class NativeSidecarKernelProxy {
             await handler(local.mount, local.relativePath);
             return;
         }
+        await this.waitForMountReconfigure();
         await nativeHandler();
     }
     resolveLocalMount(path) {
@@ -1750,7 +1818,7 @@ function socketLookupKey(kind, request) {
         path: request.path ?? null,
     });
 }
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./native-process-client.js";
+export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarProcessClient, SidecarEventBufferOverflow, SidecarProcess, SidecarProcessError, SidecarProcessExited, } from "./native-process-client.js";
 export class AgentOsSidecarVmHandle {
     client;
     sessionId;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rivet-dev/agentos-core",
-	"version": "0.0.0-nathan-agentos-combined.e833bb7",
+	"version": "0.2.0",
 	"type": "module",
 	"license": "Apache-2.0",
 	"main": "./dist/index.js",
@@ -56,9 +56,9 @@
 	"dependencies": {
 		"@agentos-software/common": "0.3.0-rc.2",
 		"@aws-sdk/client-s3": "^3.1019.0",
-		"@rivet-dev/agentos-sidecar": "0.0.0-nathan-agentos-combined.e833bb7",
+		"@rivet-dev/agentos-sidecar": "0.2.0",
 		"@rivetkit/bare-ts": "^0.6.2",
-		"@secure-exec/core": "0.0.0-codex-native-sidecar-platform-ci.117d645",
+		"@secure-exec/core": "0.3.1",
 		"@xterm/headless": "^6.0.0",
 		"better-sqlite3": "^12.8.0",
 		"croner": "^10.0.1",
@@ -79,11 +79,11 @@
 		"@copilotkit/llmock": "^1.6.0",
 		"@rivet-dev/agentos-sandbox": "link:../agentos-sandbox",
 		"@agentos-software/git": "0.3.0-rc.2",
-		"@secure-exec/google-drive": "0.0.0-codex-native-sidecar-platform-ci.117d645",
-		"@secure-exec/s3": "0.0.0-codex-native-sidecar-platform-ci.117d645",
+		"@secure-exec/google-drive": "0.3.1",
+		"@secure-exec/s3": "0.3.1",
 		"@mariozechner/pi-coding-agent": "^0.60.0",
 		"@agentos-software/claude-code": "0.0.0-nathan-binding-workspace.9be0a88",
-		"@agentos-software/codex-cli": "0.3.0-rc.2",
+		"@agentos-software/codex-cli": "0.0.0-codex-claude-runtime-fixes.9cbef3a",
 		"@agentos-software/codex": "0.3.0-rc.2",
 		"@agentos-software/coreutils": "0.3.0-rc.2",
 		"@agentos-software/curl": "0.3.0-rc.2",