@rivet-dev/agentos-core 0.0.0-codex-actor-plugin-contract-coverage.c7d8f87 → 0.0.0-fix-main-wasm-ownership.150c49a

package/dist/runtime-compat.js

@@ -7,16 +7,12 @@ import { fileURLToPath } from "node:url";
 import { resolvePublishedSidecarBinary } from "./sidecar/binary.js";
 import { findCargoBinary, resolveCargoBinary } from "./sidecar/cargo.js";
 import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
-import { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarKernelProxy, SidecarProcess, serializeMountConfigForSidecar, } from "./sidecar/rpc-client.js";
+import { NativeSidecarKernelProxy, SidecarProcess, serializeMountConfigForSidecar, } from "./sidecar/rpc-client.js";
 export const AF_INET = 2;
 export const AF_UNIX = 1;
 export const SOCK_STREAM = 1;
 export const SOCK_DGRAM = 2;
 export const SIGTERM = 15;
-const S_IFREG = 0o100000;
-const S_IFDIR = 0o040000;
-const S_IFLNK = 0o120000;
-const MAX_SYMLINK_DEPTH = 40;
 const NODE_RUNTIME_BOOTSTRAP_COMMANDS = [
     "node",
     "npm",
@@ -71,9 +67,23 @@ const SIDECAR_BUILD_INPUTS = [
     path.join(REPO_ROOT, "Cargo.toml"),
     path.join(REPO_ROOT, "Cargo.lock"),
     path.join(REPO_ROOT, "crates/bridge"),
+    path.join(REPO_ROOT, "crates/build-support"),
     path.join(REPO_ROOT, "crates/execution"),
     path.join(REPO_ROOT, "crates/kernel"),
-    path.join(REPO_ROOT, "crates/sidecar"),
+    path.join(REPO_ROOT, "crates/agentos-protocol"),
+    path.join(REPO_ROOT, "crates/agentos-sidecar"),
+    path.join(REPO_ROOT, "crates/native-sidecar"),
+    path.join(REPO_ROOT, "crates/native-sidecar-core"),
+    path.join(REPO_ROOT, "crates/sidecar-protocol"),
+    path.join(REPO_ROOT, "crates/v8-runtime"),
+    path.join(REPO_ROOT, "crates/vfs"),
+    path.join(REPO_ROOT, "crates/vm-config"),
+    path.join(REPO_ROOT, "packages/build-tools/bridge-src"),
+    path.join(REPO_ROOT, "packages/build-tools/package.json"),
+    path.join(REPO_ROOT, "packages/build-tools/scripts/build-v8-bridge.mjs"),
+    path.join(REPO_ROOT, "packages/core/fixtures/base-filesystem.json"),
+    path.join(REPO_ROOT, "packages/runtime-core/fixtures/base-filesystem.json"),
+    path.join(REPO_ROOT, "pnpm-lock.yaml"),
 ];
 let ensuredSidecarBinary = null;
 export class KernelError extends Error {
@@ -112,338 +122,6 @@ function dirnameVirtual(inputPath) {
     const parts = normalized.split("/").filter(Boolean);
     return parts.length <= 1 ? "/" : `/${parts.slice(0, -1).join("/")}`;
 }
-let nextInode = 1;
-export class InMemoryFileSystem {
-    entries = new Map();
-    constructor() {
-        this.entries.set("/", this.newDirectory());
-    }
-    async readFile(targetPath) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry || entry.type !== "file") {
-            throw errnoError("ENOENT", `open '${targetPath}'`);
-        }
-        entry.atimeMs = Date.now();
-        return new Uint8Array(entry.data);
-    }
-    async readTextFile(targetPath) {
-        return new TextDecoder().decode(await this.readFile(targetPath));
-    }
-    async readDir(targetPath) {
-        return (await this.readDirWithTypes(targetPath)).map((entry) => entry.name);
-    }
-    async readDirWithTypes(targetPath) {
-        const resolved = this.resolvePath(targetPath);
-        const entry = this.entries.get(resolved);
-        if (!entry || entry.type !== "dir") {
-            throw errnoError("ENOENT", `scandir '${targetPath}'`);
-        }
-        const prefix = resolved === "/" ? "/" : `${resolved}/`;
-        const output = new Map();
-        for (const [entryPath, candidate] of this.entries) {
-            if (!entryPath.startsWith(prefix))
-                continue;
-            const rest = entryPath.slice(prefix.length);
-            if (!rest || rest.includes("/"))
-                continue;
-            output.set(rest, {
-                name: rest,
-                isDirectory: candidate.type === "dir",
-                isSymbolicLink: candidate.type === "symlink",
-            });
-        }
-        return [...output.values()];
-    }
-    async writeFile(targetPath, content) {
-        const normalized = normalizePath(targetPath);
-        await this.mkdir(dirnameVirtual(normalized), { recursive: true });
-        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;
-            existing.mtimeMs = Date.now();
-            existing.ctimeMs = Date.now();
-            return;
-        }
-        const now = Date.now();
-        this.entries.set(normalized, {
-            type: "file",
-            data,
-            mode: S_IFREG | 0o644,
-            uid: 0,
-            gid: 0,
-            nlink: 1,
-            ino: nextInode++,
-            atimeMs: now,
-            mtimeMs: now,
-            ctimeMs: now,
-            birthtimeMs: now,
-        });
-    }
-    async createDir(targetPath) {
-        const normalized = normalizePath(targetPath);
-        if (!this.entries.has(dirnameVirtual(normalized))) {
-            throw errnoError("ENOENT", `mkdir '${targetPath}'`);
-        }
-        if (!this.entries.has(normalized)) {
-            this.entries.set(normalized, this.newDirectory());
-        }
-    }
-    async mkdir(targetPath, options) {
-        const normalized = normalizePath(targetPath);
-        if (options?.recursive === false) {
-            return this.createDir(normalized);
-        }
-        let current = "";
-        for (const part of normalized.split("/").filter(Boolean)) {
-            current += `/${part}`;
-            if (!this.entries.has(current)) {
-                this.entries.set(current, this.newDirectory());
-            }
-        }
-    }
-    async exists(targetPath) {
-        try {
-            return this.entries.has(this.resolvePath(targetPath));
-        }
-        catch {
-            return false;
-        }
-    }
-    async stat(targetPath) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry)
-            throw errnoError("ENOENT", `stat '${targetPath}'`);
-        return this.toStat(entry);
-    }
-    async removeFile(targetPath) {
-        const resolved = normalizePath(targetPath);
-        const entry = this.entries.get(resolved);
-        if (!entry || entry.type === "dir") {
-            throw errnoError("ENOENT", `unlink '${targetPath}'`);
-        }
-        this.entries.delete(resolved);
-    }
-    async removeDir(targetPath) {
-        const resolved = this.resolvePath(targetPath);
-        if (resolved === "/") {
-            throw errnoError("EPERM", "operation not permitted");
-        }
-        const entry = this.entries.get(resolved);
-        if (!entry || entry.type !== "dir") {
-            throw errnoError("ENOENT", `rmdir '${targetPath}'`);
-        }
-        const prefix = `${resolved}/`;
-        for (const key of this.entries.keys()) {
-            if (key.startsWith(prefix)) {
-                throw errnoError("ENOTEMPTY", `directory not empty '${targetPath}'`);
-            }
-        }
-        this.entries.delete(resolved);
-    }
-    async rename(oldPath, newPath) {
-        const oldResolved = this.resolvePath(oldPath);
-        const newResolved = normalizePath(newPath);
-        const entry = this.entries.get(oldResolved);
-        if (!entry)
-            throw errnoError("ENOENT", `rename '${oldPath}'`);
-        if (!this.entries.has(dirnameVirtual(newResolved))) {
-            throw errnoError("ENOENT", `rename '${newPath}'`);
-        }
-        if (entry.type !== "dir") {
-            this.entries.set(newResolved, entry);
-            this.entries.delete(oldResolved);
-            return;
-        }
-        const prefix = `${oldResolved}/`;
-        const moved = [];
-        for (const candidate of this.entries) {
-            if (candidate[0] === oldResolved || candidate[0].startsWith(prefix)) {
-                moved.push(candidate);
-            }
-        }
-        for (const [candidatePath] of moved) {
-            this.entries.delete(candidatePath);
-        }
-        for (const [candidatePath, candidate] of moved) {
-            const nextPath = candidatePath === oldResolved
-                ? newResolved
-                : `${newResolved}${candidatePath.slice(oldResolved.length)}`;
-            this.entries.set(nextPath, candidate);
-        }
-    }
-    async realpath(targetPath) {
-        return this.resolvePath(targetPath);
-    }
-    async symlink(target, linkPath) {
-        const normalized = normalizePath(linkPath);
-        if (this.entries.has(normalized)) {
-            throw errnoError("EEXIST", `symlink '${linkPath}'`);
-        }
-        const now = Date.now();
-        this.entries.set(normalized, {
-            type: "symlink",
-            target,
-            mode: S_IFLNK | 0o777,
-            uid: 0,
-            gid: 0,
-            nlink: 1,
-            ino: nextInode++,
-            atimeMs: now,
-            mtimeMs: now,
-            ctimeMs: now,
-            birthtimeMs: now,
-        });
-    }
-    async readlink(targetPath) {
-        const normalized = normalizePath(targetPath);
-        const entry = this.entries.get(normalized);
-        if (!entry || entry.type !== "symlink") {
-            throw errnoError("ENOENT", `readlink '${targetPath}'`);
-        }
-        return entry.target;
-    }
-    async lstat(targetPath) {
-        const entry = this.entries.get(normalizePath(targetPath));
-        if (!entry)
-            throw errnoError("ENOENT", `lstat '${targetPath}'`);
-        return this.toStat(entry);
-    }
-    async link(oldPath, newPath) {
-        const entry = this.resolveEntry(oldPath);
-        if (!entry || entry.type !== "file") {
-            throw errnoError("ENOENT", `link '${oldPath}'`);
-        }
-        const normalized = normalizePath(newPath);
-        if (this.entries.has(normalized)) {
-            throw errnoError("EEXIST", `link '${newPath}'`);
-        }
-        entry.nlink += 1;
-        this.entries.set(normalized, entry);
-    }
-    async chmod(targetPath, mode) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry)
-            throw errnoError("ENOENT", `chmod '${targetPath}'`);
-        const typeBits = mode & 0o170000;
-        entry.mode =
-            typeBits === 0 ? (entry.mode & 0o170000) | (mode & 0o7777) : mode;
-        entry.ctimeMs = Date.now();
-    }
-    async chown(targetPath, uid, gid) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry)
-            throw errnoError("ENOENT", `chown '${targetPath}'`);
-        entry.uid = uid;
-        entry.gid = gid;
-        entry.ctimeMs = Date.now();
-    }
-    async utimes(targetPath, atime, mtime) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry)
-            throw errnoError("ENOENT", `utimes '${targetPath}'`);
-        entry.atimeMs = atime;
-        entry.mtimeMs = mtime;
-        entry.ctimeMs = Date.now();
-    }
-    async truncate(targetPath, length) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry || entry.type !== "file") {
-            throw errnoError("ENOENT", `truncate '${targetPath}'`);
-        }
-        if (length < entry.data.length) {
-            entry.data = entry.data.slice(0, length);
-        }
-        else if (length > entry.data.length) {
-            const expanded = new Uint8Array(length);
-            expanded.set(entry.data);
-            entry.data = expanded;
-        }
-        entry.mtimeMs = Date.now();
-        entry.ctimeMs = Date.now();
-    }
-    async pread(targetPath, offset, length) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry || entry.type !== "file") {
-            throw errnoError("ENOENT", `open '${targetPath}'`);
-        }
-        if (offset >= entry.data.length)
-            return new Uint8Array(0);
-        return entry.data.slice(offset, Math.min(offset + length, entry.data.length));
-    }
-    async pwrite(targetPath, offset, data) {
-        const entry = this.resolveEntry(targetPath);
-        if (!entry || entry.type !== "file") {
-            throw errnoError("ENOENT", `open '${targetPath}'`);
-        }
-        const nextSize = Math.max(entry.data.length, offset + data.length);
-        const updated = new Uint8Array(nextSize);
-        updated.set(entry.data);
-        updated.set(new Uint8Array(data), offset);
-        entry.data = updated;
-        entry.mtimeMs = Date.now();
-        entry.ctimeMs = Date.now();
-    }
-    resolvePath(targetPath, depth = 0) {
-        if (depth > MAX_SYMLINK_DEPTH) {
-            throw errnoError("ELOOP", `too many symbolic links '${targetPath}'`);
-        }
-        const normalized = normalizePath(targetPath);
-        const entry = this.entries.get(normalized);
-        if (!entry)
-            return normalized;
-        if (entry.type === "symlink") {
-            const target = entry.target.startsWith("/")
-                ? entry.target
-                : `${dirnameVirtual(normalized)}/${entry.target}`;
-            return this.resolvePath(target, depth + 1);
-        }
-        return normalized;
-    }
-    resolveEntry(targetPath) {
-        return this.entries.get(this.resolvePath(targetPath));
-    }
-    newDirectory() {
-        const now = Date.now();
-        return {
-            type: "dir",
-            mode: S_IFDIR | 0o755,
-            uid: 0,
-            gid: 0,
-            nlink: 2,
-            ino: nextInode++,
-            atimeMs: now,
-            mtimeMs: now,
-            ctimeMs: now,
-            birthtimeMs: now,
-        };
-    }
-    toStat(entry) {
-        const size = entry.type === "file" ? entry.data.length : 4096;
-        return {
-            mode: entry.mode,
-            size,
-            blocks: size === 0 ? 0 : Math.ceil(size / 512),
-            dev: 1,
-            rdev: 0,
-            isDirectory: entry.type === "dir",
-            isSymbolicLink: entry.type === "symlink",
-            atimeMs: entry.atimeMs,
-            mtimeMs: entry.mtimeMs,
-            ctimeMs: entry.ctimeMs,
-            birthtimeMs: entry.birthtimeMs,
-            ino: entry.ino,
-            nlink: entry.nlink,
-            uid: entry.uid,
-            gid: entry.gid,
-        };
-    }
-}
-export function createInMemoryFileSystem() {
-    return new InMemoryFileSystem();
-}
 export class NodeFileSystem {
     rootPath;
     constructor(options) {
@@ -824,7 +502,6 @@ export const WASMVM_COMMANDS = Object.freeze([
     "unzip",
     "sqlite3",
     "curl",
-    "wget",
     "git",
     "git-remote-http",
     "git-remote-https",
@@ -988,7 +665,6 @@ export const DEFAULT_FIRST_PARTY_TIERS = Object.freeze({
     tac: "read-only",
     tsort: "read-only",
     curl: "full",
-    wget: "full",
     sqlite3: "read-write",
 });
 class NativeRuntimeDescriptor {
@@ -1194,7 +870,7 @@ function createBootstrapEntries() {
         ...KERNEL_POSIX_BOOTSTRAP_DIRS.map((entryPath) => ({
             path: entryPath,
             kind: "directory",
-            mode: 0o755,
+            mode: entryPath === "/tmp" || entryPath === "/var/tmp" ? 0o1777 : 0o755,
             uid: 0,
             gid: 0,
             executable: false,
@@ -1457,7 +1133,10 @@ const VIRTUAL_FILESYSTEM_METHOD_NAMES = [
     "pread",
     "pwrite",
 ];
-const LIVE_FILESYSTEM_SYNC_CHUNK_SIZE = 512 * 1024;
+const DEFAULT_LIVE_FILESYSTEM_SYNC_MAX_BYTES = 64 * 1024 * 1024;
+class LiveFilesystemSyncLimitError extends Error {
+    code = "ERR_AGENTOS_LIVE_FILESYSTEM_SYNC_LIMIT";
+}
 function topLevelSyncRoot(targetPath) {
     const normalized = normalizePath(targetPath);
     const [first] = normalized.split("/").filter(Boolean);
@@ -1489,50 +1168,71 @@ async function ensureBoundParentDirectory(methods, targetPath) {
         recursive: true,
     });
 }
-async function syncLiveFilesystemToBoundMethods(live, methods, paths) {
+async function syncLiveFilesystemToBoundMethods(live, methods, paths, maxBytes) {
+    const snapshot = [];
+    const usage = { bytes: 0 };
     for (const targetPath of [...new Set(paths.map(normalizePath))].sort((left, right) => left.localeCompare(right))) {
         if (!(await live.exists(targetPath).catch(() => false))) {
             continue;
         }
-        await syncLiveFilesystemPathToBoundMethods(live, methods, targetPath);
+        await snapshotLiveFilesystemPath(live, targetPath, snapshot, usage, maxBytes);
+    }
+    if (usage.bytes >= maxBytes * 0.8) {
+        process.emitWarning(`live filesystem sync retained ${usage.bytes} of ${maxBytes} bytes; ` +
+            "raise createKernel({ maxFilesystemBytes }) before increasing VM filesystem limits", { code: "AGENTOS_LIVE_FILESYSTEM_SYNC_NEAR_LIMIT" });
+    }
+    for (const entry of snapshot) {
+        await applyLiveFilesystemSnapshotEntry(methods, entry);
     }
 }
-async function syncLiveFilesystemPathToBoundMethods(live, methods, targetPath) {
-    const stat = targetPath === "/"
-        ? await live.stat(targetPath)
-        : await live.lstat(targetPath);
+async function snapshotLiveFilesystemPath(live, targetPath, snapshot, usage, maxBytes, knownEntry) {
+    const stat = knownEntry ??
+        (targetPath === "/" ? await live.stat(targetPath) : await live.lstat(targetPath));
     if (stat.isSymbolicLink) {
-        await ensureBoundParentDirectory(methods, targetPath);
-        await callBoundFilesystemMethod(methods, "removeFile", targetPath).catch(() => { });
-        await callBoundFilesystemMethod(methods, "symlink", await live.readlink(targetPath), targetPath);
+        snapshot.push({ kind: "symlink", path: targetPath, target: await live.readlink(targetPath) });
         return;
     }
     if (stat.isDirectory) {
-        await callBoundFilesystemMethod(methods, "mkdir", targetPath, {
-            recursive: true,
-        });
+        snapshot.push({ kind: "directory", path: targetPath });
         const children = (await live.readDirWithTypes(targetPath))
-            .map((entry) => entry.name)
-            .filter((name) => name !== "." && name !== "..")
-            .sort((left, right) => left.localeCompare(right));
+            .filter((entry) => entry.name !== "." && entry.name !== "..")
+            .sort((left, right) => left.name.localeCompare(right.name));
         for (const child of children) {
-            await syncLiveFilesystemPathToBoundMethods(live, methods, targetPath === "/"
-                ? posixPath.join("/", child)
-                : posixPath.join(targetPath, child));
+            await snapshotLiveFilesystemPath(live, targetPath === "/"
+                ? posixPath.join("/", child.name)
+                : posixPath.join(targetPath, child.name), snapshot, usage, maxBytes, child);
         }
         return;
     }
-    await ensureBoundParentDirectory(methods, targetPath);
-    await callBoundFilesystemMethod(methods, "writeFile", targetPath, new Uint8Array(0));
-    for (let offset = 0; offset < stat.size; offset += LIVE_FILESYSTEM_SYNC_CHUNK_SIZE) {
-        const chunk = await live.pread(targetPath, offset, Math.min(LIVE_FILESYSTEM_SYNC_CHUNK_SIZE, stat.size - offset));
-        if (chunk.length === 0) {
-            break;
-        }
-        await callBoundFilesystemMethod(methods, "pwrite", targetPath, offset, chunk);
+    const fileSize = "size" in stat && typeof stat.size === "number"
+        ? stat.size
+        : (await live.lstat(targetPath)).size;
+    if (fileSize > maxBytes - usage.bytes) {
+        throw new LiveFilesystemSyncLimitError(`live filesystem sync for ${targetPath} exceeds ${maxBytes} bytes ` +
+            "(createKernel maxFilesystemBytes); raise createKernel({ maxFilesystemBytes })");
+    }
+    const content = await live.readFile(targetPath);
+    if (content.byteLength > maxBytes - usage.bytes) {
+        throw new LiveFilesystemSyncLimitError(`live filesystem sync for ${targetPath} exceeds ${maxBytes} bytes ` +
+            "(createKernel maxFilesystemBytes); raise createKernel({ maxFilesystemBytes })");
+    }
+    usage.bytes += content.byteLength;
+    snapshot.push({ kind: "file", path: targetPath, content });
+}
+async function applyLiveFilesystemSnapshotEntry(methods, entry) {
+    if (entry.kind === "directory") {
+        await callBoundFilesystemMethod(methods, "mkdir", entry.path, { recursive: true });
+        return;
+    }
+    await ensureBoundParentDirectory(methods, entry.path);
+    if (entry.kind === "symlink") {
+        await callBoundFilesystemMethod(methods, "removeFile", entry.path).catch(() => { });
+        await callBoundFilesystemMethod(methods, "symlink", entry.target, entry.path);
+        return;
     }
+    await callBoundFilesystemMethod(methods, "writeFile", entry.path, entry.content);
 }
-function bindLiveFilesystem(target, getFilesystem) {
+function bindLiveFilesystem(target, getFilesystem, maxBytes) {
     const fallback = {};
     for (const method of VIRTUAL_FILESYSTEM_METHOD_NAMES) {
         const candidate = target[method];
@@ -1558,7 +1258,7 @@ function bindLiveFilesystem(target, getFilesystem) {
             if (!filesystem) {
                 return;
             }
-            await syncLiveFilesystemToBoundMethods(filesystem, fallback, paths);
+            await syncLiveFilesystemToBoundMethods(filesystem, fallback, paths, maxBytes);
         },
         restore() {
             for (const [method, delegate] of Object.entries(fallback)) {
@@ -1641,7 +1341,7 @@ class NativeKernel {
             }));
         }
         this.vfs = new DeferredFileSystem(() => this.rootFilesystem);
-        this.liveFilesystemBinding = bindLiveFilesystem(this.options.filesystem, () => this.rootFilesystem);
+        this.liveFilesystemBinding = bindLiveFilesystem(this.options.filesystem, () => this.rootFilesystem, options.maxFilesystemBytes ?? DEFAULT_LIVE_FILESYSTEM_SYNC_MAX_BYTES);
     }
     get zombieTimerCount() {
         return this.proxy?.zombieTimerCount ?? 0;
@@ -1804,9 +1504,10 @@ class NativeKernel {
         this.pendingLocalMounts.unshift(localMount);
         this.pendingLocalMounts.sort((left, right) => right.path.length - left.path.length);
         if (!this.proxy) {
+            // Pre-boot mounts apply during kernel initialization.
             return;
         }
-        this.proxy.mountFs(mountPath, filesystem, {
+        return this.proxy.mountFs(mountPath, filesystem, {
             readOnly: localMount.readOnly,
             sidecarMount: localMount.sidecarMount,
         });
@@ -1817,7 +1518,7 @@ class NativeKernel {
         if (pendingIndex >= 0) {
             this.pendingLocalMounts.splice(pendingIndex, 1);
         }
-        this.proxy?.unmountFs(mountPath);
+        return this.proxy?.unmountFs(mountPath);
     }
     async readFile(targetPath) {
         await this.ensureReady();
@@ -1917,7 +1618,6 @@ class NativeKernel {
             cwd: REPO_ROOT,
             command: ensureNativeSidecarBinary(),
             args: [],
-            frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
         });
         const session = await client.authenticateAndOpenSession();
         const createVmConfig = {

package/dist/runtime.d.ts

@@ -10,6 +10,7 @@ export interface VirtualDirEntry {
 export interface VirtualStat {
     mode: number;
     size: number;
+    sizeExact?: bigint;
     blocks: number;
     dev: number;
     rdev: number;
@@ -20,7 +21,9 @@ export interface VirtualStat {
     ctimeMs: number;
     birthtimeMs: number;
     ino: number;
+    inoExact?: bigint;
     nlink: number;
+    nlinkExact?: bigint;
     uid: number;
     gid: number;
 }
@@ -45,7 +48,9 @@ export interface VirtualFileSystem {
     lstat(path: string): Promise<VirtualStat>;
     link(oldPath: string, newPath: string): Promise<void>;
     chmod(path: string, mode: number): Promise<void>;
-    chown(path: string, uid: number, gid: number): Promise<void>;
+    chown(path: string, uid: number, gid: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<void>;
     utimes(path: string, atime: number, mtime: number): Promise<void>;
     truncate(path: string, length: number): Promise<void>;
     pread(path: string, offset: number, length: number): Promise<Uint8Array>;
@@ -102,6 +107,7 @@ export interface ManagedProcess {
 export interface ShellHandle {
     pid: number;
     write(data: Uint8Array | string): Promise<void>;
+    /** Ordered PTY output containing stdout and stderr exactly once. */
     onData: ((data: Uint8Array) => void) | null;
     resize(cols: number, rows: number): void;
     kill(signal?: number): void;
@@ -114,6 +120,7 @@ export interface OpenShellOptions {
     cwd?: string;
     cols?: number;
     rows?: number;
+    /** Optional stderr-only diagnostic tap; do not render it alongside `onData`. */
     onStderr?: (data: Uint8Array) => void;
 }
 export interface ConnectTerminalOptions extends OpenShellOptions {
@@ -275,8 +282,8 @@ export interface Kernel extends KernelInterface {
     connectTerminal(options?: ConnectTerminalOptions): Promise<number>;
     mountFs(path: string, fs: VirtualFileSystem, options?: {
         readOnly?: boolean;
-    }): void;
-    unmountFs(path: string): void;
+    }): void | Promise<void>;
+    unmountFs(path: string): void | Promise<void>;
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
     mkdir(path: string): Promise<void>;

package/dist/sandbox.d.ts

@@ -1,5 +1,5 @@
 import type { MountConfig, MountConfigJsonObject, NativeMountPluginDescriptor } from "./agent-os.js";
-import type { ToolKit } from "./host-tools.js";
+import type { Bindings } from "./bindings.js";
 export interface AgentOsSandboxProcessResult {
     stdout?: string;
     stderr?: string;
@@ -86,7 +86,7 @@ declare const sandboxDisposeHooks: unique symbol;
 type SandboxDisposeHook = () => void | Promise<void>;
 export type AgentOsSandboxExpandedOptions = {
     mounts?: MountConfig[];
-    toolKits?: ToolKit[];
+    bindings?: Bindings[];
     [sandboxDisposeHooks]?: SandboxDisposeHook[];
 };
 type ResolvedSandboxOptions = AgentOsSandboxCommonOptions & {
@@ -101,12 +101,12 @@ export type SandboxMountPluginConfig = MountConfigJsonObject & {
     maxFullReadBytes?: number;
 };
 export declare function createSandboxFs(input: ResolvedSandboxOptions | AgentOsSandboxClientOptions): NativeMountPluginDescriptor<SandboxMountPluginConfig>;
-export declare function createSandboxBindings(input: ResolvedSandboxOptions | AgentOsSandboxClientOptions): ToolKit;
+export declare function createSandboxBindings(input: ResolvedSandboxOptions | AgentOsSandboxClientOptions): Bindings;
 export declare function getSandboxDisposeHooks(options: object | undefined): SandboxDisposeHook[];
 export declare function resolveSandboxOptions<T extends {
     sandbox?: AgentOsSandboxInput;
 }>(options: T): Promise<Omit<T, "sandbox"> & {
     mounts?: MountConfig[];
-    toolKits?: ToolKit[];
+    bindings?: Bindings[];
 }>;
 export {};

package/dist/sandbox.js

@@ -49,7 +49,7 @@ export function createSandboxBindings(input) {
     return {
         name: "sandbox",
         description: "Execute commands and manage processes in a remote sandbox environment.",
-        tools: {
+        bindings: {
             "run-command": binding({
                 description: "Run a command synchronously in the sandbox and return its stdout, stderr, and exit code.",
                 inputSchema: z.object({
@@ -252,13 +252,13 @@ export async function resolveSandboxOptions(options) {
             readOnly: sandboxOptions.readOnly,
         },
     ];
-    const toolKits = [
-        ...(expanded.toolKits ?? []),
+    const bindings = [
+        ...(expanded.bindings ?? []),
         createSandboxBindings(sandboxOptions),
     ];
     return attachSandboxDisposeHooks({
         ...expanded,
         mounts,
-        toolKits,
+        bindings,
     }, normalizedSandbox.dispose ? [normalizedSandbox.dispose] : []);
 }