@rivet-dev/agentos-core 0.0.0-agentos-dylib-plugin.473700e

package/dist/agent-os.js

@@ -0,0 +1,3624 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, posix as posixPath, resolve as resolveHostPath, } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateToolkits } from "./host-tools.js";
+import { zodToJsonSchema } from "./host-tools-zod.js";
+import { resolvePublishedSidecarBinary } from "./sidecar/binary.js";
+import { findCargoBinary, resolveCargoBinary } from "./sidecar/cargo.js";
+export { isAcpTimeoutErrorData } from "./json-rpc.js";
+const ACP_PROTOCOL_VERSION = 1;
+const ACP_EXTENSION_NAMESPACE = "dev.rivet.agent-os.acp";
+const SHELL_DISPOSE_TIMEOUT_MS = 5_000;
+/**
+ * Reserved `env` key on `AcpResumeSessionRequest` carrying the resolved adapter
+ * bin entrypoint. The resume wire request omits a dedicated `adapterEntrypoint`
+ * field; the sidecar reads the entrypoint from this key and strips it before
+ * launching the adapter. Must stay in sync with the sidecar constant of the same
+ * name in `crates/agentos-sidecar/src/acp_extension.rs`.
+ */
+const RESUME_ADAPTER_ENTRYPOINT_ENV = "AGENT_OS_RESUME_ADAPTER_ENTRYPOINT";
+function defaultAcpClientCapabilities() {
+    return {
+        fs: {
+            readTextFile: true,
+            writeTextFile: true,
+        },
+        terminal: true,
+    };
+}
+async function waitForTrackedExitPromises(promises, timeoutMs) {
+    if (promises.length === 0) {
+        return;
+    }
+    await Promise.race([
+        Promise.allSettled(promises).then(() => undefined),
+        new Promise((resolve) => {
+            setTimeout(resolve, timeoutMs);
+        }),
+    ]);
+}
+import { AGENT_CONFIGS } from "./agents.js";
+import { getBaseEnvironment, getBaseFilesystemEntries, } from "./base-filesystem.js";
+import { CronManager } from "./cron/cron-manager.js";
+import { TimerScheduleDriver } from "./cron/timer-driver.js";
+import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
+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 { allowAll } from "./runtime-compat.js";
+import { AcpRuntimeKind, decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agent-os-protocol.js";
+import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
+import { createAgentOsSidecarClient, NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
+const LEGACY_PERMISSION_METHOD = "request/permission";
+const ACP_PERMISSION_METHOD = "session/request_permission";
+class AcpDispatchError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "AcpDispatchError";
+        this.code = code;
+        this.data = data;
+    }
+}
+function toJsonRpcNotification(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        value.jsonrpc !== "2.0" ||
+        typeof value.method !== "string") {
+        throw new Error("Invalid JSON-RPC notification from sidecar");
+    }
+    return value;
+}
+function toJsonRpcResponse(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        value.jsonrpc !== "2.0" ||
+        !(typeof value.id === "number" ||
+            typeof value.id === "string" ||
+            value.id === null)) {
+        throw new Error("Invalid JSON-RPC response from sidecar");
+    }
+    return value;
+}
+function toJsonRpcRequest(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        value.jsonrpc !== "2.0" ||
+        !(typeof value.id === "number" ||
+            typeof value.id === "string" ||
+            value.id === null) ||
+        typeof value.method !== "string") {
+        throw new Error("Invalid JSON-RPC request from ACP callback");
+    }
+    return value;
+}
+function toRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function parseAcpJson(value, context) {
+    if (value === null) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new Error(`invalid ACP ${context} JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function parseAcpJsonList(values, context) {
+    return values.map((value, index) => parseAcpJson(value, `${context}[${index}]`));
+}
+function sidecarSessionCreatedFromAcp(response) {
+    return {
+        sessionId: response.sessionId,
+        ...(response.pid !== null ? { pid: response.pid } : {}),
+        modes: parseAcpJson(response.modes, "modes"),
+        configOptions: parseAcpJsonList(response.configOptions, "configOptions"),
+        agentCapabilities: parseAcpJson(response.agentCapabilities, "agentCapabilities"),
+        agentInfo: parseAcpJson(response.agentInfo, "agentInfo"),
+    };
+}
+function sidecarSessionStateFromAcp(response) {
+    return {
+        sessionId: response.sessionId,
+        agentType: response.agentType,
+        processId: response.processId,
+        ...(response.pid !== null ? { pid: response.pid } : {}),
+        closed: response.closed,
+        modes: parseAcpJson(response.modes, "modes"),
+        configOptions: parseAcpJsonList(response.configOptions, "configOptions"),
+        agentCapabilities: parseAcpJson(response.agentCapabilities, "agentCapabilities"),
+        agentInfo: parseAcpJson(response.agentInfo, "agentInfo"),
+    };
+}
+function isLocalCancelledPromptResponse(method, response) {
+    const result = toRecord(response.result);
+    return (method === "session/prompt" &&
+        response.id === null &&
+        response.error === undefined &&
+        result.stopReason === "cancelled");
+}
+const CLOSED_SESSION_ID_RETENTION_LIMIT = 2048;
+const CLOSED_SHELL_ID_RETENTION_LIMIT = 2048;
+class BoundedSet {
+    limit;
+    #entries = new Map();
+    constructor(limit) {
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new Error(`BoundedSet limit must be a positive integer: ${limit}`);
+        }
+        this.limit = limit;
+    }
+    add(value) {
+        if (this.#entries.has(value)) {
+            this.#entries.delete(value);
+        }
+        this.#entries.set(value, undefined);
+        if (this.#entries.size <= this.limit) {
+            return;
+        }
+        const oldest = this.#entries.keys().next();
+        if (!oldest.done) {
+            this.#entries.delete(oldest.value);
+        }
+    }
+    has(value) {
+        return this.#entries.has(value);
+    }
+    delete(value) {
+        return this.#entries.delete(value);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+}
+function shouldDispatchToSessionEventHandlers(notification) {
+    return notification.method === "session/update";
+}
+function toSessionModes(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function toSessionConfigOptions(value) {
+    return Array.isArray(value) ? value : [];
+}
+function toAgentCapabilities(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function toAgentInfo(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    if (typeof value.name !== "string") {
+        return null;
+    }
+    return value;
+}
+function sessionEntryFromInit(sessionId, agentType, initData) {
+    return {
+        sessionId,
+        agentType,
+        processId: "",
+        pid: null,
+        closed: false,
+        modes: initData.modes ?? null,
+        configOptions: initData.configOptions ?? [],
+        capabilities: initData.capabilities ?? {},
+        agentInfo: initData.agentInfo ?? null,
+        eventHandlers: new Set(),
+        permissionHandlers: new Set(),
+        configOverrides: new Map(),
+        pendingPermissionReplies: new Map(),
+    };
+}
+function isOverlayMountConfig(config) {
+    return "filesystem" in config;
+}
+function isNativeMountConfig(config) {
+    return "plugin" in config;
+}
+function asMountConfigJsonObject(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function getHostDirMountPluginConfig(config) {
+    const object = asMountConfigJsonObject(config);
+    if (typeof object.hostPath !== "string") {
+        return null;
+    }
+    const hostPathConfig = {
+        hostPath: object.hostPath,
+    };
+    if (typeof object.readOnly === "boolean") {
+        hostPathConfig.readOnly = object.readOnly;
+    }
+    return hostPathConfig;
+}
+function getSandboxAgentMountPluginConfig(config) {
+    const object = asMountConfigJsonObject(config);
+    if (typeof object.baseUrl !== "string") {
+        return null;
+    }
+    const sandboxConfig = {
+        baseUrl: object.baseUrl,
+    };
+    if (typeof object.token === "string") {
+        sandboxConfig.token = object.token;
+    }
+    if (typeof object.basePath === "string") {
+        sandboxConfig.basePath = object.basePath;
+    }
+    if (typeof object.timeoutMs === "number") {
+        sandboxConfig.timeoutMs = object.timeoutMs;
+    }
+    if (typeof object.maxFullReadBytes === "number") {
+        sandboxConfig.maxFullReadBytes = object.maxFullReadBytes;
+    }
+    if (object.headers &&
+        typeof object.headers === "object" &&
+        !Array.isArray(object.headers)) {
+        const headers = Object.entries(object.headers)
+            .filter(([, value]) => typeof value === "string")
+            .map(([name, value]) => [name, value]);
+        if (headers.length > 0) {
+            sandboxConfig.headers = Object.fromEntries(headers);
+        }
+    }
+    return sandboxConfig;
+}
+function getS3MountPluginConfig(config) {
+    const object = asMountConfigJsonObject(config);
+    if (typeof object.bucket !== "string") {
+        return null;
+    }
+    const s3Config = {
+        bucket: object.bucket,
+    };
+    if (typeof object.prefix === "string") {
+        s3Config.prefix = object.prefix;
+    }
+    if (typeof object.region === "string") {
+        s3Config.region = object.region;
+    }
+    if (typeof object.endpoint === "string") {
+        s3Config.endpoint = object.endpoint;
+    }
+    if (typeof object.chunkSize === "number") {
+        s3Config.chunkSize = object.chunkSize;
+    }
+    if (typeof object.inlineThreshold === "number") {
+        s3Config.inlineThreshold = object.inlineThreshold;
+    }
+    if (object.credentials &&
+        typeof object.credentials === "object" &&
+        !Array.isArray(object.credentials) &&
+        typeof object.credentials.accessKeyId === "string" &&
+        typeof object.credentials.secretAccessKey === "string") {
+        s3Config.credentials = {
+            accessKeyId: object.credentials.accessKeyId,
+            secretAccessKey: object.credentials.secretAccessKey,
+        };
+    }
+    return s3Config;
+}
+function getGoogleDriveMountPluginConfig(config) {
+    const object = asMountConfigJsonObject(config);
+    if (typeof object.folderId !== "string") {
+        return null;
+    }
+    if (!object.credentials ||
+        typeof object.credentials !== "object" ||
+        Array.isArray(object.credentials) ||
+        typeof object.credentials.clientEmail !== "string" ||
+        typeof object.credentials.privateKey !== "string") {
+        return null;
+    }
+    const googleDriveConfig = {
+        credentials: {
+            clientEmail: object.credentials.clientEmail,
+            privateKey: object.credentials.privateKey,
+        },
+        folderId: object.folderId,
+    };
+    if (typeof object.keyPrefix === "string") {
+        googleDriveConfig.keyPrefix = object.keyPrefix;
+    }
+    if (typeof object.chunkSize === "number") {
+        googleDriveConfig.chunkSize = object.chunkSize;
+    }
+    if (typeof object.inlineThreshold === "number") {
+        googleDriveConfig.inlineThreshold = object.inlineThreshold;
+    }
+    return googleDriveConfig;
+}
+const KERNEL_POSIX_BOOTSTRAP_DIRS = [
+    "/dev",
+    "/proc",
+    "/tmp",
+    "/bin",
+    "/lib",
+    "/sbin",
+    "/boot",
+    "/etc",
+    "/root",
+    "/run",
+    "/srv",
+    "/sys",
+    "/opt",
+    "/mnt",
+    "/media",
+    "/home",
+    "/home/user",
+    "/usr",
+    "/usr/bin",
+    "/usr/games",
+    "/usr/include",
+    "/usr/lib",
+    "/usr/libexec",
+    "/usr/man",
+    "/usr/local",
+    "/usr/local/bin",
+    "/usr/sbin",
+    "/usr/share",
+    "/usr/share/man",
+    "/var",
+    "/var/cache",
+    "/var/empty",
+    "/var/lib",
+    "/var/lock",
+    "/var/log",
+    "/var/run",
+    "/var/spool",
+    "/var/tmp",
+    "/etc/agentos",
+];
+const NODE_RUNTIME_BOOTSTRAP_COMMANDS = ["node", "npm", "npx"];
+const KERNEL_COMMAND_STUB = "#!/bin/sh\n# kernel command stub\n";
+const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
+const SIDECAR_BINARY = join(REPO_ROOT, "target/debug/agentos-sidecar");
+const SIDECAR_BUILD_INPUTS = [
+    join(REPO_ROOT, "Cargo.toml"),
+    join(REPO_ROOT, "Cargo.lock"),
+    join(REPO_ROOT, "crates/bridge"),
+    join(REPO_ROOT, "crates/execution"),
+    join(REPO_ROOT, "crates/kernel"),
+    join(REPO_ROOT, "crates/sidecar"),
+];
+let ensuredSidecarBinary = null;
+function isWasmBinaryFile(path) {
+    try {
+        const header = readFileSync(path);
+        return (header.length >= 4 &&
+            header[0] === 0x00 &&
+            header[1] === 0x61 &&
+            header[2] === 0x73 &&
+            header[3] === 0x6d);
+    }
+    catch {
+        return false;
+    }
+}
+function collectBootstrapWasmCommands(commandDirs) {
+    const commands = [];
+    const seen = new Set();
+    for (const dir of commandDirs) {
+        let entries;
+        try {
+            entries = readdirSync(dir).sort((a, b) => a.localeCompare(b));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith(".")) {
+                continue;
+            }
+            const fullPath = join(dir, entry);
+            try {
+                if (statSync(fullPath).isDirectory()) {
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (!isWasmBinaryFile(fullPath) || seen.has(entry)) {
+                continue;
+            }
+            seen.add(entry);
+            commands.push(entry);
+        }
+    }
+    return commands;
+}
+function resolveDeclaredCommandSource(commandDir, commandName, aliases) {
+    let current = commandName;
+    const visited = new Set();
+    while (!visited.has(current)) {
+        visited.add(current);
+        const candidatePath = join(commandDir, current);
+        if (isWasmBinaryFile(candidatePath)) {
+            return candidatePath;
+        }
+        const next = aliases[current];
+        if (!next) {
+            return null;
+        }
+        current = next;
+    }
+    return null;
+}
+function prepareCommandDirs(commandPackages) {
+    const commandDirs = [];
+    const tempDirs = [];
+    try {
+        for (const commandPackage of commandPackages) {
+            commandDirs.push(commandPackage.commandDir);
+            const aliasEntries = Object.entries(commandPackage.aliases)
+                .sort(([leftAlias], [rightAlias]) => leftAlias.localeCompare(rightAlias))
+                .flatMap(([aliasName]) => {
+                const aliasPath = join(commandPackage.commandDir, aliasName);
+                if (isWasmBinaryFile(aliasPath)) {
+                    return [];
+                }
+                const sourcePath = resolveDeclaredCommandSource(commandPackage.commandDir, aliasName, commandPackage.aliases);
+                if (!sourcePath) {
+                    return [];
+                }
+                return [[aliasName, sourcePath]];
+            });
+            if (aliasEntries.length === 0) {
+                continue;
+            }
+            const aliasDir = mkdtempSync(join(tmpdir(), "agent-os-command-aliases-"));
+            for (const [aliasName, sourcePath] of aliasEntries) {
+                writeFileSync(join(aliasDir, aliasName), readFileSync(sourcePath));
+            }
+            tempDirs.push(aliasDir);
+            commandDirs.push(aliasDir);
+        }
+    }
+    catch (error) {
+        for (const tempDir of tempDirs) {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        throw error;
+    }
+    return {
+        commandDirs,
+        dispose() {
+            for (const tempDir of tempDirs) {
+                rmSync(tempDir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+function collectConfiguredLowerPaths(config) {
+    const paths = new Set();
+    for (const lower of config?.lowers ?? []) {
+        if (lower.kind !== "snapshot-export") {
+            continue;
+        }
+        for (const entry of lower.source.filesystem.entries) {
+            paths.add(entry.path);
+        }
+    }
+    return paths;
+}
+function findBootstrapSeedEntry(config, path) {
+    for (const lower of config?.lowers ?? []) {
+        if (lower.kind !== "snapshot-export") {
+            continue;
+        }
+        const entry = lower.source.filesystem.entries.find((candidate) => candidate.path === path);
+        if (entry) {
+            return entry;
+        }
+    }
+    return getBaseFilesystemEntries().find((entry) => entry.path === path);
+}
+function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
+    const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
+    const existingPaths = collectConfiguredLowerPaths(config);
+    if (includesBundledBaseLayer) {
+        for (const entry of getBaseFilesystemEntries()) {
+            existingPaths.add(entry.path);
+        }
+    }
+    const entries = [
+        {
+            path: "/",
+            type: "directory",
+            mode: "755",
+            uid: 0,
+            gid: 0,
+        },
+    ];
+    for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
+        if (existingPaths.has(dir)) {
+            continue;
+        }
+        const seed = findBootstrapSeedEntry(config, dir);
+        entries.push({
+            path: dir,
+            type: "directory",
+            mode: seed?.type === "directory" ? seed.mode : "755",
+            uid: seed?.uid ?? 0,
+            gid: seed?.gid ?? 0,
+        });
+    }
+    if (!includesBundledBaseLayer && !existingPaths.has("/usr/bin/env")) {
+        entries.push({
+            path: "/usr/bin/env",
+            type: "file",
+            mode: "644",
+            uid: 0,
+            gid: 0,
+            content: "AA==",
+            encoding: "base64",
+        });
+    }
+    const uniqueCommands = [...new Set(commandNames)].sort((a, b) => a.localeCompare(b));
+    for (const command of uniqueCommands) {
+        const stubPath = `/bin/${command}`;
+        if (existingPaths.has(stubPath)) {
+            continue;
+        }
+        entries.push({
+            path: stubPath,
+            type: "file",
+            mode: "755",
+            uid: 0,
+            gid: 0,
+            content: KERNEL_COMMAND_STUB,
+            encoding: "utf8",
+        });
+    }
+    for (const entry of sortFilesystemEntries(extraEntries)) {
+        if (existingPaths.has(entry.path)) {
+            continue;
+        }
+        entries.push(entry);
+    }
+    return entries.length > 1 ? createSnapshotExport(entries) : null;
+}
+function buildLiveBootstrapDirectoryEntries(existingPaths, config) {
+    const entries = [];
+    for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
+        if (existingPaths.has(dir)) {
+            continue;
+        }
+        const seed = findBootstrapSeedEntry(config, dir);
+        entries.push({
+            path: dir,
+            kind: "directory",
+            mode: Number.parseInt(seed?.type === "directory" ? seed.mode : "755", 8),
+            uid: seed?.uid ?? 0,
+            gid: seed?.gid ?? 0,
+            executable: true,
+        });
+    }
+    return entries;
+}
+async function bootstrapLiveBootstrapDirectories(client, session, vm, config) {
+    const existingPaths = new Set((await client.snapshotRootFilesystem(session, vm)).map((entry) => entry.path));
+    const entries = buildLiveBootstrapDirectoryEntries(existingPaths, config);
+    if (entries.length === 0) {
+        return;
+    }
+    await client.bootstrapRootFilesystem(session, vm, entries);
+}
+function toSnapshotModeString(mode, kind) {
+    const fallback = kind === "directory" ? 0o755 : kind === "symlink" ? 0o777 : 0o644;
+    return `0${((mode ?? fallback) & 0o7777).toString(8)}`;
+}
+function convertSidecarRootSnapshotEntries(entries) {
+    return entries.map((entry) => {
+        const baseEntry = {
+            path: entry.path,
+            type: entry.kind,
+            mode: toSnapshotModeString(entry.mode, entry.kind),
+            uid: entry.uid ?? 0,
+            gid: entry.gid ?? 0,
+        };
+        if (entry.kind === "file") {
+            return {
+                ...baseEntry,
+                content: entry.content ?? "",
+                encoding: entry.encoding ?? "utf8",
+            };
+        }
+        if (entry.kind === "symlink") {
+            if (entry.target === undefined) {
+                throw new Error(`sidecar root snapshot for ${entry.path} is missing a symlink target`);
+            }
+            return {
+                ...baseEntry,
+                target: entry.target,
+            };
+        }
+        return baseEntry;
+    });
+}
+function ensureNativeSidecarBinary() {
+    // A published install has no in-repo Cargo workspace to build from: resolve
+    // the prebuilt platform binary (or the AGENTOS_SIDECAR_BIN override).
+    if (process.env.AGENTOS_SIDECAR_BIN ||
+        !existsSync(join(REPO_ROOT, "Cargo.toml"))) {
+        return resolvePublishedSidecarBinary();
+    }
+    if (ensuredSidecarBinary &&
+        existsSync(ensuredSidecarBinary) &&
+        !sidecarBinaryNeedsBuild()) {
+        return ensuredSidecarBinary;
+    }
+    if (sidecarBinaryNeedsBuild()) {
+        const cargoBinary = findCargoBinary();
+        if (cargoBinary) {
+            execFileSync(cargoBinary, ["build", "-q", "-p", "agentos-sidecar"], {
+                cwd: REPO_ROOT,
+                stdio: "pipe",
+            });
+        }
+        else if (!existsSync(SIDECAR_BINARY)) {
+            execFileSync(resolveCargoBinary(), ["build", "-q", "-p", "agentos-sidecar"], {
+                cwd: REPO_ROOT,
+                stdio: "pipe",
+            });
+        }
+    }
+    ensuredSidecarBinary = SIDECAR_BINARY;
+    return ensuredSidecarBinary;
+}
+function sidecarBinaryNeedsBuild() {
+    if (!existsSync(SIDECAR_BINARY)) {
+        return true;
+    }
+    const binaryMtimeMs = statSync(SIDECAR_BINARY).mtimeMs;
+    return SIDECAR_BUILD_INPUTS.some((path) => existsSync(path) && latestMtimeMs(path) > binaryMtimeMs);
+}
+function latestMtimeMs(path) {
+    const stats = statSync(path);
+    if (!stats.isDirectory()) {
+        return stats.mtimeMs;
+    }
+    let latest = stats.mtimeMs;
+    for (const entry of readdirSync(path)) {
+        latest = Math.max(latest, latestMtimeMs(join(path, entry)));
+    }
+    return latest;
+}
+function collectGuestCommandPaths(commandDirs) {
+    const guestPaths = new Map();
+    for (const [index, commandDir] of commandDirs.entries()) {
+        let entries;
+        try {
+            entries = readdirSync(commandDir).sort((left, right) => left.localeCompare(right));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith(".")) {
+                continue;
+            }
+            if (!isWasmBinaryFile(join(commandDir, entry)) || guestPaths.has(entry)) {
+                continue;
+            }
+            guestPaths.set(entry, `/__secure_exec/commands/${index}/${entry}`);
+        }
+    }
+    return guestPaths;
+}
+async function resolveCompatLocalMounts(mounts) {
+    if (!mounts) {
+        return [];
+    }
+    const resolved = [];
+    for (const mount of mounts) {
+        if (isNativeMountConfig(mount)) {
+            continue;
+        }
+        if (!isOverlayMountConfig(mount)) {
+            resolved.push({
+                path: posixPath.normalize(mount.path),
+                fs: mount.driver,
+                readOnly: mount.readOnly ?? false,
+            });
+            continue;
+        }
+        const mode = mount.filesystem.mode ?? "ephemeral";
+        const fs = mode === "read-only"
+            ? mount.filesystem.store.createOverlayFilesystem({
+                mode: "read-only",
+                lowers: mount.filesystem.lowers,
+            })
+            : mount.filesystem.store.createOverlayFilesystem({
+                upper: await mount.filesystem.store.createWritableLayer(),
+                lowers: mount.filesystem.lowers,
+            });
+        resolved.push({
+            path: posixPath.normalize(mount.path),
+            fs,
+            readOnly: mode === "read-only",
+        });
+    }
+    return resolved;
+}
+function collectSidecarMountPlan(options) {
+    const sidecarMounts = [];
+    const hostMounts = [];
+    const hostPathMappings = [];
+    const seenMounts = new Set();
+    function pushMount(mount) {
+        const serialized = serializeMountConfigForSidecar(mount);
+        const key = `${serialized.guestPath}\0${serialized.plugin.id}\0${JSON.stringify(serialized.plugin.config)}`;
+        if (seenMounts.has(key)) {
+            return;
+        }
+        seenMounts.add(key);
+        sidecarMounts.push(serialized);
+        if (mount.plugin.id === "host_dir") {
+            const config = getHostDirMountPluginConfig(mount.plugin.config);
+            if (config) {
+                hostPathMappings.push({
+                    vmPath: posixPath.normalize(mount.path),
+                    hostPath: resolveHostPath(config.hostPath),
+                    readOnly: mount.readOnly ?? config.readOnly ?? true,
+                });
+            }
+            if (config && options.mounts?.some((candidate) => candidate === mount)) {
+                hostMounts.push({
+                    vmPath: posixPath.normalize(mount.path),
+                    hostPath: resolveHostPath(config.hostPath),
+                    readOnly: mount.readOnly ?? config.readOnly ?? true,
+                });
+            }
+        }
+    }
+    for (const mount of options.mounts ?? []) {
+        if (!isNativeMountConfig(mount)) {
+            continue;
+        }
+        pushMount(mount);
+    }
+    for (const root of options.softwareRoots) {
+        pushMount({
+            path: root.vmPath,
+            plugin: createHostDirBackend({
+                hostPath: root.hostPath,
+                readOnly: true,
+            }),
+            readOnly: true,
+        });
+    }
+    for (const [index, commandDir] of options.commandDirs.entries()) {
+        pushMount({
+            path: `/__secure_exec/commands/${index}`,
+            plugin: createHostDirBackend({
+                hostPath: commandDir,
+                readOnly: true,
+            }),
+            readOnly: true,
+        });
+    }
+    if (options.shimDir) {
+        pushMount({
+            path: "/usr/local/bin",
+            plugin: createHostDirBackend({
+                hostPath: options.shimDir,
+                readOnly: true,
+            }),
+            readOnly: true,
+        });
+    }
+    hostMounts.sort((left, right) => right.vmPath.length - left.vmPath.length);
+    hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
+    return { sidecarMounts, hostMounts, hostPathMappings };
+}
+function materializeToolShimDir(toolKits) {
+    const shimDir = mkdtempSync(join(tmpdir(), "agent-os-host-tools-shims-"));
+    writeFileSync(join(shimDir, "agentos"), KERNEL_COMMAND_STUB, { mode: 0o755 });
+    for (const toolKit of toolKits) {
+        writeFileSync(join(shimDir, `agentos-${toolKit.name}`), KERNEL_COMMAND_STUB, { mode: 0o755 });
+    }
+    return shimDir;
+}
+function collectToolkitBootstrapCommands(toolKits) {
+    if (toolKits.length === 0) {
+        return [];
+    }
+    return ["agentos", ...toolKits.map((toolKit) => `agentos-${toolKit.name}`)];
+}
+function validationMessage(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "issues" in error &&
+        Array.isArray(error.issues)) {
+        return error.issues
+            .map((issue) => {
+            const path = Array.isArray(issue.path) && issue.path.length > 0
+                ? ` at "${issue.path.join(".")}"`
+                : "";
+            return `${issue.message}${path}`;
+        })
+            .join("; ");
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function toolToSidecarDefinition(tool) {
+    return {
+        description: tool.description,
+        inputSchema: zodToJsonSchema(tool.inputSchema),
+        ...(tool.timeout !== undefined ? { timeoutMs: tool.timeout } : {}),
+        ...(tool.examples && tool.examples.length > 0
+            ? {
+                examples: tool.examples.map((example) => ({
+                    description: example.description,
+                    input: example.input,
+                })),
+            }
+            : {}),
+    };
+}
+function combineInstructions(additionalInstructions, toolReference) {
+    const parts = [additionalInstructions, toolReference]
+        .map((part) => part?.trim())
+        .filter((part) => Boolean(part));
+    if (parts.length === 0) {
+        return null;
+    }
+    return parts.join("\n\n");
+}
+function buildHostToolReference(toolKits) {
+    if (toolKits.length === 0) {
+        return "";
+    }
+    const lines = [
+        "## Available Host Tools",
+        "",
+        "Run `agentos list-tools` to see all available tools.",
+        "",
+    ];
+    for (const toolKit of toolKits) {
+        lines.push(`### ${toolKit.name}`);
+        lines.push("");
+        lines.push(toolKit.description);
+        lines.push("");
+        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
+            const sidecarTool = toolToSidecarDefinition(tool);
+            const signature = buildToolFlagSignature(sidecarTool.inputSchema);
+            const suffix = signature.length > 0 ? ` ${signature}` : "";
+            lines.push(`- \`agentos-${toolKit.name} ${toolName}${suffix}\` — ${tool.description}`);
+        }
+        lines.push("");
+        const toolsWithExamples = Object.entries(toolKit.tools).filter(([, tool]) => tool.examples && tool.examples.length > 0);
+        if (toolsWithExamples.length > 0) {
+            lines.push("**Examples:**");
+            lines.push("");
+            for (const [toolName, tool] of toolsWithExamples) {
+                for (const example of tool.examples ?? []) {
+                    const args = inputToToolFlags(example.input);
+                    const suffix = args.length > 0 ? ` ${args}` : "";
+                    lines.push(`- ${example.description}: \`agentos-${toolKit.name} ${toolName}${suffix}\``);
+                }
+            }
+            lines.push("");
+        }
+        lines.push(`Run \`agentos-${toolKit.name} <tool> --help\` for details.`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function buildToolFlagSignature(schema) {
+    return describeToolFlags(schema)
+        .map((flag) => {
+        if (flag.required) {
+            return `${flag.name} <${flag.type}>`;
+        }
+        return `[${flag.name} <${flag.type}>]`;
+    })
+        .join(" ");
+}
+function describeToolFlags(schema) {
+    const schemaObject = asRecord(schema);
+    const properties = asRecord(schemaObject.properties);
+    const required = Array.isArray(schemaObject.required)
+        ? new Set(schemaObject.required.filter((item) => typeof item === "string"))
+        : new Set();
+    return Object.entries(properties).map(([fieldName, fieldSchema]) => ({
+        name: `--${camelToKebab(fieldName)}`,
+        type: describeToolFlagType(fieldSchema),
+        required: required.has(fieldName),
+    }));
+}
+function describeToolFlagType(schema) {
+    const schemaObject = asRecord(schema);
+    const type = typeof schemaObject.type === "string" ? schemaObject.type : undefined;
+    if (type === "array") {
+        const itemType = describeJsonSchemaScalarType(schemaObject.items);
+        return `${itemType}[]`;
+    }
+    if (type === "string") {
+        const enumValues = Array.isArray(schemaObject.enum)
+            ? schemaObject.enum.filter((item) => typeof item === "string")
+            : [];
+        return enumValues.length > 0 ? enumValues.join("|") : "string";
+    }
+    return type ?? "string";
+}
+function describeJsonSchemaScalarType(schema) {
+    const schemaObject = asRecord(schema);
+    return typeof schemaObject.type === "string" ? schemaObject.type : "string";
+}
+function inputToToolFlags(input) {
+    const inputObject = asRecord(input);
+    return Object.entries(inputObject)
+        .flatMap(([key, value]) => {
+        const flag = `--${camelToKebab(key)}`;
+        if (value === true) {
+            return [flag];
+        }
+        if (value === false) {
+            return [`--no-${camelToKebab(key)}`];
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) => `${flag} ${toolCliString(item)}`);
+        }
+        return [`${flag} ${toolCliString(value)}`];
+    })
+        .join(" ");
+}
+function toolCliString(value) {
+    return typeof value === "string" ? value : (JSON.stringify(value) ?? "null");
+}
+function camelToKebab(value) {
+    return value.replace(/[A-Z]/g, (ch, index) => `${index > 0 ? "-" : ""}${ch.toLowerCase()}`);
+}
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+async function handleHostCallback(request, context) {
+    const payload = request.payload;
+    if (payload.type !== "host_callback") {
+        return {
+            type: "host_callback_result",
+            invocation_id: "unknown",
+            error: `unsupported sidecar request type: ${payload.type}`,
+        };
+    }
+    const command = parseHostCommandCallbackInput(payload.input);
+    if (command) {
+        try {
+            return {
+                type: "host_callback_result",
+                invocation_id: payload.invocation_id,
+                result: await handleHostCommandCallback(command, context),
+            };
+        }
+        catch (error) {
+            return {
+                type: "host_callback_result",
+                invocation_id: payload.invocation_id,
+                error: validationMessage(error),
+            };
+        }
+    }
+    const tool = context.toolMap.get(payload.callback_key);
+    if (!tool) {
+        return {
+            type: "host_callback_result",
+            invocation_id: payload.invocation_id,
+            error: `Unknown tool "${payload.callback_key}"`,
+        };
+    }
+    const permissionMode = toolPermissionMode(context.permissions, payload.callback_key);
+    if (permissionMode !== "allow") {
+        return {
+            type: "host_callback_result",
+            invocation_id: payload.invocation_id,
+            error: `EACCES: blocked by tool.invoke policy for ${payload.callback_key}`,
+        };
+    }
+    const parsed = tool.inputSchema.safeParse(payload.input);
+    if (!parsed.success) {
+        return {
+            type: "host_callback_result",
+            invocation_id: payload.invocation_id,
+            error: validationMessage(parsed.error),
+        };
+    }
+    try {
+        return {
+            type: "host_callback_result",
+            invocation_id: payload.invocation_id,
+            result: await executeHostTool(tool, payload.callback_key, parsed.data),
+        };
+    }
+    catch (error) {
+        return {
+            type: "host_callback_result",
+            invocation_id: payload.invocation_id,
+            error: validationMessage(error),
+        };
+    }
+}
+function buildToolMap(toolKits) {
+    const toolMap = new Map();
+    for (const toolKit of toolKits) {
+        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
+            toolMap.set(`${toolKit.name}:${toolName}`, tool);
+        }
+    }
+    return toolMap;
+}
+function parseHostCommandCallbackInput(input) {
+    const value = asRecord(input);
+    if (value.type !== "command" ||
+        typeof value.command !== "string" ||
+        typeof value.cwd !== "string" ||
+        !Array.isArray(value.args) ||
+        !value.args.every((arg) => typeof arg === "string")) {
+        return null;
+    }
+    return {
+        type: "command",
+        command: value.command,
+        args: value.args,
+        cwd: value.cwd,
+    };
+}
+async function handleHostCommandCallback(command, context) {
+    const directToolKit = context.toolKits.find((toolKit) => `agentos-${toolKit.name}` === command.command);
+    if (command.command === "agentos") {
+        return handleAgentOsRegistryCommand(command, context);
+    }
+    if (directToolKit) {
+        return handleAgentOsToolkitCommand(command, context, directToolKit);
+    }
+    throw new Error(`Unknown host callback command "${command.command}"`);
+}
+async function handleAgentOsRegistryCommand(command, context) {
+    const [subcommand, toolkitName, toolName, ...toolArgs] = command.args;
+    if (!subcommand || isHelpFlag(subcommand)) {
+        return {
+            usage: "agentos <command>: list-tools [toolkit], <toolkit> --help, or <toolkit> <tool> ...",
+        };
+    }
+    if (subcommand === "list-tools") {
+        return toolkitName
+            ? describeToolkitPayload(context.toolKits, toolkitName)
+            : listToolkitsPayload(context.toolKits);
+    }
+    const toolKit = context.toolKits.find((kit) => kit.name === subcommand);
+    if (!toolKit) {
+        throw new Error(`No toolkit "${subcommand}". Available: ${toolkitNames(context.toolKits)}`);
+    }
+    if (!toolkitName || isHelpFlag(toolkitName)) {
+        return describeToolkitPayload(context.toolKits, subcommand);
+    }
+    if (toolName && isHelpFlag(toolName)) {
+        return describeToolPayload(toolKit, toolkitName);
+    }
+    return invokeHostTool({
+        toolKit,
+        toolName: toolkitName,
+        args: [toolName, ...toolArgs].filter((value) => typeof value === "string"),
+        cwd: command.cwd,
+        context,
+    });
+}
+async function handleAgentOsToolkitCommand(command, context, toolKit) {
+    const [toolName, helpOrFirstArg, ...rest] = command.args;
+    if (!toolName || isHelpFlag(toolName)) {
+        return describeToolkitPayload(context.toolKits, toolKit.name);
+    }
+    if (helpOrFirstArg && isHelpFlag(helpOrFirstArg)) {
+        return describeToolPayload(toolKit, toolName);
+    }
+    return invokeHostTool({
+        toolKit,
+        toolName,
+        args: [helpOrFirstArg, ...rest].filter((value) => typeof value === "string"),
+        cwd: command.cwd,
+        context,
+    });
+}
+async function invokeHostTool({ toolKit, toolName, args, cwd, context, }) {
+    const tool = toolKit.tools[toolName];
+    if (!tool) {
+        throw new Error(`No tool "${toolName}" in toolkit "${toolKit.name}". Available: ${toolNames(toolKit)}`);
+    }
+    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}`);
+    }
+    const input = await parseHostToolInput(tool, args, cwd, context.readFile);
+    return executeHostTool(tool, callbackKey, input);
+}
+async function executeHostTool(tool, callbackKey, input) {
+    const parsed = tool.inputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(validationMessage(parsed.error));
+    }
+    return Promise.race([
+        Promise.resolve(tool.execute(parsed.data)),
+        new Promise((_, reject) => {
+            if (tool.timeout === undefined) {
+                return;
+            }
+            setTimeout(() => reject(new Error(`Tool "${callbackKey}" timed out after ${tool.timeout}ms`)), tool.timeout);
+        }),
+    ]);
+}
+async function parseHostToolInput(tool, args, cwd, readFile) {
+    if (args[0] === "--json") {
+        const value = args[1];
+        if (value === undefined) {
+            throw new Error("Flag --json requires a value");
+        }
+        return JSON.parse(value);
+    }
+    if (args[0] === "--json-file") {
+        const value = args[1];
+        if (value === undefined) {
+            throw new Error("Flag --json-file requires a value");
+        }
+        const guestPath = value.startsWith("/")
+            ? posixPath.normalize(value)
+            : posixPath.normalize(`${cwd}/${value}`);
+        const text = new TextDecoder().decode(await readFile(guestPath));
+        return JSON.parse(text);
+    }
+    return parseToolArgv(toolToSidecarDefinition(tool).inputSchema, args);
+}
+function parseToolArgv(schema, argv) {
+    const schemaObject = asRecord(schema);
+    const properties = asRecord(schemaObject.properties);
+    const required = Array.isArray(schemaObject.required)
+        ? new Set(schemaObject.required.filter((value) => typeof value === "string"))
+        : new Set();
+    const flagToField = new Map();
+    for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+        flagToField.set(camelToKebab(fieldName), [fieldName, fieldSchema]);
+    }
+    const input = {};
+    for (let index = 0; index < argv.length;) {
+        const arg = argv[index];
+        if (!arg?.startsWith("--")) {
+            throw new Error(`Unexpected positional argument: "${arg}"`);
+        }
+        const rawFlag = arg.slice(2);
+        const negated = rawFlag.startsWith("no-");
+        const flagName = negated ? rawFlag.slice(3) : rawFlag;
+        const entry = flagToField.get(flagName);
+        if (!entry) {
+            throw new Error(`Unknown flag: --${rawFlag}`);
+        }
+        const [fieldName, fieldSchema] = entry;
+        const fieldType = jsonSchemaType(fieldSchema);
+        if (negated) {
+            if (fieldType !== "boolean") {
+                throw new Error(`Unknown flag: --${rawFlag}`);
+            }
+            input[fieldName] = false;
+            index += 1;
+            continue;
+        }
+        if (fieldType === "boolean") {
+            input[fieldName] = true;
+            index += 1;
+            continue;
+        }
+        const value = argv[index + 1];
+        if (value === undefined) {
+            throw new Error(`Flag --${rawFlag} requires a value`);
+        }
+        if (fieldType === "number" || fieldType === "integer") {
+            const number = Number(value);
+            if (!Number.isFinite(number)) {
+                throw new Error(`Flag --${rawFlag} expects a number, got "${value}"`);
+            }
+            input[fieldName] = number;
+            index += 2;
+            continue;
+        }
+        if (fieldType === "array") {
+            const current = Array.isArray(input[fieldName])
+                ? input[fieldName]
+                : [];
+            const itemSchema = asRecord(fieldSchema).items;
+            const itemType = jsonSchemaType(itemSchema);
+            current.push(itemType === "number" || itemType === "integer" ? Number(value) : value);
+            input[fieldName] = current;
+            index += 2;
+            continue;
+        }
+        input[fieldName] = value;
+        index += 2;
+    }
+    for (const fieldName of required) {
+        if (!(fieldName in input)) {
+            throw new Error(`Missing required flag: --${camelToKebab(fieldName)}`);
+        }
+    }
+    return input;
+}
+function listToolkitsPayload(toolKits) {
+    return {
+        toolkits: toolKits.map((toolKit) => ({
+            name: toolKit.name,
+            description: toolKit.description,
+            tools: Object.keys(toolKit.tools),
+        })),
+    };
+}
+function describeToolkitPayload(toolKits, toolkitName) {
+    const toolKit = toolKits.find((kit) => kit.name === toolkitName);
+    if (!toolKit) {
+        throw new Error(`No toolkit "${toolkitName}". Available: ${toolkitNames(toolKits)}`);
+    }
+    return {
+        name: toolKit.name,
+        description: toolKit.description,
+        tools: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
+            toolName,
+            {
+                description: tool.description,
+                flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
+            },
+        ])),
+    };
+}
+function describeToolPayload(toolKit, toolName) {
+    const tool = toolKit.tools[toolName];
+    if (!tool) {
+        throw new Error(`No tool "${toolName}" in toolkit "${toolKit.name}". Available: ${toolNames(toolKit)}`);
+    }
+    return {
+        toolkit: toolKit.name,
+        tool: toolName,
+        description: tool.description,
+        flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
+        examples: tool.examples?.map((example) => ({
+            description: example.description,
+            input: example.input,
+        })) ?? [],
+    };
+}
+function toolPermissionMode(permissions, callbackKey) {
+    const scope = permissions.tool;
+    if (!scope) {
+        return "deny";
+    }
+    if (typeof scope === "string") {
+        return scope;
+    }
+    let mode = scope.default ?? "deny";
+    for (const rule of scope.rules) {
+        const operations = rule.operations ?? ["*"];
+        const patterns = rule.patterns ?? ["**"];
+        if (operations.some((operation) => operation === "*" || operation === "invoke") &&
+            patterns.some((pattern) => permissionPatternMatches(pattern, callbackKey))) {
+            mode = rule.mode;
+        }
+    }
+    return mode;
+}
+function permissionPatternMatches(pattern, value) {
+    if (pattern === "*" || pattern === "**" || pattern === value) {
+        return true;
+    }
+    const parts = pattern.split(/(\*\*|\*)/u);
+    const source = parts
+        .map((part) => {
+        if (part === "**")
+            return ".*";
+        if (part === "*")
+            return "[^:]*";
+        return part.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("");
+    return new RegExp(`^${source}$`).test(value);
+}
+function toolkitNames(toolKits) {
+    return toolKits.map((toolKit) => toolKit.name).join(", ");
+}
+function toolNames(toolKit) {
+    return Object.keys(toolKit.tools).join(", ");
+}
+function isHelpFlag(value) {
+    return value === "--help" || value === "-h";
+}
+function jsonSchemaType(schema) {
+    const schemaObject = asRecord(schema);
+    return typeof schemaObject.type === "string" ? schemaObject.type : undefined;
+}
+async function registerToolkitsOnSidecar(client, session, vm, toolKits) {
+    if (toolKits.length === 0) {
+        return "";
+    }
+    for (const toolKit of toolKits) {
+        await client.registerHostCallbacks(session, vm, {
+            name: toolKit.name,
+            description: toolKit.description,
+            commandAliases: [`agentos-${toolKit.name}`],
+            registryCommandAliases: ["agentos"],
+            callbacks: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
+                toolName,
+                toolToSidecarDefinition(tool),
+            ])),
+        });
+    }
+    return buildHostToolReference(toolKits);
+}
+export class AgentOs {
+    #kernel;
+    sidecar;
+    _sessions = new Map();
+    _closedSessionIds = new BoundedSet(CLOSED_SESSION_ID_RETENTION_LIMIT);
+    _sessionClosePromises = new Map();
+    _pendingSessionRequestResolvers = new Map();
+    _processes = new Map();
+    _shells = new Map();
+    _closedShellIds = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
+    _pendingShellExitPromises = new Set();
+    _shellCounter = 0;
+    _acpTerminals = new Map();
+    _acpTerminalCounter = 0;
+    _softwareRoots;
+    _softwareAgentConfigs;
+    _cronManager;
+    _toolKits = [];
+    _toolReference = "";
+    _permissions = allowAll;
+    _hostMounts;
+    _env;
+    _rootFilesystem;
+    _sidecarLease = null;
+    _sidecarClient;
+    _sidecarSession;
+    _sidecarVm;
+    _disposeSidecarEventListener;
+    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm) {
+        this.#kernel = kernel;
+        this.sidecar = sidecar;
+        this._softwareRoots = softwareRoots;
+        this._softwareAgentConfigs = softwareAgentConfigs;
+        this._hostMounts = hostMounts;
+        this._env = env;
+        this._rootFilesystem = rootFilesystem;
+        this._sidecarClient = sidecarClient;
+        this._sidecarSession = sidecarSession;
+        this._sidecarVm = sidecarVm;
+        this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
+            this._handleSidecarEvent(event);
+        });
+        agentOsRuntimeAdmins.set(this, {
+            kernel,
+            rootView: rootFilesystem,
+            env,
+            sidecar,
+        });
+    }
+    static async createSidecar(options = {}) {
+        return createAgentOsSidecarInternal(options);
+    }
+    static async getSharedSidecar(options = {}) {
+        return getSharedAgentOsSidecarInternal(options);
+    }
+    static async create(options) {
+        const processed = processSoftware(options?.software ?? []);
+        const localMounts = await resolveCompatLocalMounts(options?.mounts);
+        const toolKits = options?.toolKits;
+        if (toolKits && toolKits.length > 0) {
+            validateToolkits(toolKits);
+        }
+        const createVmAdmin = async () => {
+            const preparedCommandDirs = prepareCommandDirs(processed.commandPackages);
+            const toolBootstrapCommands = collectToolkitBootstrapCommands(toolKits ?? []);
+            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem, [
+                ...collectBootstrapWasmCommands(preparedCommandDirs.commandDirs),
+                ...NODE_RUNTIME_BOOTSTRAP_COMMANDS,
+                ...toolBootstrapCommands,
+            ]);
+            let toolReference = "";
+            let rootBridge = null;
+            let kernel = null;
+            let client = null;
+            let toolShimDir = null;
+            let cleanedUp = false;
+            const cleanup = async () => {
+                if (cleanedUp) {
+                    return;
+                }
+                cleanedUp = true;
+                if (toolShimDir) {
+                    rmSync(toolShimDir, { recursive: true, force: true });
+                    toolShimDir = null;
+                }
+                preparedCommandDirs.dispose();
+            };
+            try {
+                const env = getBaseEnvironment();
+                if (toolKits && toolKits.length > 0) {
+                    toolShimDir = materializeToolShimDir(toolKits);
+                }
+                const commandGuestPaths = collectGuestCommandPaths(preparedCommandDirs.commandDirs);
+                const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
+                    mounts: options?.mounts,
+                    softwareRoots: processed.softwareRoots,
+                    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();
+                const hostPermissions = options?.permissions ?? {
+                    ...allowAll,
+                    tool: "allow",
+                };
+                const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
+                const createVmConfig = {
+                    env,
+                    rootFilesystem: serializeRootFilesystemForSidecar(options?.rootFilesystem, bootstrapLower),
+                    permissions: sidecarPermissions,
+                    limits: options?.limits,
+                    loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
+                    // 0.3: the Node builtin allow-list moved from configureVm to
+                    // VM creation. `undefined` => engine default allow-list;
+                    // `[]` => deny all; `[..]` => exactly those. Platform and
+                    // 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
+                        ? {
+                            jsRuntime: {
+                                platform: "node",
+                                moduleResolution: "node",
+                                allowedBuiltins: options.allowedNodeBuiltins,
+                            },
+                        }
+                        : {}),
+                };
+                const nativeVm = await client.createVm(session, {
+                    runtime: "java_script",
+                    config: createVmConfig,
+                });
+                await client.waitForEvent((event) => event.payload.type === "vm_lifecycle" &&
+                    event.payload.state === "ready", 10_000);
+                await client.configureVm(session, nativeVm, {
+                    mounts: sidecarMounts,
+                    permissions: sidecarPermissions,
+                    commandPermissions: processed.commandPermissions,
+                    loopbackExemptPorts: options?.loopbackExemptPorts,
+                });
+                if (toolKits && toolKits.length > 0) {
+                    toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
+                    commandGuestPaths.set("agentos", "/bin/agentos");
+                    for (const toolKit of toolKits) {
+                        commandGuestPaths.set(`agentos-${toolKit.name}`, `/bin/agentos-${toolKit.name}`);
+                    }
+                }
+                rootBridge = new NativeSidecarKernelProxy({
+                    client,
+                    session,
+                    vm: nativeVm,
+                    env,
+                    cwd: "/home/user",
+                    localMounts,
+                    commandGuestPaths,
+                    onDispose: cleanup,
+                });
+                await bootstrapLiveBootstrapDirectories(client, session, nativeVm, options?.rootFilesystem);
+                kernel = rootBridge;
+                const snapshotClient = client;
+                return {
+                    env,
+                    hostMounts,
+                    kernel,
+                    rootView: rootBridge.createRootView(),
+                    sidecarClient: client,
+                    sidecarSession: session,
+                    sidecarVm: nativeVm,
+                    permissions: hostPermissions,
+                    snapshotRootFilesystem: async () => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm))),
+                    toolKits: toolKits ?? [],
+                    toolReference,
+                    async dispose() {
+                        if (kernel) {
+                            const currentKernel = kernel;
+                            kernel = null;
+                            await currentKernel.dispose();
+                        }
+                        if (rootBridge) {
+                            const currentRootBridge = rootBridge;
+                            rootBridge = null;
+                            await currentRootBridge.dispose();
+                            return;
+                        }
+                        await cleanup();
+                    },
+                };
+            }
+            catch (error) {
+                if (kernel) {
+                    await kernel.dispose().catch(() => { });
+                }
+                if (rootBridge) {
+                    await rootBridge.dispose().catch(() => { });
+                }
+                else {
+                    await client?.dispose().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);
+            vm._sidecarLease = sidecarLease;
+            vm._toolKits = vmAdmin.toolKits;
+            vm._toolReference = vmAdmin.toolReference;
+            vm._permissions = vmAdmin.permissions;
+            vm._installSidecarRequestHandler();
+            vm._cronManager = new CronManager(vm, options?.scheduleDriver ?? new TimerScheduleDriver());
+            return vm;
+        }
+        catch (error) {
+            await sidecarLease?.dispose().catch(() => { });
+            throw error;
+        }
+    }
+    async exec(command, options) {
+        return this.#kernel.exec(command, options);
+    }
+    _trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers) {
+        const entry = {
+            proc,
+            command,
+            args,
+            stdoutHandlers,
+            stderrHandlers,
+            exitHandlers,
+        };
+        this._processes.set(proc.pid, entry);
+        void proc.wait().then((code) => {
+            for (const h of exitHandlers)
+                h(code);
+        });
+        return { pid: proc.pid };
+    }
+    spawn(command, args, options) {
+        const stdoutHandlers = new Set();
+        const stderrHandlers = new Set();
+        const exitHandlers = new Set();
+        // Include caller-provided callbacks in the initial handler sets.
+        if (options?.onStdout)
+            stdoutHandlers.add(options.onStdout);
+        if (options?.onStderr)
+            stderrHandlers.add(options.onStderr);
+        const proc = this.#kernel.spawn(command, args, {
+            ...options,
+            onStdout: (data) => {
+                for (const h of stdoutHandlers)
+                    h(data);
+            },
+            onStderr: (data) => {
+                for (const h of stderrHandlers)
+                    h(data);
+            },
+        });
+        return this._trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers);
+    }
+    /** Write data to a process's stdin. */
+    writeProcessStdin(pid, data) {
+        const entry = this._processes.get(pid);
+        if (!entry)
+            throw new Error(`Process not found: ${pid}`);
+        entry.proc.writeStdin(data);
+    }
+    /** Close a process's stdin stream. */
+    closeProcessStdin(pid) {
+        const entry = this._processes.get(pid);
+        if (!entry)
+            throw new Error(`Process not found: ${pid}`);
+        entry.proc.closeStdin();
+    }
+    /** Subscribe to stdout data from a process. Returns an unsubscribe function. */
+    onProcessStdout(pid, handler) {
+        const entry = this._processes.get(pid);
+        if (!entry)
+            throw new Error(`Process not found: ${pid}`);
+        entry.stdoutHandlers.add(handler);
+        return () => {
+            entry.stdoutHandlers.delete(handler);
+        };
+    }
+    /** Subscribe to stderr data from a process. Returns an unsubscribe function. */
+    onProcessStderr(pid, handler) {
+        const entry = this._processes.get(pid);
+        if (!entry)
+            throw new Error(`Process not found: ${pid}`);
+        entry.stderrHandlers.add(handler);
+        return () => {
+            entry.stderrHandlers.delete(handler);
+        };
+    }
+    /** Subscribe to process exit. Returns an unsubscribe function. */
+    onProcessExit(pid, handler) {
+        const entry = this._processes.get(pid);
+        if (!entry)
+            throw new Error(`Process not found: ${pid}`);
+        // If already exited, call immediately.
+        if (entry.proc.exitCode !== null) {
+            handler(entry.proc.exitCode);
+            return () => { };
+        }
+        entry.exitHandlers.add(handler);
+        return () => {
+            entry.exitHandlers.delete(handler);
+        };
+    }
+    /** Wait for a process to exit. Returns the exit code. */
+    waitProcess(pid) {
+        const entry = this._processes.get(pid);
+        if (!entry)
+            throw new Error(`Process not found: ${pid}`);
+        return entry.proc.wait();
+    }
+    _assertSafeAbsolutePath(path) {
+        if (!path.startsWith("/")) {
+            throw new Error(`Path must be absolute: ${path}`);
+        }
+        if (posixPath.normalize(path) !== path) {
+            throw new Error(`Path must be normalized: ${path}`);
+        }
+    }
+    _assertWritableAbsolutePath(path) {
+        this._assertSafeAbsolutePath(path);
+        if (path === "/proc" || path.startsWith("/proc/")) {
+            throw new Error(`Path is read-only: ${path}`);
+        }
+    }
+    _vfs() {
+        return this.#kernel.vfs;
+    }
+    async _copyPath(from, to) {
+        const stat = await this._vfs().lstat(from);
+        if (stat.isSymbolicLink) {
+            const target = await this._vfs().readlink(from);
+            await this._vfs().symlink(target, to);
+            return;
+        }
+        if (stat.isDirectory) {
+            await this._mkdirp(posixPath.dirname(to));
+            if (!(await this.#kernel.exists(to))) {
+                await this.#kernel.mkdir(to);
+            }
+            await this._vfs().chmod(to, stat.mode);
+            await this._vfs().chown(to, stat.uid, stat.gid);
+            const entries = await this.#kernel.readdir(from);
+            for (const entry of entries) {
+                if (entry === "." || entry === "..")
+                    continue;
+                const fromPath = from === "/" ? `/${entry}` : `${from}/${entry}`;
+                const toPath = to === "/" ? `/${entry}` : `${to}/${entry}`;
+                await this._copyPath(fromPath, toPath);
+            }
+            return;
+        }
+        const content = await this.#kernel.readFile(from);
+        await this.writeFile(to, content);
+        await this._vfs().chmod(to, stat.mode);
+        await this._vfs().chown(to, stat.uid, stat.gid);
+    }
+    async readFile(path) {
+        this._assertSafeAbsolutePath(path);
+        return this.#kernel.readFile(path);
+    }
+    async writeFile(path, content) {
+        this._assertWritableAbsolutePath(path);
+        return this.#kernel.writeFile(path, content);
+    }
+    async writeFiles(entries) {
+        const results = [];
+        for (const entry of entries) {
+            try {
+                this._assertWritableAbsolutePath(entry.path);
+                // Create parent directories as needed
+                const parentDir = entry.path.substring(0, entry.path.lastIndexOf("/"));
+                if (parentDir) {
+                    await this._mkdirp(parentDir);
+                }
+                await this.#kernel.writeFile(entry.path, entry.content);
+                results.push({ path: entry.path, success: true });
+            }
+            catch (err) {
+                results.push({
+                    path: entry.path,
+                    success: false,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return results;
+    }
+    async readFiles(paths) {
+        const results = [];
+        for (const path of paths) {
+            try {
+                this._assertSafeAbsolutePath(path);
+                const content = await this.#kernel.readFile(path);
+                results.push({ path, content });
+            }
+            catch (err) {
+                results.push({
+                    path,
+                    content: null,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return results;
+    }
+    /** Recursively create directories (mkdir -p). */
+    async _mkdirp(path) {
+        this._assertWritableAbsolutePath(path);
+        const parts = path.split("/").filter(Boolean);
+        let current = "";
+        for (const part of parts) {
+            current += `/${part}`;
+            if (!(await this.#kernel.exists(current))) {
+                await this.#kernel.mkdir(current);
+            }
+        }
+    }
+    async mkdir(path, options) {
+        if (options?.recursive) {
+            return this._mkdirp(path);
+        }
+        this._assertSafeAbsolutePath(path);
+        return this.#kernel.mkdir(path);
+    }
+    async readdir(path) {
+        this._assertSafeAbsolutePath(path);
+        return this.#kernel.readdir(path);
+    }
+    async readdirRecursive(path, options) {
+        this._assertSafeAbsolutePath(path);
+        const maxDepth = options?.maxDepth;
+        const exclude = options?.exclude ? new Set(options.exclude) : undefined;
+        const results = [];
+        // BFS queue: [dirPath, currentDepth]
+        const queue = [[path, 0]];
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (!item)
+                break;
+            const [dirPath, depth] = item;
+            const entries = await this.#kernel.readdir(dirPath);
+            for (const name of entries) {
+                if (name === "." || name === "..")
+                    continue;
+                if (exclude?.has(name))
+                    continue;
+                const fullPath = dirPath === "/" ? `/${name}` : `${dirPath}/${name}`;
+                const s = await this.#kernel.stat(fullPath);
+                if (s.isSymbolicLink) {
+                    results.push({
+                        path: fullPath,
+                        type: "symlink",
+                        size: s.size,
+                    });
+                }
+                else if (s.isDirectory) {
+                    results.push({
+                        path: fullPath,
+                        type: "directory",
+                        size: s.size,
+                    });
+                    if (maxDepth === undefined || depth < maxDepth) {
+                        queue.push([fullPath, depth + 1]);
+                    }
+                }
+                else {
+                    results.push({
+                        path: fullPath,
+                        type: "file",
+                        size: s.size,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    async stat(path) {
+        this._assertSafeAbsolutePath(path);
+        return this.#kernel.stat(path);
+    }
+    async exists(path) {
+        this._assertSafeAbsolutePath(path);
+        return this.#kernel.exists(path);
+    }
+    async snapshotRootFilesystem() {
+        const nativeSnapshot = this._sidecarLease?.admin.snapshotRootFilesystem;
+        if (nativeSnapshot) {
+            return nativeSnapshot();
+        }
+        return createSnapshotExport(await snapshotVirtualFilesystem(this._rootFilesystem));
+    }
+    mountFs(path, driver, options) {
+        this._assertSafeAbsolutePath(path);
+        this.#kernel.mountFs(path, driver, { readOnly: options?.readOnly });
+    }
+    unmountFs(path) {
+        this._assertSafeAbsolutePath(path);
+        this.#kernel.unmountFs(path);
+    }
+    async move(from, to) {
+        this._assertSafeAbsolutePath(from);
+        this._assertSafeAbsolutePath(to);
+        const sourceStat = await this._vfs().lstat(from);
+        if (!sourceStat.isDirectory || sourceStat.isSymbolicLink) {
+            return this.#kernel.rename(from, to);
+        }
+        await this._copyPath(from, to);
+        await this.delete(from, { recursive: true });
+    }
+    async delete(path, options) {
+        this._assertSafeAbsolutePath(path);
+        const s = await this.#kernel.stat(path);
+        if (s.isDirectory) {
+            if (options?.recursive) {
+                const entries = await this.#kernel.readdir(path);
+                for (const entry of entries) {
+                    if (entry === "." || entry === "..")
+                        continue;
+                    await this.delete(`${path}/${entry}`, { recursive: true });
+                }
+            }
+            return this.#kernel.removeDir(path);
+        }
+        return this.#kernel.removeFile(path);
+    }
+    async fetch(port, request) {
+        const url = new URL(request.url);
+        const responsePayload = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
+            port,
+            method: request.method,
+            path: `${url.pathname}${url.search}`,
+            headersJson: JSON.stringify(Object.fromEntries(request.headers.entries())),
+            ...(request.method !== "GET" && request.method !== "HEAD"
+                ? { body: await request.text() }
+                : {}),
+        }));
+        const headers = new Headers();
+        for (const [key, value] of responsePayload.headers ?? []) {
+            headers.append(key, value);
+        }
+        return new Response(Buffer.from(responsePayload.body ?? "", "base64"), {
+            status: responsePayload.status,
+            statusText: responsePayload.statusText,
+            headers,
+        });
+    }
+    openShell(options) {
+        const shellId = `shell-${++this._shellCounter}`;
+        this._closedShellIds.delete(shellId);
+        const dataHandlers = new Set();
+        const handle = this.#kernel.openShell(options);
+        handle.onData = (data) => {
+            for (const h of dataHandlers)
+                h(data);
+        };
+        const entry = {
+            handle,
+            dataHandlers,
+            exitPromise: Promise.resolve(),
+        };
+        const exitPromise = handle.wait().then(() => undefined, () => undefined);
+        entry.exitPromise = exitPromise.finally(() => {
+            this._pendingShellExitPromises.delete(entry.exitPromise);
+            if (this._shells.get(shellId) === entry) {
+                this._shells.delete(shellId);
+                this._closedShellIds.add(shellId);
+            }
+        });
+        this._pendingShellExitPromises.add(entry.exitPromise);
+        this._shells.set(shellId, entry);
+        return { shellId };
+    }
+    async connectTerminal(options) {
+        return this.#kernel.connectTerminal(options);
+    }
+    /** Write data to a shell's PTY input. */
+    writeShell(shellId, data) {
+        const entry = this._shells.get(shellId);
+        if (!entry)
+            throw new Error(`Shell not found: ${shellId}`);
+        entry.handle.write(data);
+    }
+    /** Subscribe to data output from a shell. Returns an unsubscribe function. */
+    onShellData(shellId, handler) {
+        const entry = this._shells.get(shellId);
+        if (!entry)
+            throw new Error(`Shell not found: ${shellId}`);
+        entry.dataHandlers.add(handler);
+        return () => {
+            entry.dataHandlers.delete(handler);
+        };
+    }
+    /** Notify a shell of terminal resize. */
+    resizeShell(shellId, cols, rows) {
+        const entry = this._shells.get(shellId);
+        if (!entry)
+            throw new Error(`Shell not found: ${shellId}`);
+        entry.handle.resize(cols, rows);
+    }
+    /** Kill a shell process and remove it from tracking. */
+    closeShell(shellId) {
+        const entry = this._shells.get(shellId);
+        if (!entry) {
+            if (this._closedShellIds.has(shellId)) {
+                return;
+            }
+            throw new Error(`Shell not found: ${shellId}`);
+        }
+        entry.handle.kill();
+        this._shells.delete(shellId);
+        this._closedShellIds.add(shellId);
+    }
+    _resolveVmPathToHostPath(vmPath) {
+        const normalizedVmPath = posixPath.normalize(vmPath);
+        for (const mount of this._hostMounts) {
+            if (normalizedVmPath === mount.vmPath ||
+                normalizedVmPath.startsWith(`${mount.vmPath}/`)) {
+                const relativePath = posixPath.relative(mount.vmPath, normalizedVmPath);
+                if (!relativePath) {
+                    return mount.hostPath;
+                }
+                return join(mount.hostPath, ...relativePath.split("/").filter(Boolean));
+            }
+        }
+        return null;
+    }
+    /** Returns info about all processes spawned via spawn(). */
+    listProcesses() {
+        return [...this._processes.values()].map(({ proc, command, args }) => ({
+            pid: proc.pid,
+            command,
+            args,
+            running: proc.exitCode === null,
+            exitCode: proc.exitCode,
+        }));
+    }
+    /** Returns all kernel processes across all active runtimes (WASM and Node). */
+    allProcesses() {
+        if (this.#kernel instanceof NativeSidecarKernelProxy) {
+            return this.#kernel.snapshotProcesses();
+        }
+        return [...this.#kernel.processes.values()];
+    }
+    /** Returns processes organized as a tree using ppid relationships. */
+    processTree() {
+        const all = this.allProcesses();
+        const nodeMap = new Map();
+        // Index: create a tree node for each process
+        for (const proc of all) {
+            nodeMap.set(proc.pid, { ...proc, children: [] });
+        }
+        // Wire: attach each node to its parent
+        const roots = [];
+        for (const node of nodeMap.values()) {
+            const parent = nodeMap.get(node.ppid);
+            if (parent) {
+                parent.children.push(node);
+            }
+            else {
+                roots.push(node);
+            }
+        }
+        return roots;
+    }
+    /** Returns info about a specific process by PID. Throws if not found. */
+    getProcess(pid) {
+        const entry = this._processes.get(pid);
+        if (!entry) {
+            throw new Error(`Process not found: ${pid}`);
+        }
+        return {
+            pid: entry.proc.pid,
+            command: entry.command,
+            args: entry.args,
+            running: entry.proc.exitCode === null,
+            exitCode: entry.proc.exitCode,
+        };
+    }
+    /** Send SIGTERM to gracefully stop a process. No-op if already exited. */
+    stopProcess(pid) {
+        const entry = this._processes.get(pid);
+        if (!entry) {
+            throw new Error(`Process not found: ${pid}`);
+        }
+        if (entry.proc.exitCode !== null)
+            return;
+        entry.proc.kill();
+    }
+    /** Send SIGKILL to force-kill a process. No-op if already exited. */
+    killProcess(pid) {
+        const entry = this._processes.get(pid);
+        if (!entry) {
+            throw new Error(`Process not found: ${pid}`);
+        }
+        if (entry.proc.exitCode !== null)
+            return;
+        entry.proc.kill(9);
+    }
+    /** Returns all active sessions with their IDs and agent types. */
+    listSessions() {
+        return [...this._sessions.values()].map((s) => ({
+            sessionId: s.sessionId,
+            agentType: s.agentType,
+        }));
+    }
+    /** Internal helper: retrieve a session or throw. */
+    _requireSession(sessionId) {
+        const session = this._sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        return session;
+    }
+    /** Returns all registered agents with their installation status. */
+    listAgents() {
+        // Collect all agent IDs from both package configs and hardcoded configs.
+        const allIds = new Set([
+            ...this._softwareAgentConfigs.keys(),
+            ...Object.keys(AGENT_CONFIGS),
+        ]);
+        return [...allIds]
+            .map((id) => {
+            const config = this._resolveAgentConfig(id);
+            if (!config)
+                return null;
+            let installed = false;
+            try {
+                // Check software roots first, then the host dir behind the
+                // `/root/node_modules` mount.
+                const vmPrefix = `/root/node_modules/${config.acpAdapter}`;
+                let hostPkgJsonPath = null;
+                for (const root of this._softwareRoots) {
+                    if (root.vmPath === vmPrefix) {
+                        hostPkgJsonPath = join(root.hostPath, "package.json");
+                        break;
+                    }
+                }
+                if (!hostPkgJsonPath) {
+                    const nodeModulesRoot = this._nodeModulesHostRoot();
+                    if (nodeModulesRoot) {
+                        hostPkgJsonPath = join(resolvePackageDir(nodeModulesRoot, config.acpAdapter), "package.json");
+                    }
+                }
+                if (!hostPkgJsonPath) {
+                    throw new Error("no package source");
+                }
+                readFileSync(hostPkgJsonPath);
+                installed = true;
+            }
+            catch {
+                // Package not installed
+            }
+            return {
+                id,
+                acpAdapter: config.acpAdapter,
+                agentPackage: config.agentPackage,
+                installed,
+            };
+        })
+            .filter((entry) => entry !== null);
+    }
+    _syncSessionState(session, state) {
+        session.processId = state.processId;
+        session.pid = state.pid ?? null;
+        session.closed = state.closed;
+        session.modes = toSessionModes(state.modes);
+        session.configOptions = toSessionConfigOptions(state.configOptions);
+        this._applySyntheticConfigOverrides(session);
+        session.capabilities = toAgentCapabilities(state.agentCapabilities);
+        session.agentInfo = toAgentInfo(state.agentInfo);
+    }
+    _applySessionUpdate(session, notification) {
+        if (notification.method !== "session/update") {
+            return;
+        }
+        const params = toRecord(notification.params);
+        const update = toRecord(params.update ?? params);
+        const sessionUpdate = update.sessionUpdate;
+        if (sessionUpdate === "current_mode_update" &&
+            typeof update.currentModeId === "string" &&
+            session.modes) {
+            session.modes = {
+                ...session.modes,
+                currentModeId: update.currentModeId,
+            };
+        }
+        if ((sessionUpdate === "config_option_update" ||
+            sessionUpdate === "config_options_update") &&
+            Array.isArray(update.configOptions)) {
+            session.configOptions = update.configOptions;
+        }
+    }
+    _recordSessionNotification(session, notification) {
+        this._applySessionUpdate(session, notification);
+        if (shouldDispatchToSessionEventHandlers(notification)) {
+            this._dispatchSessionEvent(session, notification);
+        }
+        if (notification.method === LEGACY_PERMISSION_METHOD ||
+            notification.method === ACP_PERMISSION_METHOD) {
+            const params = toRecord(notification.params);
+            const permissionId = params.permissionId;
+            if (typeof permissionId === "string" ||
+                typeof permissionId === "number") {
+                const request = {
+                    permissionId: String(permissionId),
+                    description: typeof params.description === "string"
+                        ? params.description
+                        : undefined,
+                    params,
+                };
+                for (const handler of session.permissionHandlers) {
+                    handler(request);
+                }
+            }
+        }
+    }
+    _dispatchSessionEvent(session, notification) {
+        if (session.eventHandlers.size === 0) {
+            return;
+        }
+        for (const subscriber of [...session.eventHandlers]) {
+            try {
+                subscriber.handler(notification);
+            }
+            catch {
+                // Ignore subscriber callback failures and keep event delivery moving.
+            }
+        }
+    }
+    _subscribeSessionEvents(session, handler) {
+        const subscriber = {
+            handler,
+        };
+        session.eventHandlers.add(subscriber);
+        return () => {
+            session.eventHandlers.delete(subscriber);
+        };
+    }
+    _applySyntheticConfigOverrides(session) {
+        if (session.configOverrides.size === 0) {
+            return;
+        }
+        session.configOptions = session.configOptions.map((option) => {
+            const override = session.configOverrides.get(option.id) ??
+                (typeof option.category === "string"
+                    ? session.configOverrides.get(option.category)
+                    : undefined);
+            return override === undefined
+                ? option
+                : { ...option, currentValue: override };
+        });
+    }
+    _handleSidecarEvent(event) {
+        if (event.payload.type === "ext") {
+            this._handleAcpExtEvent(event.payload.envelope);
+            return;
+        }
+        if (event.payload.type !== "structured") {
+            return;
+        }
+        if (event.payload.name !== "acp.session_event") {
+            return;
+        }
+        const sessionId = event.payload.detail.session_id;
+        const session = sessionId ? this._sessions.get(sessionId) : undefined;
+        if (!session) {
+            return;
+        }
+        const notificationText = event.payload.detail.notification;
+        if (typeof notificationText !== "string") {
+            return;
+        }
+        try {
+            this._recordSessionNotification(session, toJsonRpcNotification(JSON.parse(notificationText)));
+        }
+        catch {
+            // Ignore malformed event payloads from the sidecar.
+        }
+    }
+    _handleAcpExtEvent(envelope) {
+        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+            return;
+        }
+        try {
+            const event = decodeAcpEvent(envelope.payload);
+            switch (event.tag) {
+                case "AcpSessionEvent": {
+                    const session = this._sessions.get(event.val.sessionId);
+                    if (!session) {
+                        return;
+                    }
+                    this._recordSessionNotification(session, toJsonRpcNotification(JSON.parse(event.val.notification)));
+                    return;
+                }
+            }
+        }
+        catch {
+            // Ignore malformed event payloads from the sidecar.
+        }
+    }
+    _unsupportedConfigResponse(agentType, category) {
+        const message = agentType === "opencode" && category === "model"
+            ? "OpenCode reports available models, but model switching must be configured before createSession() because ACP session/set_config_option is not implemented."
+            : `The ${category} config option is read-only for ${agentType} sessions.`;
+        return {
+            jsonrpc: "2.0",
+            id: null,
+            error: {
+                code: -32601,
+                message,
+            },
+        };
+    }
+    async _sendAcpRequest(request) {
+        const envelope = await this._sidecarClient.extensionRequest(this._sidecarSession, this._sidecarVm, {
+            namespace: ACP_EXTENSION_NAMESPACE,
+            payload: encodeAcpRequest(request),
+        });
+        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+            throw new Error(`unexpected ACP Ext namespace: ${envelope.namespace}`);
+        }
+        const response = decodeAcpResponse(envelope.payload);
+        if (response.tag === "AcpErrorResponse") {
+            const error = new Error(response.val.message);
+            error.code = response.val.code;
+            throw error;
+        }
+        return response;
+    }
+    async _sendSessionRequest(sessionId, method, params) {
+        const session = this._requireSession(sessionId);
+        const response = await new Promise((resolve, reject) => {
+            const resolvers = this._pendingSessionRequestResolvers.get(sessionId) ?? new Set();
+            const resolver = {
+                method,
+                resolve: (response) => {
+                    resolve(response);
+                },
+            };
+            resolvers.add(resolver);
+            this._pendingSessionRequestResolvers.set(sessionId, resolvers);
+            void this._sendAcpRequest({
+                tag: "AcpSessionRequest",
+                val: {
+                    sessionId,
+                    method,
+                    params: params === undefined ? null : JSON.stringify(params),
+                },
+            })
+                .then((response) => {
+                if (response.tag !== "AcpSessionRpcResponse") {
+                    throw new Error(`unexpected response to AcpSessionRequest: ${response.tag}`);
+                }
+                return toJsonRpcResponse(JSON.parse(response.val.response));
+            })
+                .then(resolve, reject)
+                .finally(() => {
+                const nextResolvers = this._pendingSessionRequestResolvers.get(sessionId);
+                if (!nextResolvers) {
+                    return;
+                }
+                nextResolvers.delete(resolver);
+                if (nextResolvers.size === 0) {
+                    this._pendingSessionRequestResolvers.delete(sessionId);
+                }
+            });
+        });
+        const liveSession = this._sessions.get(sessionId);
+        if (liveSession && !isLocalCancelledPromptResponse(method, response)) {
+            await this._hydrateSessionState(liveSession).catch(() => { });
+        }
+        if (!response.error) {
+            if (method === "session/set_mode" &&
+                typeof params?.modeId === "string" &&
+                session.modes) {
+                session.modes = {
+                    ...session.modes,
+                    currentModeId: params.modeId,
+                };
+            }
+            if (method === "session/set_config_option" &&
+                typeof params?.configId === "string" &&
+                typeof params?.value === "string") {
+                const nextValue = params.value;
+                const updatedOption = session.configOptions.find((option) => option.id === params.configId);
+                session.configOverrides.set(params.configId, nextValue);
+                if (typeof updatedOption?.category === "string") {
+                    session.configOverrides.set(updatedOption.category, nextValue);
+                }
+                session.configOptions = session.configOptions.map((option) => option.id === params.configId
+                    ? { ...option, currentValue: nextValue }
+                    : option);
+            }
+        }
+        return response;
+    }
+    async _setSessionConfigByCategory(sessionId, category, value) {
+        const session = this._requireSession(sessionId);
+        const option = session.configOptions.find((entry) => entry.category === category);
+        if (option?.readOnly) {
+            return this._unsupportedConfigResponse(session.agentType, category);
+        }
+        const response = await this._sendSessionRequest(sessionId, "session/set_config_option", {
+            configId: option?.id ?? category,
+            value,
+        });
+        return response;
+    }
+    _removeSession(sessionId) {
+        this._sessions.delete(sessionId);
+    }
+    _abortPendingSessionRequests(sessionId) {
+        const resolvers = this._pendingSessionRequestResolvers.get(sessionId);
+        if (!resolvers) {
+            return;
+        }
+        this._pendingSessionRequestResolvers.delete(sessionId);
+        const response = {
+            jsonrpc: "2.0",
+            id: null,
+            error: {
+                code: -32_000,
+                message: `Session closed: ${sessionId}`,
+            },
+        };
+        for (const resolver of resolvers) {
+            resolver.resolve(response);
+        }
+    }
+    _cancelPendingPromptRequests(sessionId) {
+        const resolvers = this._pendingSessionRequestResolvers.get(sessionId);
+        if (!resolvers) {
+            return false;
+        }
+        const response = {
+            jsonrpc: "2.0",
+            id: null,
+            result: {
+                stopReason: "cancelled",
+            },
+        };
+        let cancelledPrompt = false;
+        for (const resolver of [...resolvers]) {
+            if (resolver.method !== "session/prompt") {
+                continue;
+            }
+            resolvers.delete(resolver);
+            resolver.resolve(response);
+            cancelledPrompt = true;
+        }
+        if (resolvers.size === 0) {
+            this._pendingSessionRequestResolvers.delete(sessionId);
+        }
+        return cancelledPrompt;
+    }
+    _rejectPendingPermissionReplies(sessionId) {
+        const session = this._sessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        this._rejectPendingPermissionRepliesFromSession(session);
+    }
+    _rejectPendingPermissionRepliesFromSession(session) {
+        for (const [permissionId, pendingReply,] of session.pendingPermissionReplies) {
+            clearTimeout(pendingReply.timer);
+            pendingReply.reject(new Error(`Session closed before permission reply: ${permissionId}`));
+        }
+        session.pendingPermissionReplies.clear();
+    }
+    async _closeSessionInternal(sessionId) {
+        const closing = this._sessionClosePromises.get(sessionId);
+        if (closing) {
+            return closing;
+        }
+        if (this._closedSessionIds.has(sessionId)) {
+            return;
+        }
+        this._abortPendingSessionRequests(sessionId);
+        this._rejectPendingPermissionReplies(sessionId);
+        this._requireSession(sessionId);
+        this._removeSession(sessionId);
+        this._closedSessionIds.add(sessionId);
+        const closePromise = this._sendAcpRequest({
+            tag: "AcpCloseSessionRequest",
+            val: { sessionId },
+        })
+            .then((response) => {
+            if (response.tag !== "AcpSessionClosedResponse") {
+                throw new Error(`unexpected response to AcpCloseSessionRequest: ${response.tag}`);
+            }
+        })
+            .finally(() => {
+            this._sessionClosePromises.delete(sessionId);
+        });
+        this._sessionClosePromises.set(sessionId, closePromise);
+        await closePromise;
+    }
+    async _hydrateSessionState(session) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionStateRequest",
+            val: { sessionId: session.sessionId },
+        });
+        if (response.tag !== "AcpSessionStateResponse") {
+            throw new Error(`unexpected response to AcpGetSessionStateRequest: ${response.tag}`);
+        }
+        const state = sidecarSessionStateFromAcp(response.val);
+        this._syncSessionState(session, state);
+    }
+    async createSession(agentType, options) {
+        const config = this._resolveAgentConfig(agentType);
+        if (!config) {
+            throw new Error(`Unknown agent type: ${agentType}`);
+        }
+        // System-prompt assembly and injection (launch args / OPENCODE_CONTEXTPATHS) are owned by
+        // the sidecar at AcpCreateSessionRequest. The host only forwards additionalInstructions /
+        // skipOsInstructions plus the agent's static launch args and env.
+        const launchArgs = [...(config.launchArgs ?? [])];
+        let launchEnv = { ...config.defaultEnv, ...options?.env };
+        const sessionCwd = options?.cwd ?? "/home/user";
+        const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
+        if ((agentType === "pi" || agentType === "pi-cli") &&
+            !launchEnv.PI_ACP_PI_COMMAND) {
+            launchEnv = {
+                ...launchEnv,
+                PI_ACP_PI_COMMAND: this._resolvePackageBin(config.agentPackage, "pi"),
+            };
+        }
+        const response = await this._sendAcpRequest({
+            tag: "AcpCreateSessionRequest",
+            val: {
+                agentType: String(agentType),
+                runtime: AcpRuntimeKind.JavaScript,
+                adapterEntrypoint,
+                args: launchArgs,
+                env: new Map(Object.entries(launchEnv)),
+                cwd: sessionCwd,
+                mcpServers: JSON.stringify(options?.mcpServers ?? []),
+                protocolVersion: ACP_PROTOCOL_VERSION,
+                clientCapabilities: JSON.stringify(defaultAcpClientCapabilities()),
+                additionalInstructions: combineInstructions(options?.additionalInstructions, this._toolReference),
+                skipOsInstructions: options?.skipOsInstructions ?? false,
+            },
+        });
+        if (response.tag !== "AcpSessionCreatedResponse") {
+            throw new Error(`unexpected create_session response: ${response.tag}`);
+        }
+        const created = sidecarSessionCreatedFromAcp(response.val);
+        // The sessionId is chosen by the (untrusted/buggy) ACP adapter or sidecar. If it collides
+        // with a live session already in `_sessions`, blindly overwriting the entry would orphan the
+        // first session's event/permission handlers and pending permission replies. Fail closed:
+        // reject the colliding create and leave the original session intact. (A previously-closed,
+        // evicted id may still be re-used; only a live, non-closed entry is a collision.)
+        const existing = this._sessions.get(created.sessionId);
+        if (existing !== undefined && !existing.closed) {
+            throw new Error(`session id collision: ${created.sessionId}`);
+        }
+        const initData = {
+            modes: toSessionModes(created.modes) ?? undefined,
+            configOptions: toSessionConfigOptions(created.configOptions),
+            capabilities: toAgentCapabilities(created.agentCapabilities),
+            agentInfo: toAgentInfo(created.agentInfo) ?? undefined,
+        };
+        const session = sessionEntryFromInit(created.sessionId, String(agentType), initData);
+        this._closedSessionIds.delete(created.sessionId);
+        this._sessions.set(created.sessionId, session);
+        try {
+            await this._hydrateSessionState(session);
+        }
+        catch (error) {
+            this._removeSession(created.sessionId);
+            throw error;
+        }
+        return { sessionId: created.sessionId };
+    }
+    /**
+     * Resume a session that exists in durable storage but is not live in this VM
+     * (e.g. after a Rivet actor slept and woke with a fresh VM). Thin forwarder:
+     * resolves the agent config + adapter entrypoint exactly as {@link createSession}
+     * does, then forwards a single `AcpResumeSessionRequest` to the sidecar, which
+     * owns the resume state machine (native `session/load` when the agent supports
+     * it, else `session/new` + a transcript-continuation preamble). The returned
+     * `sessionId` is the live id in this VM (equal to the requested id for native
+     * loads, freshly assigned for the fallback); the caller remaps `external -> live`.
+     * The new live session is registered + hydrated locally so subsequent prompts
+     * route to it.
+     *
+     * Resume depends on a durable root; on a non-durable (default in-memory) root
+     * there is no surviving store and the fallback tier always runs.
+     */
+    async resumeSession(sessionId, agentType, options) {
+        const config = this._resolveAgentConfig(agentType);
+        if (!config) {
+            throw new Error(`Unknown agent type: ${agentType}`);
+        }
+        const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
+        let launchEnv = { ...config.defaultEnv, ...options?.env };
+        const sessionCwd = options?.cwd ?? "/home/user";
+        if ((agentType === "pi" || agentType === "pi-cli") &&
+            !launchEnv.PI_ACP_PI_COMMAND) {
+            launchEnv = {
+                ...launchEnv,
+                PI_ACP_PI_COMMAND: this._resolvePackageBin(config.agentPackage, "pi"),
+            };
+        }
+        // The resume wire request has no dedicated `adapterEntrypoint` field; carry
+        // the resolved entrypoint through env under the sidecar's reserved key. The
+        // sidecar reads it and strips it before launching the adapter.
+        launchEnv = {
+            ...launchEnv,
+            [RESUME_ADAPTER_ENTRYPOINT_ENV]: adapterEntrypoint,
+        };
+        const response = await this._sendAcpRequest({
+            tag: "AcpResumeSessionRequest",
+            val: {
+                sessionId,
+                agentType: String(agentType),
+                transcriptPath: options?.transcriptPath ?? null,
+                cwd: sessionCwd,
+                env: new Map(Object.entries(launchEnv)),
+            },
+        });
+        if (response.tag !== "AcpSessionResumedResponse") {
+            throw new Error(`unexpected resume_session response: ${response.tag}`);
+        }
+        const { sessionId: liveSessionId, mode } = response.val;
+        // Register + hydrate the live session so subsequent prompts route to it.
+        const session = sessionEntryFromInit(liveSessionId, String(agentType), {});
+        this._closedSessionIds.delete(liveSessionId);
+        this._sessions.set(liveSessionId, session);
+        try {
+            await this._hydrateSessionState(session);
+        }
+        catch (error) {
+            this._removeSession(liveSessionId);
+            throw error;
+        }
+        return { sessionId: liveSessionId, mode };
+    }
+    /**
+     * Resolve the VM bin entry point of an ACP adapter package.
+     * Reads from the host filesystem since kernel.readFile() resolves through
+     * mounts; adapter package.json is read directly off the host dir backing
+     * the relevant mount.
+     */
+    _resolveAdapterBin(adapterPackage) {
+        return this._resolvePackageBin(adapterPackage);
+    }
+    /**
+     * Parent of the host directory backing the `/root/node_modules` mount, if
+     * the caller supplied one (e.g. via `nodeModulesMount(...)`). Used as the
+     * `resolvePackageDir` start dir for adapter/agent package resolution when no
+     * software root matches. `nodeModulesMount` mounts `<dir>/node_modules`, so
+     * the start dir is `<dir>` (one level above the node_modules tree).
+     */
+    _nodeModulesHostRoot() {
+        for (const mount of this._hostMounts) {
+            if (mount.vmPath === "/root/node_modules") {
+                return dirname(mount.hostPath);
+            }
+        }
+        return null;
+    }
+    _resolvePackageBin(packageName, binName) {
+        const vmPrefix = `/root/node_modules/${packageName}`;
+        let hostPkgJsonPath = null;
+        for (const root of this._softwareRoots) {
+            if (root.vmPath === vmPrefix) {
+                hostPkgJsonPath = join(root.hostPath, "package.json");
+                break;
+            }
+        }
+        // Fall back to the host dir behind the `/root/node_modules` mount.
+        if (!hostPkgJsonPath) {
+            const nodeModulesRoot = this._nodeModulesHostRoot();
+            if (!nodeModulesRoot) {
+                throw new Error(`Cannot resolve package "${packageName}": no software root provides it and ` +
+                    `no /root/node_modules mount was supplied. Pass ` +
+                    `mounts: [nodeModulesMount("<host>/node_modules")] to AgentOs.create().`);
+            }
+            hostPkgJsonPath = join(resolvePackageDir(nodeModulesRoot, packageName), "package.json");
+        }
+        const pkg = JSON.parse(readFileSync(hostPkgJsonPath, "utf-8"));
+        let binEntry;
+        if (typeof pkg.bin === "string") {
+            binEntry = pkg.bin;
+        }
+        else if (typeof pkg.bin === "object" && pkg.bin !== null) {
+            binEntry =
+                (binName ? pkg.bin[binName] : undefined) ??
+                    pkg.bin[packageName] ??
+                    Object.values(pkg.bin)[0];
+        }
+        if (!binEntry) {
+            throw new Error(`No bin entry found in ${packageName}/package.json`);
+        }
+        return `${vmPrefix}/${binEntry}`;
+    }
+    _installSidecarRequestHandler() {
+        const context = {
+            toolKits: this._toolKits,
+            toolMap: buildToolMap(this._toolKits),
+            permissions: this._permissions,
+            readFile: (path) => this.readFile(path),
+        };
+        this._sidecarClient.setSidecarRequestHandler((request) => {
+            switch (request.payload.type) {
+                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}`,
+                    });
+                case "ext":
+                    return this._handleAcpExtSidecarRequest(request.payload.envelope);
+            }
+        });
+    }
+    async _handleAcpExtSidecarRequest(envelope) {
+        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+            return {
+                type: "ext_result",
+                envelope: {
+                    namespace: envelope.namespace,
+                    payload: Buffer.from("unknown extension namespace", "utf8"),
+                },
+            };
+        }
+        const callback = decodeAcpCallback(envelope.payload);
+        switch (callback.tag) {
+            case "AcpPermissionCallback": {
+                const reply = await this._handleAcpPermissionCallback(callback.val.sessionId, callback.val.permissionId, {
+                    ...toRecord(JSON.parse(callback.val.params)),
+                    _acpMethod: ACP_PERMISSION_METHOD,
+                });
+                return {
+                    type: "ext_result",
+                    envelope: {
+                        namespace: ACP_EXTENSION_NAMESPACE,
+                        payload: encodeAcpCallbackResponse({
+                            tag: "AcpPermissionCallbackResponse",
+                            val: {
+                                permissionId: callback.val.permissionId,
+                                reply,
+                            },
+                        }),
+                    },
+                };
+            }
+            case "AcpHostRequestCallback": {
+                const response = await this._dispatchAcpSidecarRequest(toJsonRpcRequest(JSON.parse(callback.val.request)));
+                return {
+                    type: "ext_result",
+                    envelope: {
+                        namespace: ACP_EXTENSION_NAMESPACE,
+                        payload: encodeAcpCallbackResponse({
+                            tag: "AcpHostRequestCallbackResponse",
+                            val: {
+                                response: JSON.stringify(response),
+                            },
+                        }),
+                    },
+                };
+            }
+        }
+    }
+    async _dispatchAcpSidecarRequest(request) {
+        try {
+            const result = await this._handleSupportedAcpSidecarRequest(request);
+            return {
+                jsonrpc: "2.0",
+                id: request.id,
+                result,
+            };
+        }
+        catch (error) {
+            if (error instanceof AcpDispatchError) {
+                return {
+                    jsonrpc: "2.0",
+                    id: request.id,
+                    error: {
+                        code: error.code,
+                        message: error.message,
+                        ...(error.data ? { data: error.data } : {}),
+                    },
+                };
+            }
+            return {
+                jsonrpc: "2.0",
+                id: request.id,
+                error: {
+                    code: -32603,
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    async _handleSupportedAcpSidecarRequest(request) {
+        const params = this._acpParams(request);
+        switch (request.method) {
+            case ACP_PERMISSION_METHOD:
+                return this._handleAcpPermissionRequest(request, params);
+            case "fs/read":
+            case "fs/read_text_file":
+                return this._handleAcpReadFile(params);
+            case "fs/write":
+            case "fs/write_text_file":
+                return this._handleAcpWriteFile(params);
+            case "fs/readDir":
+            case "fs/read_dir":
+                return this._handleAcpReadDir(params);
+            case "terminal/create":
+                return this._handleAcpCreateTerminal(params);
+            case "terminal/write":
+                return this._handleAcpWriteTerminal(params);
+            case "terminal/output":
+            case "terminal/read":
+                return this._handleAcpReadTerminal(params);
+            case "terminal/wait_for_exit":
+            case "terminal/waitForExit":
+                return this._handleAcpWaitForTerminalExit(params);
+            case "terminal/kill":
+                return this._handleAcpKillTerminal(params);
+            case "terminal/release":
+            case "terminal/close":
+                return this._handleAcpReleaseTerminal(params);
+            case "terminal/resize":
+                return this._handleAcpResizeTerminal(params);
+            default:
+                throw new AcpDispatchError(-32601, `Method not found: ${request.method}`, {
+                    method: request.method,
+                });
+        }
+    }
+    _normalizeAcpPermissionOptionId(options, reply) {
+        const optionTargets = reply === "always"
+            ? {
+                optionIds: new Set(["always", "allow_always"]),
+                kinds: new Set(["allow_always"]),
+            }
+            : reply === "once"
+                ? {
+                    optionIds: new Set(["once", "allow_once"]),
+                    kinds: new Set(["allow_once"]),
+                }
+                : {
+                    optionIds: new Set(["reject", "reject_once"]),
+                    kinds: new Set(["reject_once"]),
+                };
+        const matched = options?.find((option) => {
+            const optionId = typeof option.optionId === "string" ? option.optionId : undefined;
+            const kind = typeof option.kind === "string" ? option.kind : undefined;
+            return ((optionId !== undefined && optionTargets.optionIds.has(optionId)) ||
+                (kind !== undefined && optionTargets.kinds.has(kind)));
+        });
+        if (matched && typeof matched.optionId === "string") {
+            return matched.optionId;
+        }
+        if (reply === "always") {
+            return "allow_always";
+        }
+        if (reply === "once") {
+            return "allow_once";
+        }
+        return "reject_once";
+    }
+    _buildAcpPermissionResult(reply, params) {
+        const options = Array.isArray(params.options)
+            ? params.options.filter((option) => typeof option === "object" && option !== null)
+            : undefined;
+        const optionId = this._normalizeAcpPermissionOptionId(options, reply);
+        return {
+            outcome: optionId
+                ? {
+                    outcome: "selected",
+                    optionId,
+                }
+                : {
+                    outcome: "cancelled",
+                },
+        };
+    }
+    async _handleAcpPermissionRequest(request, params) {
+        const sessionId = typeof params.sessionId === "string" ? params.sessionId : undefined;
+        if (!sessionId) {
+            throw new AcpDispatchError(-32602, `${ACP_PERMISSION_METHOD} requires a sessionId`);
+        }
+        const session = this._sessions.get(sessionId);
+        if (!session) {
+            throw new AcpDispatchError(-32602, `Session not found: ${sessionId}`);
+        }
+        const permissionId = String(request.id);
+        const permissionParams = {
+            ...params,
+            permissionId,
+            _acpMethod: request.method,
+        };
+        if (session.permissionHandlers.size === 0) {
+            return this._buildAcpPermissionResult("reject", permissionParams);
+        }
+        const reply = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                session.pendingPermissionReplies.delete(permissionId);
+                reject(new Error(`Timed out waiting for permission reply: ${permissionId}`));
+            }, 120_000);
+            session.pendingPermissionReplies.set(permissionId, {
+                resolve,
+                reject,
+                timer,
+            });
+            const permissionRequest = {
+                permissionId,
+                description: typeof permissionParams["description"] === "string"
+                    ? permissionParams["description"]
+                    : undefined,
+                params: permissionParams,
+            };
+            for (const handler of session.permissionHandlers) {
+                handler(permissionRequest);
+            }
+        });
+        return this._buildAcpPermissionResult(reply, permissionParams);
+    }
+    _acpParams(request) {
+        if (!request.params) {
+            return {};
+        }
+        if (typeof request.params !== "object" ||
+            request.params === null ||
+            Array.isArray(request.params)) {
+            throw new AcpDispatchError(-32602, `${request.method} requires object params`);
+        }
+        return request.params;
+    }
+    _requireAcpStringParam(params, name, method) {
+        const value = params[name];
+        if (typeof value !== "string") {
+            throw new AcpDispatchError(-32602, `${method} requires a string ${name}`);
+        }
+        return value;
+    }
+    _optionalAcpStringParam(params, name, method) {
+        const value = params[name];
+        if (value === undefined || value === null) {
+            return undefined;
+        }
+        if (typeof value !== "string") {
+            throw new AcpDispatchError(-32602, `${method} requires ${name} to be a string when provided`);
+        }
+        return value;
+    }
+    _optionalAcpNumberParam(params, name, method) {
+        const value = params[name];
+        if (value === undefined || value === null) {
+            return undefined;
+        }
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw new AcpDispatchError(-32602, `${method} requires ${name} to be a number when provided`);
+        }
+        return value;
+    }
+    _optionalAcpStringArrayParam(params, name, method) {
+        const value = params[name];
+        if (value === undefined || value === null) {
+            return undefined;
+        }
+        if (!Array.isArray(value) ||
+            value.some((entry) => typeof entry !== "string")) {
+            throw new AcpDispatchError(-32602, `${method} requires ${name} to be an array of strings when provided`);
+        }
+        return [...value];
+    }
+    _optionalAcpEnvParam(params, name, method) {
+        const value = params[name];
+        if (value === undefined || value === null) {
+            return undefined;
+        }
+        if (Array.isArray(value)) {
+            const env = {};
+            for (const entry of value) {
+                if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+                    throw new AcpDispatchError(-32602, `${method} requires ${name} entries to be { name, value } objects`);
+                }
+                const record = entry;
+                if (typeof record.name !== "string" ||
+                    typeof record.value !== "string") {
+                    throw new AcpDispatchError(-32602, `${method} requires ${name} entries to be { name, value } objects`);
+                }
+                env[record.name] = record.value;
+            }
+            return env;
+        }
+        if (typeof value !== "object") {
+            throw new AcpDispatchError(-32602, `${method} requires ${name} to be an object or name/value array`);
+        }
+        const env = {};
+        for (const [key, entryValue] of Object.entries(value)) {
+            if (typeof entryValue !== "string") {
+                throw new AcpDispatchError(-32602, `${method} requires ${name} values to be strings`);
+            }
+            env[key] = entryValue;
+        }
+        return env;
+    }
+    _requireAcpTerminal(params, method) {
+        const terminalId = this._requireAcpStringParam(params, "terminalId", method);
+        const terminal = this._acpTerminals.get(terminalId);
+        if (!terminal) {
+            throw new AcpDispatchError(-32602, `ACP terminal not found: ${terminalId}`);
+        }
+        return terminal;
+    }
+    _appendAcpTerminalOutput(terminal, data) {
+        const chunk = Buffer.from(data).toString("utf8");
+        if (!chunk) {
+            return;
+        }
+        terminal.output += chunk;
+        if (Number.isFinite(terminal.outputByteLimit) &&
+            terminal.outputByteLimit >= 0 &&
+            terminal.output.length > terminal.outputByteLimit) {
+            terminal.output = terminal.output.slice(terminal.output.length - terminal.outputByteLimit);
+            terminal.truncated = true;
+        }
+    }
+    async _handleAcpReadFile(params) {
+        const method = "fs/read";
+        const path = this._requireAcpStringParam(params, "path", method);
+        const line = this._optionalAcpNumberParam(params, "line", method);
+        const limit = this._optionalAcpNumberParam(params, "limit", method);
+        const encoding = this._optionalAcpStringParam(params, "encoding", method);
+        const bytes = await this.readFile(path);
+        if (encoding === "base64") {
+            return { content: Buffer.from(bytes).toString("base64") };
+        }
+        const text = new TextDecoder().decode(bytes);
+        if (line === undefined && limit === undefined) {
+            return { content: text };
+        }
+        const startLine = Math.max(1, Math.trunc(line ?? 1));
+        const lineLimit = limit === undefined
+            ? Number.POSITIVE_INFINITY
+            : Math.max(0, Math.trunc(limit));
+        return {
+            content: text
+                .split("\n")
+                .slice(startLine - 1, startLine - 1 + lineLimit)
+                .join("\n"),
+        };
+    }
+    async _handleAcpWriteFile(params) {
+        const method = "fs/write";
+        const path = this._requireAcpStringParam(params, "path", method);
+        const content = this._requireAcpStringParam(params, "content", method);
+        const encoding = this._optionalAcpStringParam(params, "encoding", method);
+        await this.writeFile(path, encoding === "base64" ? Buffer.from(content, "base64") : content);
+        return null;
+    }
+    async _handleAcpReadDir(params) {
+        const method = "fs/readDir";
+        const path = this._requireAcpStringParam(params, "path", method);
+        const entries = await this._vfs().readDirWithTypes(path);
+        return {
+            entries: entries
+                .filter((entry) => entry.name !== "." && entry.name !== "..")
+                .map((entry) => ({
+                name: entry.name,
+                path: path === "/" ? `/${entry.name}` : `${path}/${entry.name}`,
+                type: entry.isSymbolicLink
+                    ? "symlink"
+                    : entry.isDirectory
+                        ? "directory"
+                        : "file",
+            })),
+        };
+    }
+    _handleAcpCreateTerminal(params) {
+        const method = "terminal/create";
+        const command = this._requireAcpStringParam(params, "command", method);
+        const args = this._optionalAcpStringArrayParam(params, "args", method);
+        const env = this._optionalAcpEnvParam(params, "env", method);
+        const cwd = this._optionalAcpStringParam(params, "cwd", method);
+        const cols = this._optionalAcpNumberParam(params, "cols", method);
+        const rows = this._optionalAcpNumberParam(params, "rows", method);
+        const outputByteLimit = Math.max(0, Math.trunc(this._optionalAcpNumberParam(params, "outputByteLimit", method) ??
+            1_048_576));
+        const terminalId = `acp-terminal-${++this._acpTerminalCounter}`;
+        const terminal = {
+            handle: this.#kernel.openShell({
+                command,
+                ...(args ? { args } : {}),
+                ...(env ? { env } : {}),
+                ...(cwd ? { cwd } : {}),
+                ...(cols !== undefined ? { cols: Math.trunc(cols) } : {}),
+                ...(rows !== undefined ? { rows: Math.trunc(rows) } : {}),
+                onStderr: (data) => {
+                    this._appendAcpTerminalOutput(terminal, data);
+                },
+            }),
+            output: "",
+            truncated: false,
+            outputByteLimit,
+            exitCode: null,
+            waitPromise: Promise.resolve(0),
+        };
+        terminal.handle.onData = (data) => {
+            this._appendAcpTerminalOutput(terminal, data);
+        };
+        terminal.waitPromise = terminal.handle.wait().then((exitCode) => {
+            terminal.exitCode = exitCode;
+            return exitCode;
+        });
+        this._acpTerminals.set(terminalId, terminal);
+        return { terminalId };
+    }
+    _handleAcpWriteTerminal(params) {
+        const method = "terminal/write";
+        const terminal = this._requireAcpTerminal(params, method);
+        const data = this._requireAcpStringParam(params, "data", method);
+        const encoding = this._optionalAcpStringParam(params, "encoding", method);
+        terminal.handle.write(encoding === "base64" ? Buffer.from(data, "base64") : data);
+        return null;
+    }
+    _handleAcpReadTerminal(params) {
+        const terminal = this._requireAcpTerminal(params, "terminal/output");
+        return {
+            output: terminal.output,
+            truncated: terminal.truncated,
+            ...(terminal.exitCode !== null
+                ? {
+                    exitStatus: {
+                        exitCode: terminal.exitCode,
+                        signal: null,
+                    },
+                }
+                : {}),
+        };
+    }
+    async _handleAcpWaitForTerminalExit(params) {
+        const terminal = this._requireAcpTerminal(params, "terminal/wait_for_exit");
+        const exitCode = await terminal.waitPromise;
+        return { exitCode, signal: null };
+    }
+    _handleAcpKillTerminal(params) {
+        const method = "terminal/kill";
+        const terminal = this._requireAcpTerminal(params, method);
+        const signal = this._optionalAcpNumberParam(params, "signal", method) ?? 15;
+        terminal.handle.kill(Math.trunc(signal));
+        return null;
+    }
+    _handleAcpReleaseTerminal(params) {
+        const method = "terminal/release";
+        const terminalId = this._requireAcpStringParam(params, "terminalId", method);
+        const terminal = this._acpTerminals.get(terminalId);
+        if (!terminal) {
+            throw new AcpDispatchError(-32602, `ACP terminal not found: ${terminalId}`);
+        }
+        if (terminal.exitCode === null) {
+            terminal.handle.kill();
+        }
+        this._acpTerminals.delete(terminalId);
+        return null;
+    }
+    _handleAcpResizeTerminal(params) {
+        const method = "terminal/resize";
+        const terminal = this._requireAcpTerminal(params, method);
+        const cols = this._optionalAcpNumberParam(params, "cols", method);
+        const rows = this._optionalAcpNumberParam(params, "rows", method);
+        if (cols === undefined || rows === undefined) {
+            throw new AcpDispatchError(-32602, `${method} requires numeric cols and rows`);
+        }
+        terminal.handle.resize(Math.trunc(cols), Math.trunc(rows));
+        return null;
+    }
+    async _handleAcpPermissionCallback(sessionId, permissionId, params) {
+        const session = this._sessions.get(sessionId);
+        if (!session) {
+            return "reject";
+        }
+        if (session.permissionHandlers.size === 0) {
+            return "reject";
+        }
+        try {
+            return await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    session.pendingPermissionReplies.delete(permissionId);
+                    reject(new Error(`Timed out waiting for permission reply: ${permissionId}`));
+                }, 120_000);
+                session.pendingPermissionReplies.set(permissionId, {
+                    resolve,
+                    reject,
+                    timer,
+                });
+                const permissionRequest = {
+                    permissionId,
+                    description: typeof params.description === "string"
+                        ? params.description
+                        : undefined,
+                    params,
+                };
+                for (const handler of session.permissionHandlers) {
+                    handler(permissionRequest);
+                }
+            });
+        }
+        catch {
+            return "reject";
+        }
+    }
+    /**
+     * Resolve an agent config by ID. Package-provided configs take
+     * precedence over the hardcoded AGENT_CONFIGS.
+     */
+    _resolveAgentConfig(agentType) {
+        return (this._softwareAgentConfigs.get(agentType) ??
+            AGENT_CONFIGS[agentType]);
+    }
+    /**
+     * Gracefully destroy a session: cancel any pending work, close the client,
+     * and remove from tracking. Unlike close() which is abrupt, this attempts
+     * a graceful shutdown sequence.
+     */
+    async destroySession(sessionId) {
+        this._requireSession(sessionId);
+        try {
+            await this.cancelSession(sessionId);
+        }
+        catch {
+            // Ignore cancellation failures during teardown.
+        }
+        await this._closeSessionInternal(sessionId);
+    }
+    // ── Flat session API (ID-based) ───────────────────────────────
+    async prompt(sessionId, text) {
+        const session = this._requireSession(sessionId);
+        let agentText = "";
+        const handler = (event) => {
+            const params = toRecord(event.params);
+            const update = toRecord(params.update);
+            if (update?.sessionUpdate === "agent_message_chunk") {
+                const content = toRecord(update.content);
+                if (typeof content.text === "string") {
+                    agentText += content.text;
+                }
+            }
+        };
+        const unsubscribe = this._subscribeSessionEvents(session, handler);
+        try {
+            const response = await this._sendSessionRequest(sessionId, "session/prompt", {
+                prompt: [{ type: "text", text }],
+            });
+            return { response, text: agentText };
+        }
+        finally {
+            unsubscribe();
+        }
+    }
+    /** Cancel ongoing agent work for a session. */
+    async cancelSession(sessionId) {
+        this._requireSession(sessionId);
+        const cancelledPendingPrompt = this._cancelPendingPromptRequests(sessionId);
+        if (cancelledPendingPrompt) {
+            // Session control requests share the same framed sidecar transport as an
+            // in-flight prompt request. If the adapter is blocked in prompt I/O, a
+            // synchronous cancel RPC can wedge behind that prompt until the transport
+            // timeout fires. Resolve the local prompt immediately, then let the sidecar
+            // cancellation continue in the background as best effort.
+            void this._sendSessionRequest(sessionId, "session/cancel").catch(() => { });
+            return {
+                jsonrpc: "2.0",
+                id: null,
+                result: {
+                    cancelled: true,
+                    requested: true,
+                    via: "prompt-fallback",
+                },
+            };
+        }
+        const response = await this._sendSessionRequest(sessionId, "session/cancel");
+        if (response.error?.code === -32601) {
+            return {
+                jsonrpc: "2.0",
+                id: null,
+                result: {
+                    cancelled: false,
+                    requested: true,
+                    via: "unsupported",
+                },
+            };
+        }
+        return response;
+    }
+    closeSession(sessionId) {
+        if (!this._sessions.has(sessionId) &&
+            !this._closedSessionIds.has(sessionId) &&
+            !this._sessionClosePromises.has(sessionId)) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const closePromise = this._closeSessionInternal(sessionId);
+        // `closeSession()` is intentionally fire-and-forget; suppress unhandled
+        // rejections here and let tracked close promises surface errors to any
+        // internal/test callers awaiting `_sessionClosePromises`.
+        void closePromise.catch(() => { });
+    }
+    async respondPermission(sessionId, permissionId, reply) {
+        const session = this._requireSession(sessionId);
+        const pendingReply = session.pendingPermissionReplies.get(permissionId);
+        if (pendingReply) {
+            session.pendingPermissionReplies.delete(permissionId);
+            clearTimeout(pendingReply.timer);
+            pendingReply.resolve(reply);
+            return {
+                jsonrpc: "2.0",
+                id: null,
+                result: {
+                    permissionId,
+                    reply,
+                    via: "sidecar-request",
+                },
+            };
+        }
+        return this._sendSessionRequest(sessionId, LEGACY_PERMISSION_METHOD, {
+            permissionId,
+            reply,
+        });
+    }
+    async setSessionMode(sessionId, modeId) {
+        return this._sendSessionRequest(sessionId, "session/set_mode", {
+            modeId,
+        });
+    }
+    getSessionModes(sessionId) {
+        return this._requireSession(sessionId).modes;
+    }
+    async setSessionModel(sessionId, model) {
+        return this._setSessionConfigByCategory(sessionId, "model", model);
+    }
+    async setSessionThoughtLevel(sessionId, level) {
+        return this._setSessionConfigByCategory(sessionId, "thought_level", level);
+    }
+    getSessionConfigOptions(sessionId) {
+        return [...this._requireSession(sessionId).configOptions];
+    }
+    getSessionCapabilities(sessionId) {
+        const caps = this._requireSession(sessionId).capabilities;
+        return Object.keys(caps).length > 0 ? caps : null;
+    }
+    getSessionAgentInfo(sessionId) {
+        return this._requireSession(sessionId).agentInfo;
+    }
+    async rawSessionSend(sessionId, method, params) {
+        return this._sendSessionRequest(sessionId, method, params);
+    }
+    async rawSend(sessionId, method, params) {
+        return this.rawSessionSend(sessionId, method, params);
+    }
+    onSessionEvent(sessionId, handler) {
+        const session = this._requireSession(sessionId);
+        return this._subscribeSessionEvents(session, handler);
+    }
+    onPermissionRequest(sessionId, handler) {
+        const session = this._requireSession(sessionId);
+        session.permissionHandlers.add(handler);
+        return () => {
+            session.permissionHandlers.delete(handler);
+        };
+    }
+    // ── Cron ────────────────────────────────────────────────────
+    /** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
+    scheduleCron(options) {
+        return this._cronManager.schedule(options);
+    }
+    /** List all registered cron jobs. */
+    listCronJobs() {
+        return this._cronManager.list();
+    }
+    /** Cancel a cron job by ID. */
+    cancelCronJob(id) {
+        this._cronManager.cancel(id);
+    }
+    /** Subscribe to cron lifecycle events (fire, complete, error). */
+    onCronEvent(handler) {
+        this._cronManager.onEvent(handler);
+    }
+    async dispose() {
+        this._cronManager.dispose();
+        for (const sessionId of [...this._sessions.keys()]) {
+            await this._closeSessionInternal(sessionId).catch(() => { });
+        }
+        for (const [id, entry] of this._shells) {
+            entry.handle.kill();
+        }
+        const shellExitPromises = [...this._pendingShellExitPromises];
+        this._shells.clear();
+        const terminalExitPromises = [];
+        for (const terminal of this._acpTerminals.values()) {
+            terminal.handle.kill();
+            terminalExitPromises.push(terminal.waitPromise.then(() => undefined, () => undefined));
+        }
+        this._acpTerminals.clear();
+        await waitForTrackedExitPromises([...shellExitPromises, ...terminalExitPromises], SHELL_DISPOSE_TIMEOUT_MS);
+        this._disposeSidecarEventListener();
+        const sidecarLease = this._sidecarLease;
+        this._sidecarLease = null;
+        if (sidecarLease) {
+            return sidecarLease.dispose();
+        }
+        return this.#kernel.dispose();
+    }
+}
+const agentOsRuntimeAdmins = new WeakMap();
+export function getAgentOsRuntimeAdmin(vm) {
+    const admin = agentOsRuntimeAdmins.get(vm);
+    if (!admin) {
+        throw new Error("Agent OS runtime admin is not available for this VM");
+    }
+    return admin;
+}
+export function getAgentOsKernel(vm) {
+    return getAgentOsRuntimeAdmin(vm).kernel;
+}
+function resolveAgentOsSidecar(config) {
+    if (!config || config.kind === "shared") {
+        return getSharedAgentOsSidecarInternal(config?.kind === "shared" ? { pool: config.pool } : undefined);
+    }
+    return config.handle;
+}
+const sidecarStates = new WeakMap();
+const sharedSidecars = new Map();
+export class AgentOsSidecar {
+    constructor(sidecarId, placement, sharedPool) {
+        sidecarStates.set(this, {
+            description: {
+                sidecarId,
+                placement: cloneSidecarPlacement(placement),
+                state: "ready",
+                activeVmCount: 0,
+            },
+            activeLeases: new Set(),
+            sharedPool,
+        });
+    }
+    describe() {
+        const state = getSidecarState(this);
+        return cloneSidecarDescription(state.description);
+    }
+    async dispose() {
+        const state = getSidecarState(this);
+        if (state.description.state === "disposed") {
+            return;
+        }
+        state.description.state = "disposing";
+        const errors = [];
+        for (const lease of [...state.activeLeases]) {
+            try {
+                await lease.dispose();
+            }
+            catch (error) {
+                errors.push(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        state.activeLeases.clear();
+        state.description.activeVmCount = 0;
+        state.description.state = "disposed";
+        if (state.sharedPool && sharedSidecars.get(state.sharedPool) === this) {
+            sharedSidecars.delete(state.sharedPool);
+        }
+        if (errors.length > 0) {
+            throw new Error(errors.map((error) => error.message).join("; "));
+        }
+    }
+}
+function createAgentOsSidecarInternal(options = {}) {
+    const sidecarId = options.sidecarId ?? `agentos-sidecar-${randomUUID()}`;
+    return new AgentOsSidecar(sidecarId, {
+        kind: "explicit",
+        sidecarId,
+    });
+}
+/**
+ * Test-only escape hatch: dispose every cached shared sidecar so vitest
+ * workers can exit cleanly. The shared sidecar is normally process-global and
+ * keeps its native subprocess alive across `AgentOs.create()` calls; without
+ * this hook the vitest worker can hold open piped stdio handles after the
+ * test suite finishes and stall `pnpm test` indefinitely.
+ */
+export async function __disposeAllSharedSidecarsForTesting() {
+    const sidecars = Array.from(sharedSidecars.values());
+    sharedSidecars.clear();
+    const errors = [];
+    for (const sidecar of sidecars) {
+        try {
+            await sidecar.dispose();
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`failed to dispose shared sidecars: ${errors.map((error) => error.message).join("; ")}`);
+    }
+}
+function getSharedAgentOsSidecarInternal(options = {}) {
+    const pool = options.pool ?? "default";
+    const existing = sharedSidecars.get(pool);
+    if (existing && existing.describe().state !== "disposed") {
+        return existing;
+    }
+    const sidecar = new AgentOsSidecar(`agent-os-shared-sidecar:${pool}`, { kind: "shared", ...(pool ? { pool } : {}) }, pool);
+    sharedSidecars.set(pool, sidecar);
+    return sidecar;
+}
+async function leaseAgentOsSidecarVm(sidecar, options) {
+    const state = getSidecarState(sidecar);
+    if (state.description.state !== "ready") {
+        throw new Error(`Cannot lease VM from sidecar ${state.description.sidecarId} while it is ${state.description.state}`);
+    }
+    let transport;
+    const client = createAgentOsSidecarClient({
+        async createSessionTransport(sessionBootstrap) {
+            transport = await createInProcessSidecarTransport(sessionBootstrap, options);
+            return transport;
+        },
+    });
+    let disposed = false;
+    let leaseRecord;
+    try {
+        const session = await client.createSession({
+            placement: cloneSidecarPlacement(state.description.placement),
+        });
+        const vm = await session.createVm();
+        const admin = transport?.getVmAdmin(vm.vmId);
+        if (!admin) {
+            throw new Error(`Sidecar VM admin was not registered for ${vm.vmId}`);
+        }
+        const lease = {
+            sidecar,
+            session,
+            vm,
+            admin,
+            async dispose() {
+                if (disposed) {
+                    return;
+                }
+                disposed = true;
+                state.activeLeases.delete(leaseRecord);
+                state.description.activeVmCount = state.activeLeases.size;
+                await client.dispose();
+            },
+        };
+        leaseRecord = {
+            dispose: () => lease.dispose(),
+        };
+        state.activeLeases.add(leaseRecord);
+        state.description.activeVmCount = state.activeLeases.size;
+        return lease;
+    }
+    catch (error) {
+        await client.dispose().catch(() => { });
+        throw error;
+    }
+}
+async function createInProcessSidecarTransport(sessionBootstrap, options) {
+    const vmAdmins = new Map();
+    let disposed = false;
+    async function disposeVmAdmin(vmId) {
+        const admin = vmAdmins.get(vmId);
+        if (!admin) {
+            return;
+        }
+        vmAdmins.delete(vmId);
+        await admin.dispose();
+    }
+    return {
+        async createVm(vmBootstrap) {
+            if (disposed) {
+                throw new Error(`Cannot create VM ${vmBootstrap.vmId} for disposed sidecar session ${sessionBootstrap.sessionId}`);
+            }
+            const admin = await options.createVm(sessionBootstrap, vmBootstrap);
+            vmAdmins.set(vmBootstrap.vmId, admin);
+        },
+        async disposeVm(vmId) {
+            await disposeVmAdmin(vmId);
+        },
+        async dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            const errors = [];
+            for (const vmId of [...vmAdmins.keys()]) {
+                try {
+                    await disposeVmAdmin(vmId);
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            if (errors.length > 0) {
+                throw new Error(errors.map((error) => error.message).join("; "));
+            }
+        },
+        getVmAdmin(vmId) {
+            return vmAdmins.get(vmId);
+        },
+    };
+}
+function getSidecarState(sidecar) {
+    const state = sidecarStates.get(sidecar);
+    if (!state) {
+        throw new Error("Unknown Agent OS sidecar handle");
+    }
+    return state;
+}
+function cloneSidecarDescription(description) {
+    return {
+        ...description,
+        placement: cloneSidecarPlacement(description.placement),
+    };
+}
+function cloneSidecarPlacement(placement) {
+    if (placement.kind === "shared") {
+        return {
+            kind: "shared",
+            ...(placement.pool ? { pool: placement.pool } : {}),
+        };
+    }
+    return {
+        kind: "explicit",
+        sidecarId: placement.sidecarId,
+    };
+}