@rivet-dev/agentos-core 0.0.0-integrate-dylib-into-main.815fcda → 0.0.0-main.2f99c77

package/dist/sidecar/rpc-client.js

@@ -7,6 +7,30 @@ const PROTECTED_READ_ONLY_GUEST_ROOTS = ["/etc/agentos"];
 const TRAILING_OUTPUT_DRAIN_INTERVAL_MS = 10;
 const TRAILING_OUTPUT_DRAIN_MAX_MS = 250;
 const TRAILING_OUTPUT_DRAIN_QUIET_TURNS = 2;
+function shouldLogStructuredSidecarEvent(name) {
+    const normalized = name.toLowerCase();
+    return (normalized === "limit_warning" ||
+        normalized.startsWith("security.") ||
+        normalized.includes("warning") ||
+        normalized.includes("failed") ||
+        normalized.includes("error"));
+}
+function formatStructuredSidecarDetail(detail) {
+    const entries = Object.entries(detail);
+    if (entries.length === 0) {
+        return "";
+    }
+    return entries.map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ");
+}
+function logStructuredSidecarEvent(name, detail) {
+    if (!shouldLogStructuredSidecarEvent(name)) {
+        return;
+    }
+    const formatted = formatStructuredSidecarDetail(detail);
+    console.warn(formatted
+        ? `[agent-os] sidecar ${name}: ${formatted}`
+        : `[agent-os] sidecar ${name}`);
+}
 async function drainTrailingProcessOutputTurn(delayMs = 0) {
     // Native-sidecar `process_output` events can lag one macrotask behind the
     // terminal `process_exited` notification for very short-lived processes, and
@@ -142,7 +166,10 @@ function parseSimpleExecCommand(command) {
     return tokens;
 }
 function canUseDirectExec(driver, commandName) {
-    return driver === "wasmvm" || (driver === "node" && commandName === "node");
+    return (driver === "wasmvm" ||
+        (driver === "node" && commandName === "node") ||
+        (driver === "python" &&
+            (commandName === "python" || commandName === "python3")));
 }
 function shellSingleQuote(value) {
     if (value.length === 0) {
@@ -181,7 +208,17 @@ export class NativeSidecarKernelProxy {
     client;
     session;
     vm;
+    ownsClient;
     localMounts;
+    baseSidecarMounts;
+    permissions;
+    commandPermissions;
+    loopbackExemptPorts;
+    // Mutable: runtime `linkSoftware` appends via `registerLinkedPackage` so
+    // later mount reconfigures resend linked packages too, not just boot ones.
+    packages;
+    packagesMountAt;
+    toolShimCommands;
     commandDrivers;
     onWasmCommandResolved;
     onDispose;
@@ -199,6 +236,7 @@ export class NativeSidecarKernelProxy {
     zombieTimerCountRefresh = null;
     disposed = false;
     pumpError = null;
+    mountReconfigurePromise = null;
     nextSyntheticPid = SYNTHETIC_PID_BASE;
     eventPumpAbortController = new AbortController();
     eventPump;
@@ -206,10 +244,20 @@ 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.packages = options.packages ? [...options.packages] : [];
+        this.packagesMountAt = options.packagesMountAt;
+        this.toolShimCommands = options.toolShimCommands;
         this.commandDrivers = buildCommandMap(options.commandGuestPaths);
         this.onWasmCommandResolved = options.onWasmCommandResolved;
         this.onDispose = options.onDispose;
@@ -233,12 +281,24 @@ export class NativeSidecarKernelProxy {
             this.commandDrivers.set(name, "wasmvm");
         }
     }
+    /**
+     * Record a runtime-linked package (`linkSoftware`) so mount reconfigures
+     * resend it. Rust `configure_vm` rebuilds the whole VM configuration from
+     * each payload, so a linked package omitted here would be silently
+     * unprojected from `/opt/agentos` by the next `mountFs`/`unmountFs`.
+     */
+    registerLinkedPackage(descriptor) {
+        if (!this.packages.some((pkg) => pkg.path === descriptor.path)) {
+            this.packages.push({ path: descriptor.path });
+        }
+    }
     async dispose() {
         if (this.disposed) {
             return;
         }
         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,9 +311,42 @@ 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(() => { });
+        // Drop all per-VM tracking state so a disposed proxy retains nothing.
+        for (const entry of this.trackedProcesses.values()) {
+            entry.onStdout.clear();
+            entry.onStderr.clear();
+        }
+        this.trackedProcesses.clear();
+        this.trackedProcessesById.clear();
+        this.signalStates.clear();
+        this.signalRefreshes.clear();
+        this.localMounts.length = 0;
+    }
+    /** Test-only snapshot of the per-VM tracking collection sizes. */
+    __trackingSizesForTest() {
+        return {
+            trackedProcesses: this.trackedProcesses.size,
+            trackedProcessesById: this.trackedProcessesById.size,
+            signalStates: this.signalStates.size,
+            signalRefreshes: this.signalRefreshes.size,
+            localMounts: this.localMounts.length,
+        };
+    }
+    /** Test-only handle to a tracked entry so its listener Sets can be inspected. */
+    __trackedEntryForTest(pid) {
+        return this.trackedProcesses.get(pid);
+    }
+    /** Test-only join point for in-flight signal-state refreshes. */
+    async __awaitSignalRefreshesForTest() {
+        await Promise.allSettled([...this.signalRefreshes.values()]);
     }
     async exec(command, options) {
         if (!this.commands.has("sh")) {
@@ -263,9 +356,6 @@ export class NativeSidecarKernelProxy {
         const stderrChunks = [];
         const effectiveCwd = options?.cwd ?? this.defaultExecCwd ?? this.cwd;
         const parsedCommand = parseSimpleExecCommand(command);
-        const resolveExecPath = (targetPath) => targetPath.startsWith("/")
-            ? posixPath.normalize(targetPath)
-            : posixPath.normalize(posixPath.join(effectiveCwd, targetPath));
         const runAndCapture = async (proc, stdinOverride, readExitCode) => {
             if (stdinOverride !== undefined) {
                 proc.writeStdin(stdinOverride);
@@ -301,43 +391,6 @@ export class NativeSidecarKernelProxy {
                 stderr: Buffer.concat(stderrChunks.map((chunk) => Buffer.from(chunk))).toString("utf8"),
             };
         };
-        if (parsedCommand &&
-            (parsedCommand[0] === "sh" || parsedCommand[0] === "/bin/sh") &&
-            parsedCommand[1] === "-c" &&
-            parsedCommand.length === 3) {
-            const shellScript = parsedCommand[2].trim();
-            const exitMatch = shellScript.match(/^exit(?:\s+(-?\d+))?$/);
-            if (exitMatch) {
-                return {
-                    exitCode: Number.parseInt(exitMatch[1] ?? "0", 10),
-                    stdout: "",
-                    stderr: "",
-                };
-            }
-            return this.exec(parsedCommand[2], options);
-        }
-        if (parsedCommand &&
-            parsedCommand[0] === "chmod" &&
-            parsedCommand.length >= 3 &&
-            /^[0-7]{3,4}$/.test(parsedCommand[1] ?? "")) {
-            const mode = Number.parseInt(parsedCommand[1], 8);
-            for (const target of parsedCommand.slice(2)) {
-                await this.client.chmod(this.session, this.vm, resolveExecPath(target), mode);
-            }
-            return { exitCode: 0, stdout: "", stderr: "" };
-        }
-        if (parsedCommand &&
-            parsedCommand[0] === "stat" &&
-            parsedCommand.length === 4 &&
-            parsedCommand[1] === "-c" &&
-            parsedCommand[2] === "%a") {
-            const stat = await this.stat(resolveExecPath(parsedCommand[3]));
-            return {
-                exitCode: 0,
-                stdout: `${(stat.mode & 0o777).toString(8)}\n`,
-                stderr: "",
-            };
-        }
         const parsedCommandDriver = parsedCommand
             ? this.commands.get(parsedCommand[0])
             : undefined;
@@ -447,11 +500,15 @@ export class NativeSidecarKernelProxy {
             processId,
             command: spawnCommand,
             args: spawnArgs,
-            driver: spawnCommand === "node" ? "node" : "wasmvm",
+            driver: spawnCommand === "node"
+                ? "node"
+                : spawnCommand === "python" || spawnCommand === "python3"
+                    ? "python"
+                    : "wasmvm",
             cwd: options?.cwd ?? this.cwd,
             env: {
                 ...(options?.env ?? {}),
-                ...(options?.streamStdin ? { SECURE_EXEC_KEEP_STDIN_OPEN: "1" } : {}),
+                ...(options?.streamStdin ? { AGENTOS_KEEP_STDIN_OPEN: "1" } : {}),
             },
             startTime: Date.now(),
             exitTime: null,
@@ -479,16 +536,16 @@ export class NativeSidecarKernelProxy {
             pid,
             writeStdin: (data) => {
                 if (entry.exitCode !== null) {
-                    return;
+                    return Promise.resolve();
                 }
                 entry.pendingStdin.push(data);
-                void this.flushPendingStdin(entry).catch((error) => {
+                return this.flushPendingStdin(entry).catch((error) => {
                     this.handleBackgroundProcessError(entry, error);
                 });
             },
             closeStdin: () => {
                 entry.pendingCloseStdin = true;
-                void this.closeTrackedStdin(entry).catch((error) => {
+                return this.closeTrackedStdin(entry).catch((error) => {
                     this.handleBackgroundProcessError(entry, error);
                 });
             },
@@ -532,7 +589,6 @@ export class NativeSidecarKernelProxy {
         const args = options?.args ??
             (command === "sh" || command === "/bin/sh" ? ["-i"] : []);
         const synthesizePrompt = !options?.command && !options?.args;
-        const autoCloseExplicitCommandStdin = Boolean(options?.command) && !["sh", "/bin/sh", "bash"].includes(command);
         const promptText = "sh-0.4$ ";
         const textEncoder = new TextEncoder();
         const textDecoder = new TextDecoder();
@@ -542,14 +598,18 @@ export class NativeSidecarKernelProxy {
             .replace(/\u001b\[[0-9;]*m/g, "")
             .replace(/^.*WARN could not retrieve pid for child process\n?/gm, "")
             .replace(/^ProcessExitError:.*\n(?:\s+at .*\n)*/gm, "");
+        const sanitizeNativeShellOutput = (chunk) => {
+            const text = textDecoder.decode(chunk);
+            const sanitized = text.replace(/^.*WARN could not retrieve pid for child process\n?/gm, "");
+            return sanitized.length > 0 ? textEncoder.encode(sanitized) : null;
+        };
         let bufferedInput = "";
         let bufferedCommand = "";
         let activeForegroundProcess = null;
-        let shellEnv = { ...(options?.env ?? {}) };
+        let shellEnv = { ...(options?.env ?? {}), AGENTOS_EXEC_TTY: "1" };
         let shellCwd = options?.cwd ?? this.cwd;
         let syntheticCommandQueue = Promise.resolve();
         let promptTimer = null;
-        let closeStdinTimer = null;
         let commandInFlight = false;
         let syntheticCursorAtLineStart = true;
         const syntheticPid = this.nextSyntheticPid++;
@@ -564,12 +624,6 @@ export class NativeSidecarKernelProxy {
                 promptTimer = null;
             }
         };
-        const clearCloseStdinTimer = () => {
-            if (closeStdinTimer !== null) {
-                clearTimeout(closeStdinTimer);
-                closeStdinTimer = null;
-            }
-        };
         const normalizeSyntheticTerminalText = (text) => text.replace(/\r?\n/g, "\r\n");
         const updateSyntheticCursor = (text) => {
             if (!text) {
@@ -665,15 +719,36 @@ export class NativeSidecarKernelProxy {
             }
             return parsed;
         };
-        const writeForegroundInput = (proc, data) => {
+        const writeForegroundInput = async (proc, data) => {
             if (typeof data === "string") {
                 for (const character of data) {
-                    proc.writeStdin(character);
+                    await proc.writeStdin(character);
                 }
                 return;
             }
             for (const byte of data) {
-                proc.writeStdin(new Uint8Array([byte]));
+                await proc.writeStdin(new Uint8Array([byte]));
+            }
+        };
+        const appendSyntheticInput = (input) => {
+            for (const character of input) {
+                if (character === "\u0004") {
+                    continue;
+                }
+                if (character === "\b" || character === "\u007f") {
+                    if (bufferedInput.length > 0) {
+                        bufferedInput = bufferedInput.slice(0, -1);
+                        emitSyntheticTerminal("\b \b");
+                    }
+                    continue;
+                }
+                bufferedInput += character;
+                if (character === "\n") {
+                    emitSyntheticTerminal("\n");
+                }
+                else if (character >= " ") {
+                    emitSyntheticTerminal(character);
+                }
             }
         };
         let onData = null;
@@ -685,7 +760,7 @@ export class NativeSidecarKernelProxy {
             schedulePrompt(0);
             return {
                 pid: syntheticPid,
-                write(data) {
+                async write(data) {
                     if (syntheticExitCode !== null) {
                         return;
                     }
@@ -696,13 +771,13 @@ export class NativeSidecarKernelProxy {
                         if (rawText.includes("\u0003")) {
                             const [beforeInterrupt] = rawText.split("\u0003");
                             if (beforeInterrupt) {
-                                writeForegroundInput(activeForegroundProcess, beforeInterrupt);
+                                await writeForegroundInput(activeForegroundProcess, beforeInterrupt);
                             }
                             emitSyntheticTerminal("^C\n");
                             activeForegroundProcess.kill(2);
                             return;
                         }
-                        writeForegroundInput(activeForegroundProcess, data);
+                        await writeForegroundInput(activeForegroundProcess, data);
                         return;
                     }
                     const rawText = typeof data === "string"
@@ -725,7 +800,7 @@ export class NativeSidecarKernelProxy {
                         finishSyntheticShell(0);
                         return;
                     }
-                    bufferedInput += text.replace(/\u0004/g, "");
+                    appendSyntheticInput(text.replace(/\r\n/g, "\n").replace(/\r/g, "\n"));
                     while (true) {
                         const newlineIndex = bufferedInput.indexOf("\n");
                         if (newlineIndex < 0) {
@@ -735,7 +810,6 @@ export class NativeSidecarKernelProxy {
                             .slice(0, newlineIndex)
                             .replace(/\r$/, "");
                         bufferedInput = bufferedInput.slice(newlineIndex + 1);
-                        emitSyntheticStdout(`${line}\n`);
                         const nextCommand = bufferedCommand
                             ? `${bufferedCommand}\n${line}`
                             : line;
@@ -834,20 +908,33 @@ export class NativeSidecarKernelProxy {
             };
         }
         const proc = this.spawn(command, args, {
-            env: options?.env,
+            env: {
+                ...(options?.env ?? {}),
+                ...(options?.cols ? { COLUMNS: String(Math.trunc(options.cols)) } : {}),
+                ...(options?.rows ? { LINES: String(Math.trunc(options.rows)) } : {}),
+                AGENTOS_EXEC_TTY: "1",
+            },
             cwd: options?.cwd,
             streamStdin: true,
             onStdout: (chunk) => {
+                const sanitized = sanitizeNativeShellOutput(chunk);
+                if (!sanitized) {
+                    return;
+                }
                 for (const handler of stdoutHandlers) {
-                    handler(chunk);
+                    handler(sanitized);
                 }
                 if (commandInFlight) {
                     schedulePrompt(120);
                 }
             },
             onStderr: (chunk) => {
+                const sanitized = sanitizeNativeShellOutput(chunk);
+                if (!sanitized) {
+                    return;
+                }
                 for (const handler of stderrHandlers) {
-                    handler(chunk);
+                    handler(sanitized);
                 }
                 if (commandInFlight) {
                     schedulePrompt(120);
@@ -856,18 +943,11 @@ export class NativeSidecarKernelProxy {
         });
         return {
             pid: proc.pid,
-            write(data) {
+            async write(data) {
                 if (synthesizePrompt) {
                     return;
                 }
-                proc.writeStdin(data);
-                if (autoCloseExplicitCommandStdin) {
-                    clearCloseStdinTimer();
-                    closeStdinTimer = setTimeout(() => {
-                        closeStdinTimer = null;
-                        proc.closeStdin();
-                    }, 100);
-                }
+                await proc.writeStdin(data);
                 if (synthesizePrompt &&
                     typeof data === "string" &&
                     (data.includes("\n") || data.includes("\r"))) {
@@ -881,11 +961,18 @@ export class NativeSidecarKernelProxy {
             set onData(handler) {
                 onData = handler;
             },
-            resize() {
-                // The current stdio-native path is process-backed rather than PTY-backed.
+            resize: (cols, rows) => {
+                const entry = this.trackedProcesses.get(proc.pid);
+                if (!entry || entry.exitCode !== null) {
+                    return;
+                }
+                void entry.startPromise
+                    .then(() => this.client.resizePty(this.session, this.vm, entry.processId, Math.trunc(cols), Math.trunc(rows)))
+                    .catch((error) => {
+                    this.handleBackgroundProcessError(entry, error);
+                });
             },
             kill(signal) {
-                clearCloseStdinTimer();
                 clearPromptTimer();
                 proc.kill(signal);
             },
@@ -985,12 +1072,41 @@ export class NativeSidecarKernelProxy {
         const entries = await this.client.readdir(this.session, this.vm, path);
         return [...new Set([...entries, ...this.mountedChildNames(path)])].sort((a, b) => a.localeCompare(b));
     }
+    async readdirRecursive(path, options) {
+        const local = this.resolveLocalMount(path);
+        if (local) {
+            return this.readdirRecursiveLocal(local.mount.fs, local.relativePath, options?.maxDepth);
+        }
+        return (await this.client.readdirRecursive(this.session, this.vm, path, options)).map((entry) => ({ ...entry, size: Number(entry.size) }));
+    }
     async removeFile(path) {
         return this.dispatchWrite(path, (mount, relativePath) => mount.fs.removeFile(relativePath), () => this.client.removeFile(this.session, this.vm, path));
     }
     async removeDir(path) {
         return this.dispatchWrite(path, (mount, relativePath) => mount.fs.removeDir(relativePath), () => this.client.removeDir(this.session, this.vm, path));
     }
+    async removePath(path, options) {
+        return this.dispatchWrite(path, (mount, relativePath) => this.removePathLocal(mount.fs, relativePath, options?.recursive ?? false), () => this.client.removePath(this.session, this.vm, path, {
+            recursive: options?.recursive ?? false,
+        }));
+    }
+    async copyPath(fromPath, toPath, options) {
+        const from = this.resolveLocalMount(fromPath);
+        const to = this.resolveLocalMount(toPath);
+        if (!!from !== !!to) {
+            throw errnoError("EXDEV", "cross-device link not permitted");
+        }
+        if (from && to) {
+            if (from.mount.path !== to.mount.path) {
+                throw errnoError("EXDEV", "cross-device link not permitted");
+            }
+            this.assertLocalWritable(to.mount);
+            return this.copyPathLocal(from.mount.fs, from.relativePath, to.relativePath, options?.recursive ?? false);
+        }
+        return this.client.copyPath(this.session, this.vm, fromPath, toPath, {
+            recursive: options?.recursive ?? false,
+        });
+    }
     async rename(oldPath, newPath) {
         const from = this.resolveLocalMount(oldPath);
         const to = this.resolveLocalMount(newPath);
@@ -1006,19 +1122,93 @@ export class NativeSidecarKernelProxy {
         }
         return this.client.rename(this.session, this.vm, oldPath, newPath);
     }
+    async movePath(oldPath, newPath) {
+        const from = this.resolveLocalMount(oldPath);
+        const to = this.resolveLocalMount(newPath);
+        if (!!from !== !!to) {
+            throw errnoError("EXDEV", "cross-device link not permitted");
+        }
+        if (from && to) {
+            if (from.mount.path !== to.mount.path) {
+                throw errnoError("EXDEV", "cross-device link not permitted");
+            }
+            this.assertLocalWritable(from.mount);
+            return from.mount.fs.rename(from.relativePath, to.relativePath);
+        }
+        return this.client.movePath(this.session, this.vm, oldPath, newPath);
+    }
     mountFs(path, driver, options) {
         this.localMounts.unshift({
             path: posixPath.normalize(path),
             fs: driver,
             readOnly: options?.readOnly ?? false,
+            sidecarMount: options?.sidecarMount,
         });
         this.localMounts.sort((left, right) => right.path.length - left.path.length);
+        // Resolves once the sidecar has the mount; a swallowed rejection here
+        // used to turn reconfigure failures into silently missing guest mounts.
+        // The local catch only guards callers that drop the promise — awaiting
+        // callers still observe the rejection.
+        const applied = this.reconfigureSidecarMounts();
+        applied.catch(() => { });
+        return applied;
     }
     unmountFs(path) {
         const normalized = posixPath.normalize(path);
         const index = this.localMounts.findIndex((mount) => mount.path === normalized);
-        if (index >= 0) {
-            this.localMounts.splice(index, 1);
+        if (index < 0) {
+            return Promise.resolve();
+        }
+        this.localMounts.splice(index, 1);
+        const applied = this.reconfigureSidecarMounts();
+        applied.catch(() => { });
+        return applied;
+    }
+    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;
+            }
+            // Rust `configure_vm` rebuilds the whole VM configuration from this
+            // payload, so resend the boot packages / tool shim commands too —
+            // omitting them here strips the `/opt/agentos` projections and tool
+            // shims from the VM as a side effect of a runtime mount change.
+            await this.client.configureVm(this.session, this.vm, {
+                mounts: this.desiredSidecarMounts(),
+                permissions: this.permissions,
+                commandPermissions: this.commandPermissions,
+                loopbackExemptPorts: this.loopbackExemptPorts,
+                packages: this.packages,
+                packagesMountAt: this.packagesMountAt,
+                toolShimCommands: this.toolShimCommands,
+            });
+        };
+        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 +1322,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 +1348,13 @@ 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) {
@@ -1188,8 +1381,11 @@ export class NativeSidecarKernelProxy {
                         continue;
                     }
                     void this.refreshProcessSnapshot().catch(() => { });
-                    this.signalRefreshes.delete(entry.pid);
                     this.finishProcess(entry, event.payload.exit_code);
+                    continue;
+                }
+                if (event.payload.type === "structured") {
+                    logStructuredSidecarEvent(event.payload.name, event.payload.detail);
                 }
             }
             catch (error) {
@@ -1220,6 +1416,25 @@ export class NativeSidecarKernelProxy {
         entry.exitTime = Date.now();
         this.updateTrackedProcessSnapshot(entry);
         entry.resolveWait(exitCode);
+        // Release per-process tracking now that the process has terminated so these
+        // maps/Sets don't grow without bound. Defer the release until trailing
+        // output has drained: `wait()`'s drain and late `process_output` events
+        // still need the entry + its listeners during the drain window. The exited
+        // record lives on in `processes` for listing.
+        void this.releaseProcessTrackingAfterDrain(entry);
+    }
+    async releaseProcessTrackingAfterDrain(entry) {
+        try {
+            await this.drainTrailingProcessOutput(entry);
+        }
+        finally {
+            this.trackedProcesses.delete(entry.pid);
+            this.trackedProcessesById.delete(entry.processId);
+            this.signalRefreshes.delete(entry.pid);
+            this.signalStates.delete(entry.pid);
+            entry.onStdout.clear();
+            entry.onStderr.clear();
+        }
     }
     waitForTrackedProcess(entry) {
         if (entry.exitCode !== null) {
@@ -1370,6 +1585,74 @@ export class NativeSidecarKernelProxy {
             handler(stderr);
         }
     }
+    async readdirRecursiveLocal(fs, path, maxDepth) {
+        const results = [];
+        const queue = [{ path, depth: 0 }];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (!current)
+                break;
+            for (const name of await fs.readDir(current.path)) {
+                if (name === "." || name === "..")
+                    continue;
+                const child = posixPath.join(current.path, name);
+                const stat = await fs.lstat(child);
+                results.push({
+                    name,
+                    path: child,
+                    isDirectory: stat.isDirectory,
+                    isSymbolicLink: stat.isSymbolicLink,
+                    size: stat.size,
+                });
+                if (stat.isDirectory &&
+                    !stat.isSymbolicLink &&
+                    (maxDepth === undefined || current.depth < maxDepth)) {
+                    queue.push({ path: child, depth: current.depth + 1 });
+                }
+            }
+        }
+        return results;
+    }
+    async removePathLocal(fs, path, recursive) {
+        const stat = await fs.lstat(path);
+        if (stat.isDirectory && !stat.isSymbolicLink) {
+            if (recursive) {
+                for (const name of await fs.readDir(path)) {
+                    if (name === "." || name === "..")
+                        continue;
+                    await this.removePathLocal(fs, posixPath.join(path, name), true);
+                }
+            }
+            return fs.removeDir(path);
+        }
+        return fs.removeFile(path);
+    }
+    async copyPathLocal(fs, fromPath, toPath, recursive) {
+        const stat = await fs.lstat(fromPath);
+        if (stat.isSymbolicLink) {
+            return fs.symlink(await fs.readlink(fromPath), toPath);
+        }
+        if (stat.isDirectory) {
+            if (!recursive) {
+                throw errnoError("EISDIR", "illegal operation on a directory");
+            }
+            await fs.mkdir(posixPath.dirname(toPath), { recursive: true });
+            if (!(await fs.exists(toPath))) {
+                await fs.createDir(toPath);
+            }
+            await fs.chmod(toPath, stat.mode);
+            await fs.chown(toPath, stat.uid, stat.gid);
+            for (const name of await fs.readDir(fromPath)) {
+                if (name === "." || name === "..")
+                    continue;
+                await this.copyPathLocal(fs, posixPath.join(fromPath, name), posixPath.join(toPath, name), true);
+            }
+            return;
+        }
+        await fs.writeFile(toPath, await fs.readFile(fromPath));
+        await fs.chmod(toPath, stat.mode);
+        await fs.chown(toPath, stat.uid, stat.gid);
+    }
     createFilesystemView(includeLocalMounts) {
         return {
             readFile: (path) => this.dispatchRead(path, (mount, relativePath) => mount.fs.readFile(relativePath), includeLocalMounts),
@@ -1580,7 +1863,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 +1875,7 @@ export class NativeSidecarKernelProxy {
             await handler(local.mount, local.relativePath);
             return;
         }
+        await this.waitForMountReconfigure();
         await nativeHandler();
     }
     resolveLocalMount(path) {
@@ -1666,6 +1951,10 @@ function buildCommandMap(commandGuestPaths) {
         ["node", "node"],
         ["npm", "node"],
         ["npx", "node"],
+        // `python` / `python3` are served by the embedded Pyodide runtime,
+        // mirroring how `node` is served by the embedded V8 runtime.
+        ["python", "python"],
+        ["python3", "python"],
     ]);
     for (const name of commandGuestPaths.keys()) {
         commands.set(name, "wasmvm");
@@ -1703,21 +1992,27 @@ function isMissingHostProcessError(error) {
 function errnoError(code, message) {
     return Object.assign(new Error(`${code}: ${message}`), { code });
 }
+// VirtualStat is a numeric, Node-default-shaped view: u64 fields above
+// Number.MAX_SAFE_INTEGER lose precision here, same as Node's non-bigint
+// fs.stat on the host.
 function toVirtualStat(stat) {
     return {
         mode: stat.mode,
-        size: stat.size,
-        blocks: stat.blocks,
-        dev: stat.dev,
-        rdev: stat.rdev,
+        size: Number(stat.size),
+        sizeExact: stat.size,
+        blocks: Number(stat.blocks),
+        dev: Number(stat.dev),
+        rdev: Number(stat.rdev),
         isDirectory: stat.is_directory,
         isSymbolicLink: stat.is_symbolic_link,
         atimeMs: stat.atime_ms,
         mtimeMs: stat.mtime_ms,
         ctimeMs: stat.ctime_ms,
         birthtimeMs: stat.birthtime_ms,
-        ino: stat.ino,
-        nlink: stat.nlink,
+        ino: Number(stat.ino),
+        inoExact: stat.ino,
+        nlink: Number(stat.nlink),
+        nlinkExact: stat.nlink,
         uid: stat.uid,
         gid: stat.gid,
     };
@@ -1750,7 +2045,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 { NativeSidecarProcessClient, SidecarEventBufferOverflow, SidecarProcess, SidecarProcessError, SidecarProcessExited, } from "./native-process-client.js";
 export class AgentOsSidecarVmHandle {
     client;
     sessionId;