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

package/dist/agent-os.js

@@ -3,22 +3,139 @@ import { randomUUID } from "node:crypto";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { 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 { validateBindings } from "./bindings.js";
+import { zodToJsonSchema } from "./bindings-zod.js";
 import { parseAgentOsOptions } from "./options-schema.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;
-function defaultAcpClientCapabilities() {
+function safeWireU64(value) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0) {
+        throw new RangeError(`wire integer ${value} exceeds JavaScript's safe range`);
+    }
+    return result;
+}
+function decodeDurableSessionInfo(value) {
     return {
-        fs: {
-            readTextFile: true,
-            writeTextFile: true,
-        },
-        terminal: true,
+        sessionId: value.sessionId,
+        agent: value.agent,
+        cwd: value.cwd,
+        additionalDirectories: JSON.parse(value.additionalDirectories),
+        state: JSON.parse(value.state),
+        latestSequence: safeWireU64(value.latestSequence),
+        title: value.title ?? undefined,
+        metadata: value.metadata === null ? undefined : JSON.parse(value.metadata),
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+    };
+}
+const PERMISSION_TERMINAL_REASONS = new Set([
+    "already_resolved",
+    "prompt_cancelled",
+    "adapter_exited",
+    "session_deleted",
+    "vm_shutdown",
+    "request_not_found",
+]);
+function permissionTerminalReason(value) {
+    if (value !== null &&
+        PERMISSION_TERMINAL_REASONS.has(value)) {
+        return value;
+    }
+    throw new Error(`invalid permission terminal reason: ${value ?? "missing"}`);
+}
+function decodeDurableSessionEvent(value) {
+    const envelope = {
+        durability: "durable",
+        sessionId: value.sessionId,
+        sequence: safeWireU64(value.sequence),
+        timestamp: value.timestamp,
+    };
+    switch (value.event.tag) {
+        case "AcpDurableSessionUpdate": {
+            const update = JSON.parse(value.event.val.update);
+            const { sessionUpdate: type, ...payload } = update;
+            return {
+                ...envelope,
+                type,
+                ...payload,
+            };
+        }
+        case "AcpDurablePermissionRequest": {
+            const request = JSON.parse(value.event.val.request);
+            const { sessionId: _sessionId, ...payload } = request;
+            return {
+                ...envelope,
+                type: "permission_request",
+                requestId: value.event.val.requestId,
+                ...payload,
+            };
+        }
+        case "AcpDurablePermissionResponse": {
+            const status = value.event.val.status;
+            if (status !== "accepted" && status !== "not_pending") {
+                throw new Error(`invalid permission response event status: ${status}`);
+            }
+            const response = JSON.parse(value.event.val.response);
+            return {
+                ...envelope,
+                type: "permission_response",
+                requestId: value.event.val.requestId,
+                ...response,
+                status,
+                ...(value.event.val.reason === null
+                    ? {}
+                    : { reason: permissionTerminalReason(value.event.val.reason) }),
+            };
+        }
+    }
+}
+function normalizeSessionCapabilities(value) {
+    const capabilities = toRecord(value);
+    const prompt = toRecord(capabilities.promptCapabilities);
+    const mcp = toRecord(capabilities.mcpCapabilities);
+    const session = toRecord(capabilities.sessionCapabilities);
+    const extensions = Object.fromEntries(Object.entries(capabilities).filter(([key]) => ![
+        "loadSession",
+        "promptCapabilities",
+        "mcpCapabilities",
+        "sessionCapabilities",
+    ].includes(key)));
+    return {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        loadSession: capabilities.loadSession === true,
+        ...(Object.keys(prompt).length > 0
+            ? {
+                prompt: {
+                    audio: prompt.audio === true || undefined,
+                    embeddedContext: prompt.embeddedContext === true || undefined,
+                    image: prompt.image === true || undefined,
+                },
+            }
+            : {}),
+        ...(Object.keys(mcp).length > 0
+            ? {
+                mcp: {
+                    http: mcp.http === true || undefined,
+                    sse: mcp.sse === true || undefined,
+                },
+            }
+            : {}),
+        ...(Object.keys(session).length > 0
+            ? {
+                session: {
+                    list: typeof session.list === "object" || undefined,
+                    resume: typeof session.resume === "object" || undefined,
+                    close: typeof session.close === "object" || undefined,
+                    delete: typeof session.delete === "object" || undefined,
+                    additionalDirectories: typeof session.additionalDirectories === "object" || undefined,
+                },
+            }
+            : {}),
+        ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
     };
 }
 async function waitForTrackedExitPromises(promises, timeoutMs) {
@@ -32,26 +149,24 @@ async function waitForTrackedExitPromises(promises, timeoutMs) {
         }),
     ]);
 }
+import { OPT_AGENTOS_ROOT, } from "./agentos-package.js";
 import { getBaseEnvironment } from "./base-filesystem.js";
 import { CronManager } from "./cron/cron-manager.js";
 import { TimerScheduleDriver } from "./cron/timer-driver.js";
+import { resolveDefaultSoftware } from "./default-software.js";
 import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
 import { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
-import { OPT_AGENTOS_ROOT, } from "./agentos-package.js";
-import { resolveDefaultSoftware } from "./default-software.js";
 import { allowAll } from "./runtime-compat.js";
-import { AcpRuntimeKind, decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
+import { decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
 import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
 import { createAgentOsSidecarClient, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
 function defaultAgentStderrHandler(event) {
     process.stderr.write(event.chunk);
 }
 function defaultAgentExitHandler(event) {
-    process.stderr.write(`[agentos] agent adapter exited unexpectedly: session=${event.sessionId} agent=${event.agentType} exitCode=${event.exitCode ?? "unknown"} restart=${event.restart} (${event.restartCount}/${event.maxRestarts})\n`);
+    process.stderr.write(`[agentos] agent adapter exited unexpectedly: session=${event.sessionId} agent=${event.agentType} exitCode=${event.exitCode ?? "unknown"}; restore explicitly before retrying\n`);
 }
-const LEGACY_PERMISSION_METHOD = "request/permission";
-const ACP_PERMISSION_METHOD = "session/request_permission";
 class AcpDispatchError extends Error {
     code;
     data;
@@ -124,51 +239,6 @@ function normalizePackageRef(value) {
     }
     return undefined;
 }
-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;
@@ -205,51 +275,6 @@ class BoundedSet {
         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(),
-        warnedNoPermissionHandler: false,
-        configOverrides: new Map(),
-        pendingPermissionReplies: new Map(),
-    };
-}
 function isOverlayMountConfig(config) {
     return "filesystem" in config;
 }
@@ -445,14 +470,28 @@ const SIDECAR_BUILD_INPUTS = [
     join(REPO_ROOT, "Cargo.toml"),
     join(REPO_ROOT, "Cargo.lock"),
     join(REPO_ROOT, "crates/bridge"),
+    join(REPO_ROOT, "crates/build-support"),
     join(REPO_ROOT, "crates/execution"),
     join(REPO_ROOT, "crates/kernel"),
-    join(REPO_ROOT, "crates/sidecar"),
+    join(REPO_ROOT, "crates/agentos-protocol"),
+    join(REPO_ROOT, "crates/agentos-sidecar"),
+    join(REPO_ROOT, "crates/native-sidecar"),
+    join(REPO_ROOT, "crates/native-sidecar-core"),
+    join(REPO_ROOT, "crates/sidecar-protocol"),
+    join(REPO_ROOT, "crates/v8-runtime"),
+    join(REPO_ROOT, "crates/vfs"),
+    join(REPO_ROOT, "crates/vm-config"),
+    join(REPO_ROOT, "packages/build-tools/bridge-src"),
+    join(REPO_ROOT, "packages/build-tools/package.json"),
+    join(REPO_ROOT, "packages/build-tools/scripts/build-v8-bridge.mjs"),
+    join(REPO_ROOT, "packages/core/fixtures/base-filesystem.json"),
+    join(REPO_ROOT, "packages/runtime-core/fixtures/base-filesystem.json"),
+    join(REPO_ROOT, "pnpm-lock.yaml"),
 ];
 let ensuredSidecarBinary = null;
 function collectConfiguredLowerPaths(config) {
     const paths = new Set();
-    for (const lower of config?.lowers ?? []) {
+    for (const lower of config?.type === "native" ? [] : (config?.lowers ?? [])) {
         if (lower.kind !== "snapshot-export") {
             continue;
         }
@@ -463,7 +502,7 @@ function collectConfiguredLowerPaths(config) {
     return paths;
 }
 function findBootstrapSeedEntry(config, path) {
-    for (const lower of config?.lowers ?? []) {
+    for (const lower of config?.type === "native" ? [] : (config?.lowers ?? [])) {
         if (lower.kind !== "snapshot-export") {
             continue;
         }
@@ -479,6 +518,9 @@ function findBootstrapSeedEntry(config, path) {
     return meta ? { path, type: "directory", ...meta } : undefined;
 }
 function createKernelBootstrapLower(config, extraEntries = []) {
+    if (config?.type === "native") {
+        return null;
+    }
     const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
     const existingPaths = collectConfiguredLowerPaths(config);
     const entries = [
@@ -547,7 +589,7 @@ function buildLiveBootstrapDirectoryEntries(existingPaths, config) {
     return entries;
 }
 async function bootstrapLiveBootstrapDirectories(client, session, vm, config) {
-    const existingPaths = new Set((await client.snapshotRootFilesystem(session, vm)).map((entry) => entry.path));
+    const existingPaths = new Set((await client.snapshotRootFilesystem(session, vm, Number.MAX_SAFE_INTEGER)).map((entry) => entry.path));
     const entries = buildLiveBootstrapDirectoryEntries(existingPaths, config);
     if (entries.length === 0) {
         return;
@@ -720,11 +762,14 @@ function collectSidecarMountPlan(options) {
     hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
     return { sidecarMounts, hostMounts, hostPathMappings };
 }
-function collectToolkitBootstrapCommands(toolKits) {
-    if (toolKits.length === 0) {
+function collectBindingBootstrapCommands(bindings) {
+    if (bindings.length === 0) {
         return [];
     }
-    return ["agentos", ...toolKits.map((toolKit) => `agentos-${toolKit.name}`)];
+    return [
+        "agentos",
+        ...bindings.map((bindingCollection) => `agentos-${bindingCollection.name}`),
+    ];
 }
 function validationMessage(error) {
     if (typeof error === "object" &&
@@ -742,14 +787,16 @@ function validationMessage(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
-function toolToSidecarDefinition(tool) {
+function bindingToSidecarDefinition(definition) {
     return {
-        description: tool.description,
-        inputSchema: zodToJsonSchema(tool.inputSchema),
-        ...(tool.timeout !== undefined ? { timeoutMs: tool.timeout } : {}),
-        ...(tool.examples && tool.examples.length > 0
+        description: definition.description,
+        inputSchema: zodToJsonSchema(definition.inputSchema),
+        ...(definition.timeout !== undefined
+            ? { timeoutMs: definition.timeout }
+            : {}),
+        ...(definition.examples && definition.examples.length > 0
             ? {
-                examples: tool.examples.map((example) => ({
+                examples: definition.examples.map((example) => ({
                     description: example.description,
                     input: example.input,
                 })),
@@ -757,8 +804,8 @@ function toolToSidecarDefinition(tool) {
             : {}),
     };
 }
-function combineInstructions(additionalInstructions, toolReference) {
-    const parts = [additionalInstructions, toolReference]
+function combineInstructions(additionalInstructions, bindingReference) {
+    const parts = [additionalInstructions, bindingReference]
         .map((part) => part?.trim())
         .filter((part) => Boolean(part));
     if (parts.length === 0) {
@@ -766,48 +813,48 @@ function combineInstructions(additionalInstructions, toolReference) {
     }
     return parts.join("\n\n");
 }
-function buildHostToolReference(toolKits) {
-    if (toolKits.length === 0) {
+function buildBindingReference(bindings) {
+    if (bindings.length === 0) {
         return "";
     }
     const lines = [
-        "## Available Host Tools",
+        "## Available Host Bindings",
         "",
-        "Run `agentos list-tools` to see all available tools.",
+        "Run `agentos list-bindings` to see all available bindings.",
         "",
     ];
-    for (const toolKit of toolKits) {
-        lines.push(`### ${toolKit.name}`);
+    for (const bindingCollection of bindings) {
+        lines.push(`### ${bindingCollection.name}`);
         lines.push("");
-        lines.push(toolKit.description);
+        lines.push(bindingCollection.description);
         lines.push("");
-        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
-            const sidecarTool = toolToSidecarDefinition(tool);
-            const signature = buildToolFlagSignature(sidecarTool.inputSchema);
+        for (const [bindingName, definition] of Object.entries(bindingCollection.bindings)) {
+            const sidecarBinding = bindingToSidecarDefinition(definition);
+            const signature = buildBindingFlagSignature(sidecarBinding.inputSchema);
             const suffix = signature.length > 0 ? ` ${signature}` : "";
-            lines.push(`- \`agentos-${toolKit.name} ${toolName}${suffix}\` — ${tool.description}`);
+            lines.push(`- \`agentos-${bindingCollection.name} ${bindingName}${suffix}\` — ${definition.description}`);
         }
         lines.push("");
-        const toolsWithExamples = Object.entries(toolKit.tools).filter(([, tool]) => tool.examples && tool.examples.length > 0);
-        if (toolsWithExamples.length > 0) {
+        const bindingsWithExamples = Object.entries(bindingCollection.bindings).filter(([, definition]) => definition.examples && definition.examples.length > 0);
+        if (bindingsWithExamples.length > 0) {
             lines.push("**Examples:**");
             lines.push("");
-            for (const [toolName, tool] of toolsWithExamples) {
-                for (const example of tool.examples ?? []) {
-                    const args = inputToToolFlags(example.input);
+            for (const [bindingName, definition] of bindingsWithExamples) {
+                for (const example of definition.examples ?? []) {
+                    const args = inputToBindingFlags(example.input);
                     const suffix = args.length > 0 ? ` ${args}` : "";
-                    lines.push(`- ${example.description}: \`agentos-${toolKit.name} ${toolName}${suffix}\``);
+                    lines.push(`- ${example.description}: \`agentos-${bindingCollection.name} ${bindingName}${suffix}\``);
                 }
             }
             lines.push("");
         }
-        lines.push(`Run \`agentos-${toolKit.name} <tool> --help\` for details.`);
+        lines.push(`Run \`agentos-${bindingCollection.name} <binding> --help\` for details.`);
         lines.push("");
     }
     return lines.join("\n");
 }
-function buildToolFlagSignature(schema) {
-    return describeToolFlags(schema)
+function buildBindingFlagSignature(schema) {
+    return describeBindingFlags(schema)
         .map((flag) => {
         if (flag.required) {
             return `${flag.name} <${flag.type}>`;
@@ -816,7 +863,7 @@ function buildToolFlagSignature(schema) {
     })
         .join(" ");
 }
-function describeToolFlags(schema) {
+function describeBindingFlags(schema) {
     const schemaObject = asRecord(schema);
     const properties = asRecord(schemaObject.properties);
     const required = Array.isArray(schemaObject.required)
@@ -824,11 +871,11 @@ function describeToolFlags(schema) {
         : new Set();
     return Object.entries(properties).map(([fieldName, fieldSchema]) => ({
         name: `--${camelToKebab(fieldName)}`,
-        type: describeToolFlagType(fieldSchema),
+        type: describeBindingFlagType(fieldSchema),
         required: required.has(fieldName),
     }));
 }
-function describeToolFlagType(schema) {
+function describeBindingFlagType(schema) {
     const schemaObject = asRecord(schema);
     const type = typeof schemaObject.type === "string" ? schemaObject.type : undefined;
     if (type === "array") {
@@ -847,7 +894,7 @@ function describeJsonSchemaScalarType(schema) {
     const schemaObject = asRecord(schema);
     return typeof schemaObject.type === "string" ? schemaObject.type : "string";
 }
-function inputToToolFlags(input) {
+function inputToBindingFlags(input) {
     const inputObject = asRecord(input);
     return Object.entries(inputObject)
         .flatMap(([key, value]) => {
@@ -859,13 +906,13 @@ function inputToToolFlags(input) {
             return [`--no-${camelToKebab(key)}`];
         }
         if (Array.isArray(value)) {
-            return value.map((item) => `${flag} ${toolCliString(item)}`);
+            return value.map((item) => `${flag} ${bindingCliString(item)}`);
         }
-        return [`${flag} ${toolCliString(value)}`];
+        return [`${flag} ${bindingCliString(value)}`];
     })
         .join(" ");
 }
-function toolCliString(value) {
+function bindingCliString(value) {
     return typeof value === "string" ? value : (JSON.stringify(value) ?? "null");
 }
 function camelToKebab(value) {
@@ -903,15 +950,15 @@ async function handleHostCallback(request, context) {
             };
         }
     }
-    const tool = context.toolMap.get(payload.callback_key);
-    if (!tool) {
+    const definition = context.bindingMap.get(payload.callback_key);
+    if (!definition) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            error: `Unknown tool "${payload.callback_key}"`,
+            error: `Unknown binding "${payload.callback_key}"`,
         };
     }
-    const permissionMode = toolPermissionMode(context.permissions, payload.callback_key);
+    const permissionMode = bindingPermissionMode(context.permissions, payload.callback_key);
     if (permissionMode !== "allow") {
         return {
             type: "host_callback_result",
@@ -919,7 +966,7 @@ async function handleHostCallback(request, context) {
             error: `EACCES: blocked by binding.invoke policy for ${payload.callback_key}`,
         };
     }
-    const parsed = tool.inputSchema.safeParse(payload.input);
+    const parsed = definition.inputSchema.safeParse(payload.input);
     if (!parsed.success) {
         return {
             type: "host_callback_result",
@@ -931,7 +978,7 @@ async function handleHostCallback(request, context) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            result: await executeHostTool(tool, payload.callback_key, parsed.data),
+            result: await executeBinding(definition, payload.callback_key, parsed.data),
         };
     }
     catch (error) {
@@ -942,14 +989,14 @@ async function handleHostCallback(request, context) {
         };
     }
 }
-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);
+function buildBindingMap(bindings) {
+    const bindingMap = new Map();
+    for (const bindingCollection of bindings) {
+        for (const [bindingName, definition] of Object.entries(bindingCollection.bindings)) {
+            bindingMap.set(`${bindingCollection.name}:${bindingName}`, definition);
         }
     }
-    return toolMap;
+    return bindingMap;
 }
 function bridgeErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -1048,7 +1095,7 @@ async function handleJsBridgeCall(request, context) {
                 await fs.chmod(path(), requireBridgeNumber(args.mode, "mode"));
                 break;
             case "chown":
-                await fs.chown(path(), requireBridgeNumber(args.uid, "uid"), requireBridgeNumber(args.gid, "gid"));
+                await fs.chown(path(), requireBridgeNumber(args.uid, "uid"), requireBridgeNumber(args.gid, "gid"), { followSymlinks: args.followSymlinks !== false });
                 break;
             case "utimes":
                 await fs.utimes(path(), requireBridgeNumber(args.atimeMs, "atimeMs"), requireBridgeNumber(args.mtimeMs, "mtimeMs"));
@@ -1096,90 +1143,90 @@ function parseHostCommandCallbackInput(input) {
     };
 }
 async function handleHostCommandCallback(command, context) {
-    const directToolKit = context.toolKits.find((toolKit) => `agentos-${toolKit.name}` === command.command);
+    const directBindings = context.bindings.find((bindingCollection) => `agentos-${bindingCollection.name}` === command.command);
     if (command.command === "agentos") {
         return handleAgentOsRegistryCommand(command, context);
     }
-    if (directToolKit) {
-        return handleAgentOsToolkitCommand(command, context, directToolKit);
+    if (directBindings) {
+        return handleAgentOsBindingCommand(command, context, directBindings);
     }
     throw new Error(`Unknown host callback command "${command.command}"`);
 }
 async function handleAgentOsRegistryCommand(command, context) {
-    const [subcommand, toolkitName, toolName, ...toolArgs] = command.args;
+    const [subcommand, collectionName, bindingName, ...bindingArgs] = command.args;
     if (!subcommand || isHelpFlag(subcommand)) {
         return {
-            usage: "agentos <command>: list-tools [toolkit], <toolkit> --help, or <toolkit> <tool> ...",
+            usage: "agentos <command>: list-bindings [collection], <collection> --help, or <collection> <binding> ...",
         };
     }
-    if (subcommand === "list-tools") {
-        return toolkitName
-            ? describeToolkitPayload(context.toolKits, toolkitName)
-            : listToolkitsPayload(context.toolKits);
+    if (subcommand === "list-bindings") {
+        return collectionName
+            ? describeBindingsPayload(context.bindings, collectionName)
+            : listBindingsPayload(context.bindings);
     }
-    const toolKit = context.toolKits.find((kit) => kit.name === subcommand);
-    if (!toolKit) {
-        throw new Error(`No toolkit "${subcommand}". Available: ${toolkitNames(context.toolKits)}`);
+    const bindingCollection = context.bindings.find((collection) => collection.name === subcommand);
+    if (!bindingCollection) {
+        throw new Error(`No binding collection "${subcommand}". Available: ${bindingsNames(context.bindings)}`);
     }
-    if (!toolkitName || isHelpFlag(toolkitName)) {
-        return describeToolkitPayload(context.toolKits, subcommand);
+    if (!collectionName || isHelpFlag(collectionName)) {
+        return describeBindingsPayload(context.bindings, subcommand);
     }
-    if (toolName && isHelpFlag(toolName)) {
-        return describeToolPayload(toolKit, toolkitName);
+    if (bindingName && isHelpFlag(bindingName)) {
+        return describeBindingPayload(bindingCollection, collectionName);
     }
-    return invokeHostTool({
-        toolKit,
-        toolName: toolkitName,
-        args: [toolName, ...toolArgs].filter((value) => typeof value === "string"),
+    return invokeBinding({
+        bindingCollection,
+        bindingName: collectionName,
+        args: [bindingName, ...bindingArgs].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);
+async function handleAgentOsBindingCommand(command, context, bindingCollection) {
+    const [bindingName, helpOrFirstArg, ...rest] = command.args;
+    if (!bindingName || isHelpFlag(bindingName)) {
+        return describeBindingsPayload(context.bindings, bindingCollection.name);
     }
     if (helpOrFirstArg && isHelpFlag(helpOrFirstArg)) {
-        return describeToolPayload(toolKit, toolName);
+        return describeBindingPayload(bindingCollection, bindingName);
     }
-    return invokeHostTool({
-        toolKit,
-        toolName,
+    return invokeBinding({
+        bindingCollection,
+        bindingName,
         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)}`);
+async function invokeBinding({ bindingCollection, bindingName, args, cwd, context, }) {
+    const definition = bindingCollection.bindings[bindingName];
+    if (!definition) {
+        throw new Error(`No binding "${bindingName}" in collection "${bindingCollection.name}". Available: ${bindingNames(bindingCollection)}`);
     }
-    const callbackKey = `${toolKit.name}:${toolName}`;
-    const permissionMode = toolPermissionMode(context.permissions, callbackKey);
+    const callbackKey = `${bindingCollection.name}:${bindingName}`;
+    const permissionMode = bindingPermissionMode(context.permissions, callbackKey);
     if (permissionMode !== "allow") {
         throw new Error(`EACCES: blocked by binding.invoke policy for ${callbackKey}`);
     }
-    const input = await parseHostToolInput(tool, args, cwd, context.readFile);
-    return executeHostTool(tool, callbackKey, input);
+    const input = await parseBindingInput(definition, args, cwd, context.readFile);
+    return executeBinding(definition, callbackKey, input);
 }
-async function executeHostTool(tool, callbackKey, input) {
-    const parsed = tool.inputSchema.safeParse(input);
+async function executeBinding(definition, callbackKey, input) {
+    const parsed = definition.inputSchema.safeParse(input);
     if (!parsed.success) {
         throw new Error(validationMessage(parsed.error));
     }
     return Promise.race([
-        Promise.resolve(tool.execute(parsed.data)),
+        Promise.resolve(definition.execute(parsed.data)),
         new Promise((_, reject) => {
-            if (tool.timeout === undefined) {
+            if (definition.timeout === undefined) {
                 return;
             }
-            setTimeout(() => reject(new Error(`Tool "${callbackKey}" timed out after ${tool.timeout}ms`)), tool.timeout);
+            setTimeout(() => reject(new Error(`Binding "${callbackKey}" timed out after ${definition.timeout}ms`)), definition.timeout);
         }),
     ]);
 }
-async function parseHostToolInput(tool, args, cwd, readFile) {
+async function parseBindingInput(definition, args, cwd, readFile) {
     if (args[0] === "--json") {
         const value = args[1];
         if (value === undefined) {
@@ -1198,9 +1245,9 @@ async function parseHostToolInput(tool, args, cwd, readFile) {
         const text = new TextDecoder().decode(await readFile(guestPath));
         return JSON.parse(text);
     }
-    return parseToolArgv(toolToSidecarDefinition(tool).inputSchema, args);
+    return parseBindingArgv(bindingToSidecarDefinition(definition).inputSchema, args);
 }
-function parseToolArgv(schema, argv) {
+function parseBindingArgv(schema, argv) {
     const schemaObject = asRecord(schema);
     const properties = asRecord(schemaObject.properties);
     const required = Array.isArray(schemaObject.required)
@@ -1272,49 +1319,49 @@ function parseToolArgv(schema, argv) {
     }
     return input;
 }
-function listToolkitsPayload(toolKits) {
+function listBindingsPayload(bindings) {
     return {
-        toolkits: toolKits.map((toolKit) => ({
-            name: toolKit.name,
-            description: toolKit.description,
-            tools: Object.keys(toolKit.tools),
+        bindings: bindings.map((bindingCollection) => ({
+            name: bindingCollection.name,
+            description: bindingCollection.description,
+            bindings: Object.keys(bindingCollection.bindings),
         })),
     };
 }
-function describeToolkitPayload(toolKits, toolkitName) {
-    const toolKit = toolKits.find((kit) => kit.name === toolkitName);
-    if (!toolKit) {
-        throw new Error(`No toolkit "${toolkitName}". Available: ${toolkitNames(toolKits)}`);
+function describeBindingsPayload(bindings, collectionName) {
+    const bindingCollection = bindings.find((collection) => collection.name === collectionName);
+    if (!bindingCollection) {
+        throw new Error(`No binding collection "${collectionName}". Available: ${bindingsNames(bindings)}`);
     }
     return {
-        name: toolKit.name,
-        description: toolKit.description,
-        tools: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
-            toolName,
+        name: bindingCollection.name,
+        description: bindingCollection.description,
+        bindings: Object.fromEntries(Object.entries(bindingCollection.bindings).map(([bindingName, definition]) => [
+            bindingName,
             {
-                description: tool.description,
-                flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
+                description: definition.description,
+                flags: describeBindingFlags(bindingToSidecarDefinition(definition).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)}`);
+function describeBindingPayload(bindingCollection, bindingName) {
+    const definition = bindingCollection.bindings[bindingName];
+    if (!definition) {
+        throw new Error(`No binding "${bindingName}" in collection "${bindingCollection.name}". Available: ${bindingNames(bindingCollection)}`);
     }
     return {
-        toolkit: toolKit.name,
-        tool: toolName,
-        description: tool.description,
-        flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
-        examples: tool.examples?.map((example) => ({
+        collection: bindingCollection.name,
+        binding: bindingName,
+        description: definition.description,
+        flags: describeBindingFlags(bindingToSidecarDefinition(definition).inputSchema),
+        examples: definition.examples?.map((example) => ({
             description: example.description,
             input: example.input,
         })) ?? [],
     };
 }
-function toolPermissionMode(permissions, callbackKey) {
+function bindingPermissionMode(permissions, callbackKey) {
     const scope = permissions.binding;
     if (!scope) {
         return "deny";
@@ -1349,11 +1396,11 @@ function permissionPatternMatches(pattern, value) {
         .join("");
     return new RegExp(`^${source}$`).test(value);
 }
-function toolkitNames(toolKits) {
-    return toolKits.map((toolKit) => toolKit.name).join(", ");
+function bindingsNames(bindings) {
+    return bindings.map((bindingCollection) => bindingCollection.name).join(", ");
 }
-function toolNames(toolKit) {
-    return Object.keys(toolKit.tools).join(", ");
+function bindingNames(bindingCollection) {
+    return Object.keys(bindingCollection.bindings).join(", ");
 }
 function isHelpFlag(value) {
     return value === "--help" || value === "-h";
@@ -1362,31 +1409,29 @@ 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) {
+async function registerBindingsOnSidecar(client, session, vm, bindings) {
+    if (bindings.length === 0) {
         return "";
     }
-    for (const toolKit of toolKits) {
+    for (const bindingCollection of bindings) {
         await client.registerHostCallbacks(session, vm, {
-            name: toolKit.name,
-            description: toolKit.description,
-            commandAliases: [`agentos-${toolKit.name}`],
+            name: bindingCollection.name,
+            description: bindingCollection.description,
+            commandAliases: [`agentos-${bindingCollection.name}`],
             registryCommandAliases: ["agentos"],
-            callbacks: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
-                toolName,
-                toolToSidecarDefinition(tool),
+            callbacks: Object.fromEntries(Object.entries(bindingCollection.bindings).map(([bindingName, definition]) => [
+                bindingName,
+                bindingToSidecarDefinition(definition),
             ])),
         });
     }
-    return buildHostToolReference(toolKits);
+    return buildBindingReference(bindings);
 }
 export class AgentOs {
     #kernel;
     sidecar;
-    _sessions = new Map();
-    _closedSessionIds = new BoundedSet(CLOSED_SESSION_ID_RETENTION_LIMIT);
-    _sessionClosePromises = new Map();
-    _pendingSessionRequestResolvers = new Map();
+    _durableSessionEventHandlers = new Map();
+    _agentExitHandlers = new Map();
     _processes = new Map();
     _shells = new Map();
     // Value is the recorded exit code (undefined until/unless the exit
@@ -1398,13 +1443,12 @@ export class AgentOs {
     _acpTerminalCounter = 0;
     _softwareRoots;
     _cronManager;
-    _toolKits = [];
-    _toolReference = "";
+    _bindings = [];
+    _bindingReference = "";
     _permissions = allowAll;
     _hostMounts;
     _env;
     _rootFilesystem;
-    _additionalInstructions;
     _sidecarLease = null;
     _sidecarClient;
     _sidecarSession;
@@ -1413,7 +1457,7 @@ export class AgentOs {
     _agentStderrHandler;
     _agentExitHandler;
     _limitWarningHandler;
-    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, agentStderrHandler, agentExitHandler, limitWarningHandler) {
+    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, agentStderrHandler, agentExitHandler, limitWarningHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
         this._softwareRoots = softwareRoots;
@@ -1423,7 +1467,6 @@ export class AgentOs {
         this._sidecarClient = sidecarClient;
         this._sidecarSession = sidecarSession;
         this._sidecarVm = sidecarVm;
-        this._additionalInstructions = additionalInstructions;
         this._agentStderrHandler = agentStderrHandler;
         this._agentExitHandler = agentExitHandler;
         this._limitWarningHandler = limitWarningHandler;
@@ -1448,7 +1491,7 @@ export class AgentOs {
         // Default software is FULLY DYNAMIC: this package's own NON-agent
         // @agentos-software/* dependencies (e.g. common), each default-exporting
         // its registry-built descriptor. Agent packages are NOT projected here —
-        // createSession(id) links the matching agent dependency into the running
+        // openSession({ agent: id }) links the matching agent dependency into the running
         // VM on first use, so agent closures (and pi's V8 snapshot bundle) only
         // enter VMs that run them. Unbuilt packages throw with build
         // instructions; opt out via defaultSoftware: false.
@@ -1479,9 +1522,9 @@ export class AgentOs {
         // sidecar owns agent resolution, agent enumeration, and agent snapshot
         // bundle loading from the projected package dirs.
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
-        const toolKits = options?.toolKits;
-        if (toolKits && toolKits.length > 0) {
-            validateToolkits(toolKits);
+        const bindings = options?.bindings;
+        if (bindings && bindings.length > 0) {
+            validateBindings(bindings);
         }
         // Resolve the sidecar handle up front so every VM created here leases the
         // one shared native sidecar process owned by that handle.
@@ -1491,13 +1534,13 @@ export class AgentOs {
             // forwarded `packages` (it owns the staging dir + read-only mount, and
             // runtime `linkSoftware` appends to that live dir). The client no longer
             // stages packages host-side.
-            const toolBootstrapCommands = collectToolkitBootstrapCommands(toolKits ?? []);
+            const bindingBootstrapCommands = collectBindingBootstrapCommands(bindings ?? []);
             const bootstrapCommands = [
                 ...RUNTIME_BOOTSTRAP_COMMANDS,
-                ...toolBootstrapCommands,
+                ...bindingBootstrapCommands,
             ];
             const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem);
-            let toolReference = "";
+            let bindingReference = "";
             let rootBridge = null;
             let kernel = null;
             let client = null;
@@ -1514,7 +1557,7 @@ export class AgentOs {
                 const env = getBaseEnvironment();
                 // Guest command paths. The sidecar owns the `/opt/agentos` projection and
                 // reports the exact projected package commands after `configureVm`.
-                // Tool-shim commands are added below.
+                // Binding-shim commands are added below.
                 const commandGuestPaths = new Map();
                 const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
                     mounts: options?.mounts,
@@ -1532,11 +1575,24 @@ export class AgentOs {
                 const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
                 const createVmConfig = {
                     env,
+                    database: options?.database,
+                    ...(options?.user ? { user: options.user } : {}),
                     rootFilesystem: serializeRootFilesystemForSidecar(options?.rootFilesystem, bootstrapLower),
                     permissions: sidecarPermissions,
                     limits: options?.limits,
                     loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
                     bootstrapCommands,
+                    ...(options?.rootFilesystem?.type === "native"
+                        ? {
+                            nativeRoot: {
+                                plugin: {
+                                    id: options.rootFilesystem.plugin.id,
+                                    config: options.rootFilesystem.plugin.config ?? {},
+                                },
+                                readOnly: options.rootFilesystem.readOnly ?? false,
+                            },
+                        }
+                        : {}),
                     // 0.3: the Node builtin allow-list moved from configureVm to
                     // VM creation. `undefined` => engine default allow-list;
                     // `[]` => deny all; `[..]` => exactly those. Platform and
@@ -1577,16 +1633,16 @@ export class AgentOs {
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     packages: sidecarPackages,
                     packagesMountAt: OPT_AGENTOS_ROOT,
-                    toolShimCommands: toolBootstrapCommands,
+                    bindingShimCommands: bindingBootstrapCommands,
                 });
                 for (const command of configuredVm.projectedCommands) {
                     commandGuestPaths.set(command.name, command.guestPath);
                 }
-                if (toolKits && toolKits.length > 0) {
-                    toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
+                if (bindings && bindings.length > 0) {
+                    bindingReference = await registerBindingsOnSidecar(client, session, nativeVm, bindings);
                     commandGuestPaths.set("agentos", "/bin/agentos");
-                    for (const toolKit of toolKits) {
-                        commandGuestPaths.set(`agentos-${toolKit.name}`, `/bin/agentos-${toolKit.name}`);
+                    for (const bindingCollection of bindings) {
+                        commandGuestPaths.set(`agentos-${bindingCollection.name}`, `/bin/agentos-${bindingCollection.name}`);
                     }
                 }
                 rootBridge = new NativeSidecarKernelProxy({
@@ -1602,17 +1658,19 @@ export class AgentOs {
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     // Retained for runtime mount reconfigures: `configure_vm` is
                     // replace-on-write for the whole payload, so post-boot mountFs
-                    // must resend the boot packages and tool shims.
+                    // must resend the boot packages and binding shims.
                     packages: sidecarPackages,
                     packagesMountAt: OPT_AGENTOS_ROOT,
-                    toolShimCommands: toolBootstrapCommands,
+                    bindingShimCommands: bindingBootstrapCommands,
                     commandGuestPaths,
                     onDispose: cleanup,
                     // The native process is owned by the AgentOsSidecar handle and
                     // shared across VMs; disposing this VM must not kill the process.
                     ownsClient: false,
                 });
-                await bootstrapLiveBootstrapDirectories(client, session, nativeVm, options?.rootFilesystem);
+                if (options?.rootFilesystem?.type !== "native") {
+                    await bootstrapLiveBootstrapDirectories(client, session, nativeVm, options?.rootFilesystem);
+                }
                 kernel = rootBridge;
                 const snapshotClient = client;
                 return {
@@ -1628,9 +1686,9 @@ export class AgentOs {
                     sidecarSession: session,
                     sidecarVm: nativeVm,
                     permissions: hostPermissions,
-                    snapshotRootFilesystem: async () => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm))),
-                    toolKits: toolKits ?? [],
-                    toolReference,
+                    snapshotRootFilesystem: async (maxBytes) => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm, maxBytes))),
+                    bindings: bindings ?? [],
+                    bindingReference,
                     async dispose() {
                         if (kernel) {
                             const currentKernel = kernel;
@@ -1673,10 +1731,10 @@ export class AgentOs {
                 createVm: async () => createVmAdmin(),
             });
             const vmAdmin = sidecarLease.admin;
-            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.additionalInstructions, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onAgentExit ?? defaultAgentExitHandler, options?.onLimitWarning);
+            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onAgentExit ?? defaultAgentExitHandler, options?.onLimitWarning);
             vm._sidecarLease = sidecarLease;
-            vm._toolKits = vmAdmin.toolKits;
-            vm._toolReference = vmAdmin.toolReference;
+            vm._bindings = vmAdmin.bindings;
+            vm._bindingReference = vmAdmin.bindingReference;
             vm._permissions = vmAdmin.permissions;
             vm._installSidecarRequestHandler();
             vm._cronManager = new CronManager(vm, options?.scheduleDriver ?? new TimerScheduleDriver());
@@ -1694,13 +1752,12 @@ export class AgentOs {
         const kernel = this.#kernel;
         return kernel.execArgv(command, args, options);
     }
-    _trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers) {
+    _trackProcess(proc, command, args, outputHandlers, exitHandlers) {
         const entry = {
             proc,
             command,
             args,
-            stdoutHandlers,
-            stderrHandlers,
+            outputHandlers,
             exitHandlers,
         };
         this._processes.set(proc.pid, entry);
@@ -1711,31 +1768,29 @@ export class AgentOs {
         // in dispose(). (H5: the leak was that dispose() never cleared it.)
         void proc.wait().then((code) => {
             for (const h of exitHandlers)
-                h(code);
+                h({ pid: proc.pid, exitCode: code });
         });
         return { pid: proc.pid };
     }
     spawn(command, args, options) {
-        const stdoutHandlers = new Set();
-        const stderrHandlers = new Set();
+        const outputHandlers = 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);
+                options?.onStdout?.(data);
+                for (const h of outputHandlers) {
+                    h({ pid: proc.pid, stream: "stdout", data });
+                }
             },
             onStderr: (data) => {
-                for (const h of stderrHandlers)
-                    h(data);
+                options?.onStderr?.(data);
+                for (const h of outputHandlers) {
+                    h({ pid: proc.pid, stream: "stderr", data });
+                }
             },
         });
-        return this._trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers);
+        return this._trackProcess(proc, command, args, outputHandlers, exitHandlers);
     }
     /** Write data to a process's stdin. */
     writeProcessStdin(pid, data) {
@@ -1751,24 +1806,14 @@ export class AgentOs {
             throw new Error(`Process not found: ${pid}`);
         return entry.proc.closeStdin();
     }
-    /** Subscribe to stdout data from a process. Returns an unsubscribe function. */
-    onProcessStdout(pid, handler) {
+    /** Subscribe to stdout and stderr from a process. */
+    onProcessOutput(pid, handler) {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.stdoutHandlers.add(handler);
+        entry.outputHandlers.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);
+            entry.outputHandlers.delete(handler);
         };
     }
     /** Subscribe to process exit. Returns an unsubscribe function. */
@@ -1778,7 +1823,7 @@ export class AgentOs {
             throw new Error(`Process not found: ${pid}`);
         // If already exited, call immediately.
         if (entry.proc.exitCode !== null) {
-            handler(entry.proc.exitCode);
+            handler({ pid, exitCode: entry.proc.exitCode });
             return () => { };
         }
         entry.exitHandlers.add(handler);
@@ -1881,6 +1926,15 @@ export class AgentOs {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readdir(path);
     }
+    async readdirEntries(path) {
+        this._assertSafeAbsolutePath(path);
+        const entries = await this.#kernel.readdirRecursive(path, { maxDepth: 0 });
+        return entries.map((entry) => ({
+            name: entry.name,
+            isDirectory: entry.isDirectory,
+            isSymbolicLink: entry.isSymbolicLink,
+        }));
+    }
     async readdirRecursive(path, options) {
         this._assertSafeAbsolutePath(path);
         const exclude = options?.exclude ? new Set(options.exclude) : undefined;
@@ -1919,12 +1973,19 @@ export class AgentOs {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.exists(path);
     }
-    async snapshotRootFilesystem() {
+    async exportRootFilesystem(options) {
+        if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) {
+            throw new RangeError("maxBytes must be a positive safe integer");
+        }
         const nativeSnapshot = this._sidecarLease?.admin.snapshotRootFilesystem;
-        if (nativeSnapshot) {
-            return nativeSnapshot();
+        const snapshot = nativeSnapshot
+            ? await nativeSnapshot(options.maxBytes)
+            : createSnapshotExport(await snapshotVirtualFilesystem(this._rootFilesystem));
+        const size = Buffer.byteLength(JSON.stringify(snapshot));
+        if (size > options.maxBytes) {
+            throw new RangeError(`root filesystem export is ${size} bytes, limit is ${options.maxBytes}; raise maxBytes to export this filesystem`);
         }
-        return createSnapshotExport(await snapshotVirtualFilesystem(this._rootFilesystem));
+        return snapshot;
     }
     /**
      * Mount a filesystem into the running VM. Resolves once the mount has been
@@ -1932,58 +1993,93 @@ export class AgentOs {
      * after the returned promise settles; a delivery failure rejects instead of
      * leaving the mount silently host-only.
      */
-    async mountFs(path, driver, options) {
-        this._assertSafeAbsolutePath(path);
-        await this.#kernel.mountFs(path, driver, { readOnly: options?.readOnly });
+    async mountFs(descriptor) {
+        this._assertSafeAbsolutePath(descriptor.path);
+        if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
+            throw new Error("portable dynamic mounts require the native sidecar");
+        }
+        await this.#kernel.mountDescriptor({
+            guestPath: descriptor.path,
+            readOnly: descriptor.readOnly ?? false,
+            plugin: {
+                id: descriptor.plugin.id,
+                config: descriptor.plugin.config ?? {},
+            },
+        });
     }
     async unmountFs(path) {
         this._assertSafeAbsolutePath(path);
-        await this.#kernel.unmountFs(path);
+        if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
+            throw new Error("portable dynamic mounts require the native sidecar");
+        }
+        await this.#kernel.unmountDescriptor(path);
+    }
+    async listMounts() {
+        if (!(this.#kernel instanceof NativeSidecarKernelProxy))
+            return [];
+        return this.#kernel.listMounts();
     }
     async move(from, to) {
         this._assertWritableAbsolutePath(from);
         this._assertWritableAbsolutePath(to);
         await this.#kernel.movePath(from, to);
     }
-    async delete(path, options) {
+    async remove(path, options) {
         this._assertWritableAbsolutePath(path);
         await this.#kernel.removePath(path, {
             recursive: options?.recursive ?? false,
         });
     }
-    async fetch(port, request) {
-        const url = new URL(request.url);
+    async httpRequest(request) {
+        this._assertSafeAbsolutePath(request.path.split("?")[0] || "/");
+        const method = request.method?.toUpperCase() ?? "GET";
+        const body = typeof request.body === "string"
+            ? request.body
+            : request.body === undefined
+                ? undefined
+                : new TextDecoder().decode(request.body);
         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() }
+            port: request.port,
+            method,
+            path: request.path,
+            headersJson: JSON.stringify(request.headers ?? {}),
+            ...(method !== "GET" && method !== "HEAD" && body !== undefined
+                ? { body }
                 : {}),
         }));
-        const headers = new Headers();
+        const headers = {};
         for (const [key, value] of responsePayload.headers ?? []) {
-            headers.append(key, value);
+            headers[key] = value;
         }
-        return new Response(Buffer.from(responsePayload.body ?? "", "base64"), {
+        return {
             status: responsePayload.status,
-            statusText: responsePayload.statusText,
+            statusText: responsePayload.statusText ?? "",
             headers,
-        });
+            body: new Uint8Array(Buffer.from(responsePayload.body ?? "", "base64")),
+        };
     }
     openShell(options) {
         const shellId = `shell-${++this._shellCounter}`;
         this._closedShellIds.delete(shellId);
         const dataHandlers = new Set();
-        const handle = this.#kernel.openShell(options);
+        const stderrHandlers = new Set();
+        const exitHandlers = new Set();
+        const handle = this.#kernel.openShell({
+            ...options,
+            onStderr: (data) => {
+                for (const handler of stderrHandlers)
+                    handler({ shellId, data });
+            },
+        });
         handle.onData = (data) => {
-            for (const h of dataHandlers)
-                h(data);
+            for (const handler of dataHandlers)
+                handler({ shellId, data });
         };
         const entry = {
             handle,
             dataHandlers,
+            stderrHandlers,
+            exitHandlers,
             exitPromise: Promise.resolve(0),
         };
         const exitPromise = handle.wait();
@@ -1998,6 +2094,8 @@ export class AgentOs {
         };
         entry.exitPromise = exitPromise.then((exitCode) => {
             finalize(exitCode);
+            for (const handler of exitHandlers)
+                handler({ shellId, exitCode });
             return exitCode;
         }, (error) => {
             finalize();
@@ -2017,7 +2115,11 @@ export class AgentOs {
             throw new Error(`Shell not found: ${shellId}`);
         return entry.handle.write(data);
     }
-    /** Subscribe to data output from a shell. Returns an unsubscribe function. */
+    /**
+     * Subscribe to ordered PTY output (stdout and stderr). Returns an unsubscribe
+     * function. `OpenShellOptions.onStderr` is a diagnostic tap for callers that
+     * need channel identity; do not render both surfaces.
+     */
     onShellData(shellId, handler) {
         const entry = this._shells.get(shellId);
         if (!entry)
@@ -2027,6 +2129,28 @@ export class AgentOs {
             entry.dataHandlers.delete(handler);
         };
     }
+    /** Subscribe to the stderr-only diagnostic stream for a shell. */
+    onShellStderr(shellId, handler) {
+        const entry = this._shells.get(shellId);
+        if (!entry)
+            throw new Error(`Shell not found: ${shellId}`);
+        entry.stderrHandlers.add(handler);
+        return () => entry.stderrHandlers.delete(handler);
+    }
+    /** Subscribe to shell exit. */
+    onShellExit(shellId, handler) {
+        const entry = this._shells.get(shellId);
+        if (!entry) {
+            const exitCode = this._closedShellIds.get(shellId);
+            if (exitCode !== undefined) {
+                handler({ shellId, exitCode });
+                return () => { };
+            }
+            throw new Error(`Shell not found: ${shellId}`);
+        }
+        entry.exitHandlers.add(handler);
+        return () => entry.exitHandlers.delete(handler);
+    }
     /** Notify a shell of terminal resize. */
     resizeShell(shellId, cols, rows) {
         const entry = this._shells.get(shellId);
@@ -2148,39 +2272,216 @@ export class AgentOs {
             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,
-        }));
+    async openSession(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpOpenSessionRequest",
+            val: {
+                sessionId: input.sessionId ?? null,
+                agent: input.agent,
+                cwd: input.cwd ?? null,
+                additionalDirectories: input.additionalDirectories === undefined
+                    ? null
+                    : JSON.stringify(input.additionalDirectories),
+                env: input.env === undefined ? null : JSON.stringify(input.env),
+                mcpServers: input.mcpServers === undefined
+                    ? null
+                    : JSON.stringify(input.mcpServers),
+                permissionPolicy: input.permissionPolicy ?? null,
+                skipOsInstructions: input.skipOsInstructions ?? null,
+                additionalInstructions: combineInstructions(input.additionalInstructions, this._bindingReference) ?? null,
+            },
+        });
+        if (response.tag !== "AcpOpenSessionResponse") {
+            throw new Error(`unexpected openSession response: ${response.tag}`);
+        }
     }
-    /** Internal helper: retrieve a session or throw. */
-    _requireSession(sessionId) {
-        const session = this._sessions.get(sessionId);
-        if (!session) {
-            throw new Error(`Session not found: ${sessionId}`);
+    async getSession(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetDurableSessionRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpGetDurableSessionResponse") {
+            throw new Error(`unexpected getSession response: ${response.tag}`);
         }
-        return session;
+        return decodeDurableSessionInfo(response.val.session);
+    }
+    async listSessions(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpListDurableSessionsRequest",
+            val: { cursor: input?.cursor ?? null, limit: input?.limit ?? null },
+        });
+        if (response.tag !== "AcpListDurableSessionsResponse") {
+            throw new Error(`unexpected listSessions response: ${response.tag}`);
+        }
+        return {
+            sessions: response.val.sessions.map(decodeDurableSessionInfo),
+            nextCursor: response.val.nextCursor,
+        };
+    }
+    async deleteSession(input = {}) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpDeleteSessionRequest",
+            val: { sessionId: input.sessionId ?? null },
+        });
+        if (response.tag !== "AcpDeleteSessionResponse") {
+            throw new Error(`unexpected deleteSession response: ${response.tag}`);
+        }
+    }
+    async unloadSession(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpUnloadSessionRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpUnloadSessionResponse") {
+            throw new Error(`unexpected unloadSession response: ${response.tag}`);
+        }
+    }
+    async prompt(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpPromptRequest",
+            val: {
+                sessionId: input.sessionId ?? null,
+                idempotencyKey: input.idempotencyKey ?? null,
+                content: JSON.stringify(input.content),
+            },
+        });
+        if (response.tag !== "AcpPromptResponse") {
+            throw new Error(`unexpected prompt response: ${response.tag}`);
+        }
+        return {
+            sessionId: response.val.sessionId,
+            message: response.val.message === null ? null : JSON.parse(response.val.message),
+            stopReason: response.val.stopReason,
+        };
+    }
+    async cancelPrompt(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpCancelPromptRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpCancelPromptResponse") {
+            throw new Error(`unexpected cancelPrompt response: ${response.tag}`);
+        }
+        if (response.val.status !== "cancelled" &&
+            response.val.status !== "no_active_prompt") {
+            throw new Error(`invalid cancelPrompt status: ${response.val.status}`);
+        }
+        return { status: response.val.status };
+    }
+    async respondPermission(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpRespondPermissionRequest",
+            val: {
+                sessionId: input.sessionId,
+                requestId: input.requestId,
+                optionId: input.optionId,
+            },
+        });
+        if (response.tag !== "AcpRespondPermissionResponse") {
+            throw new Error(`unexpected respondPermission response: ${response.tag}`);
+        }
+        if (response.val.status !== "accepted" &&
+            response.val.status !== "not_pending") {
+            throw new Error(`invalid respondPermission status: ${response.val.status}`);
+        }
+        if (response.val.status === "accepted") {
+            if (response.val.reason !== null) {
+                throw new Error("accepted permission response must not include a reason");
+            }
+            return { status: "accepted" };
+        }
+        return {
+            status: "not_pending",
+            reason: permissionTerminalReason(response.val.reason),
+        };
+    }
+    async readHistory(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpReadHistoryRequest",
+            val: {
+                sessionId: input?.sessionId ?? null,
+                before: input?.before === undefined ? null : BigInt(input.before),
+                after: input?.after === undefined ? null : BigInt(input.after),
+                limit: input?.limit ?? null,
+            },
+        });
+        if (response.tag !== "AcpHistoryPageResponse") {
+            throw new Error(`unexpected readHistory response: ${response.tag}`);
+        }
+        return {
+            events: response.val.events.map(decodeDurableSessionEvent),
+            hasMoreBefore: response.val.hasMoreBefore,
+            hasMoreAfter: response.val.hasMoreAfter,
+        };
+    }
+    async getSessionConfig(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionConfigRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpSessionConfigResponse") {
+            throw new Error(`unexpected getSessionConfig response: ${response.tag}`);
+        }
+        return {
+            revision: safeWireU64(response.val.revision),
+            options: JSON.parse(response.val.options),
+        };
+    }
+    async setSessionConfigOption(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpSetSessionConfigOptionRequest",
+            val: {
+                sessionId: input.sessionId ?? null,
+                configId: input.configId,
+                value: JSON.stringify(input.value),
+            },
+        });
+        if (response.tag !== "AcpSessionConfigResponse") {
+            throw new Error(`unexpected setSessionConfigOption response: ${response.tag}`);
+        }
+        return {
+            revision: safeWireU64(response.val.revision),
+            options: JSON.parse(response.val.options),
+        };
+    }
+    async getSessionCapabilities(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionCapabilitiesRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpSessionCapabilitiesResponse") {
+            throw new Error(`unexpected getSessionCapabilities response: ${response.tag}`);
+        }
+        return response.val.capabilities === null
+            ? null
+            : normalizeSessionCapabilities(JSON.parse(response.val.capabilities));
+    }
+    async getSessionAgentInfo(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionAgentInfoRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpSessionAgentInfoResponse") {
+            throw new Error(`unexpected getSessionAgentInfo response: ${response.tag}`);
+        }
+        return response.val.agentInfo === null
+            ? null
+            : JSON.parse(response.val.agentInfo);
     }
     /**
      * Dynamically link a software package into the RUNNING VM. The package's
      * `bin/` commands appear under `/opt/agentos/bin` (on `$PATH`) and its `share/man`
      * pages under MANPATH immediately — the `/opt/agentos` mount is host-backed, so
      * writing into its staging dir is reflected live with no reboot. An `agent`
-     * block registers the package for `createSession(name)`. Persists for the VM's
+     * block registers the package for `openSession({ agent: name })`. Persists for the VM's
      * lifetime (and across a snapshot iff the volume persists).
      */
     async linkSoftware(descriptor) {
-        const ref = normalizePackageRef(descriptor);
-        if (!ref) {
-            throw new Error("Invalid agentOS package reference");
-        }
         // Forward to the sidecar, which owns the `/opt/agentos` projection and
         // appends the package to its live host-backed staging dir; the commands
         // appear under `/opt/agentos/bin` immediately. The sidecar rejects a
         // duplicate command, surfaced here as a thrown error.
-        const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, { path: ref.path });
+        const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, descriptor);
         if (this.#kernel instanceof NativeSidecarKernelProxy) {
             this.#kernel.registerCommandGuestPaths(new Map(commands.projectedCommands.map((command) => [
                 command.name,
@@ -2189,13 +2490,13 @@ export class AgentOs {
             // Retain the linked package for runtime mount reconfigures:
             // `configure_vm` is replace-on-write, so a later `mountFs` that
             // resent only the boot packages would unproject this one.
-            this.#kernel.registerLinkedPackage({ path: ref.path });
+            this.#kernel.registerLinkedPackage(descriptor);
         }
         // The client parses no manifests: an `agent` block in the linked package is
         // picked up by the sidecar (it owns the projected `/opt/agentos` and answers
-        // createSession/listAgents from it). Nothing to record client-side.
+        // openSession/listAgents from it). Nothing to record client-side.
     }
-    async providedCommands() {
+    async listSoftware() {
         return this._sidecarClient.providedCommands(this._sidecarSession, this._sidecarVm);
     }
     /**
@@ -2215,145 +2516,10 @@ export class AgentOs {
         return response.val.agents.map((agent) => ({
             id: agent.id,
             installed: agent.installed,
-            adapterEntrypoint: agent.adapterEntrypoint,
         }));
     }
-    _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);
-        };
-    }
-    /**
-     * Warn once per session (host-visible) that a tool-permission request was
-     * auto-denied because no `onPermissionRequest` handler is registered. Shared
-     * by both the bare-callback and JSON-RPC permission paths so the message and
-     * the once-per-session guard cannot drift between them.
-     */
-    _warnNoPermissionHandlerOnce(session, params) {
-        if (session.warnedNoPermissionHandler) {
-            return;
-        }
-        session.warnedNoPermissionHandler = true;
-        this._emitSessionWarning(session, `agentos: a tool-permission request (${this._permissionToolLabel(params)}) was ` +
-            `auto-denied because no onPermissionRequest handler is registered for session ` +
-            `${session.sessionId}. Register one with vm.onPermissionRequest(sessionId, ...) and ` +
-            `reply via vm.respondPermission(...) to let the agent use tools.`);
-    }
-    /** Best-effort human label for the tool named in a permission request. */
-    _permissionToolLabel(params) {
-        if (typeof params.toolName === "string") {
-            return params.toolName;
-        }
-        const toolCall = params.toolCall;
-        if (toolCall &&
-            typeof toolCall === "object" &&
-            typeof toolCall.title === "string") {
-            return toolCall.title;
-        }
-        return "a tool";
-    }
-    /**
-     * Emit a host-visible warning for a session through the same agent-process log
-     * channel that surfaces adapter stderr (`onAgentStderr`, default: process
-     * stderr). Used for agent-os-owned diagnostics — e.g. a permission request
-     * that was auto-denied because no host hook is registered — so they never fire
-     * silently inside the sidecar.
-     */
-    _emitSessionWarning(session, message) {
-        const handler = this._agentStderrHandler;
-        if (!handler) {
-            return;
-        }
-        try {
-            handler({
-                sessionId: session.sessionId,
-                agentType: session.agentType,
-                processId: session.processId,
-                pid: session.pid,
-                chunk: new TextEncoder().encode(`${message}\n`),
-            });
-        }
-        catch {
-            // A warning sink failure must never affect permission handling.
-        }
-    }
     _recordAgentStderr(event) {
-        const session = (event.sessionId ? this._sessions.get(event.sessionId) : undefined) ??
-            [...this._sessions.values()].find((candidate) => candidate.processId === event.processId);
-        const sessionId = event.sessionId || session?.sessionId;
-        if (!sessionId) {
+        if (!event.sessionId) {
             return;
         }
         const handler = this._agentStderrHandler;
@@ -2362,52 +2528,47 @@ export class AgentOs {
         }
         try {
             handler({
-                sessionId,
-                agentType: event.agentType || session?.agentType || "",
+                sessionId: event.sessionId,
+                agentType: event.agentType,
                 processId: event.processId,
-                pid: session?.pid ?? null,
+                pid: null,
                 chunk: new Uint8Array(event.chunk),
             });
         }
-        catch {
-            // Ignore subscriber callback failures and keep event delivery moving.
+        catch (error) {
+            console.error("AgentOS stderr handler failed", error);
         }
     }
     _recordAgentExit(event) {
-        const session = this._sessions.get(event.sessionId);
+        const publicEvent = {
+            sessionId: event.sessionId,
+            agentType: event.agentType,
+            processId: event.processId,
+            pid: event.pid,
+            exitCode: event.exitCode,
+            restart: event.restart,
+            restartCount: event.restartCount,
+            maxRestarts: event.maxRestarts,
+        };
         const handler = this._agentExitHandler;
-        if (!handler) {
-            return;
-        }
-        try {
-            handler({
-                sessionId: event.sessionId,
-                agentType: event.agentType || session?.agentType || "",
-                processId: event.processId,
-                pid: session?.pid ?? null,
-                exitCode: event.exitCode,
-                restart: event.restart,
-                restartCount: event.restartCount,
-                maxRestarts: event.maxRestarts,
-            });
-        }
-        catch {
-            // Ignore subscriber callback failures and keep event delivery moving.
+        if (handler) {
+            try {
+                handler(publicEvent);
+            }
+            catch (error) {
+                console.error("AgentOS agent-exit handler failed", error);
+            }
         }
-    }
-    _applySyntheticConfigOverrides(session) {
-        if (session.configOverrides.size === 0) {
-            return;
+        for (const key of ["*", event.sessionId]) {
+            for (const subscription of this._agentExitHandlers.get(key) ?? []) {
+                try {
+                    subscription(publicEvent);
+                }
+                catch (error) {
+                    console.error("AgentOS agent-exit subscription failed", error);
+                }
+            }
         }
-        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") {
@@ -2419,25 +2580,6 @@ export class AgentOs {
         }
         if (event.payload.name === "limit_warning") {
             this._handleLimitWarning(event.payload.detail);
-            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.
         }
     }
     _handleLimitWarning(detail) {
@@ -2457,8 +2599,8 @@ export class AgentOs {
                 fillPercent: toNumber(detail.fillPercent),
             });
         }
-        catch {
-            // A throwing handler must never break the sidecar event loop.
+        catch (error) {
+            console.error("AgentOS limit-warning handler failed", error);
         }
     }
     _handleAcpExtEvent(envelope) {
@@ -2468,14 +2610,24 @@ export class AgentOs {
         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)));
+                case "AcpDurableSessionEvent": {
+                    this._emitDurableSessionEvent(decodeDurableSessionEvent(event.val));
                     return;
                 }
+                case "AcpEphemeralSessionUpdateEvent": {
+                    const update = JSON.parse(event.val.update);
+                    const { sessionUpdate: type, ...payload } = update;
+                    this._emitDurableSessionEvent({
+                        durability: "ephemeral",
+                        type,
+                        sessionId: event.val.sessionId,
+                        afterSequence: safeWireU64(event.val.afterSequence),
+                        ...payload,
+                    });
+                    return;
+                }
+                case "AcpSessionEvent":
+                    return;
                 case "AcpAgentStderrEvent": {
                     this._recordAgentStderr(event.val);
                     return;
@@ -2486,22 +2638,19 @@ export class AgentOs {
                 }
             }
         }
-        catch {
-            // Ignore malformed event payloads from the sidecar.
+        catch (error) {
+            console.error("AgentOS failed to decode an ACP sidecar event", error);
         }
     }
-    _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,
-            },
-        };
+    _emitDurableSessionEvent(entry) {
+        for (const handler of this._durableSessionEventHandlers.get(entry.sessionId) ?? []) {
+            try {
+                handler(entry);
+            }
+            catch (error) {
+                console.error("AgentOS session event handler failed", error);
+            }
+        }
     }
     async _sendAcpRequest(request) {
         const envelope = await this._sidecarClient.extensionRequest(this._sidecarSession, this._sidecarVm, {
@@ -2519,300 +2668,10 @@ export class AgentOs {
         }
         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) {
-        // The client is npm-agnostic: it sends only the agent NAME. The sidecar
-        // resolves the name -> package -> entrypoint/env/launchArgs from the
-        // projected `/opt/agentos/<name>/current/agentos-package.json` and spawns
-        // (including the agent's static launch args and manifest env defaults).
-        // System-prompt assembly/injection (launch args / OPENCODE_CONTEXTPATHS) is
-        // owned by the sidecar; the host only forwards additionalInstructions /
-        // skipOsInstructions plus the caller's env.
-        const launchEnv = { ...options?.env };
-        const sessionCwd = options?.cwd ?? "/workspace";
-        const response = await this._sendAcpRequest({
-            tag: "AcpCreateSessionRequest",
-            val: {
-                agentType: String(agentType),
-                runtime: AcpRuntimeKind.JavaScript,
-                args: [],
-                env: new Map(Object.entries(launchEnv)),
-                cwd: sessionCwd,
-                mcpServers: JSON.stringify(options?.mcpServers ?? []),
-                protocolVersion: ACP_PROTOCOL_VERSION,
-                clientCapabilities: JSON.stringify(defaultAcpClientCapabilities()),
-                additionalInstructions: combineInstructions([this._additionalInstructions, options?.additionalInstructions]
-                    .map((part) => part?.trim())
-                    .filter((part) => Boolean(part))
-                    .join("\n\n") || undefined, 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) {
-        // The client is npm-agnostic: it sends only the agent NAME. The sidecar
-        // resolves the name -> package -> entrypoint/env/launchArgs from the
-        // projected manifest, exactly as createSession does.
-        const sessionCwd = options?.cwd ?? "/workspace";
-        const launchEnv = { ...options?.env };
-        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 existing = this._sessions.get(liveSessionId);
-        if (existing !== undefined && !existing.closed) {
-            throw new Error(`session id collision: ${liveSessionId}`);
-        }
-        const session = sessionEntryFromInit(liveSessionId, String(agentType), {});
-        this._closedSessionIds.delete(liveSessionId);
-        this._sessions.set(liveSessionId, session);
-        try {
-            await this._hydrateSessionState(session);
-        }
-        catch (error) {
-            this._removeSession(liveSessionId);
-            throw error;
-        }
-        return { sessionId: liveSessionId, mode };
-    }
     _installSidecarRequestHandler() {
         const context = {
-            toolKits: this._toolKits,
-            toolMap: buildToolMap(this._toolKits),
+            bindings: this._bindings,
+            bindingMap: buildBindingMap(this._bindings),
             permissions: this._permissions,
             readFile: (path) => this.readFile(path),
         };
@@ -2841,25 +2700,6 @@ export class AgentOs {
         }
         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 {
@@ -2911,8 +2751,6 @@ export class AgentOs {
     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);
@@ -2945,99 +2783,6 @@ export class AgentOs {
                 });
         }
     }
-    _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) {
-            // Default-closed deny; warn once (host-visible) so a forgotten
-            // onPermissionRequest handler is an observable cause rather than a
-            // silent denial. See _warnNoPermissionHandlerOnce.
-            this._warnNoPermissionHandlerOnce(session, permissionParams);
-            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 {};
@@ -3210,9 +2955,6 @@ export class AgentOs {
                 ...(cwd ? { cwd } : {}),
                 ...(cols !== undefined ? { cols: Math.trunc(cols) } : {}),
                 ...(rows !== undefined ? { rows: Math.trunc(rows) } : {}),
-                onStderr: (data) => {
-                    this._appendAcpTerminalOutput(terminal, data);
-                },
             }),
             output: "",
             truncated: false,
@@ -3289,193 +3031,38 @@ export class AgentOs {
         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) {
-            // Default-closed: deny when no host hook is listening, and warn once
-            // (host-visible) so a forgotten onPermissionRequest handler is not an
-            // invisible cause of an agent that cannot use any tool.
-            this._warnNoPermissionHandlerOnce(session, params);
-            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";
-        }
-    }
-    /**
-     * 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);
+    onSessionEvent(sessionIdOrHandler, maybeHandler) {
+        const sessionId = typeof sessionIdOrHandler === "string" ? sessionIdOrHandler : "main";
+        const handler = typeof sessionIdOrHandler === "function"
+            ? sessionIdOrHandler
+            : maybeHandler;
+        if (!handler) {
+            throw new TypeError("onSessionEvent requires a handler");
         }
-        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 handlers = this._durableSessionEventHandlers.get(sessionId) ?? new Set();
+        handlers.add(handler);
+        this._durableSessionEventHandlers.set(sessionId, handlers);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this._durableSessionEventHandlers.delete(sessionId);
             }
         };
-        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);
+    onAgentExit(sessionIdOrHandler, maybeHandler) {
+        const sessionId = typeof sessionIdOrHandler === "string" ? sessionIdOrHandler : "*";
+        const handler = typeof sessionIdOrHandler === "function"
+            ? sessionIdOrHandler
+            : maybeHandler;
+        if (!handler)
+            throw new TypeError("onAgentExit requires a handler");
+        const handlers = this._agentExitHandlers.get(sessionId) ?? new Set();
+        handlers.add(handler);
+        this._agentExitHandlers.set(sessionId, handlers);
         return () => {
-            session.permissionHandlers.delete(handler);
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this._agentExitHandlers.delete(sessionId);
         };
     }
     // ── Cron ────────────────────────────────────────────────────
@@ -3497,9 +3084,6 @@ export class AgentOs {
     }
     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();
         }
@@ -3583,7 +3167,17 @@ function applySharedSidecarHold(state) {
     if (!child)
         return;
     const hold = (state.eventLoopHolds ?? 0) > 0;
-    for (const handle of [child, child.stdin, child.stdout, child.stderr]) {
+    // Include the complete stdio array, not just the named fd0-fd2 aliases.
+    // Protocol v8 carries responses over fd3; leaving that control socket
+    // referenced pins Node's event loop after the final VM lease is disposed.
+    const handles = new Set([
+        child,
+        child.stdin,
+        child.stdout,
+        child.stderr,
+        ...(child.stdio ?? []),
+    ]);
+    for (const handle of handles) {
         if (!handle)
             continue;
         try {
@@ -3790,7 +3384,7 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
     }
     let transport;
     const client = createAgentOsSidecarClient({
-        async createSessionTransport(sessionBootstrap) {
+        async createOwnershipTransport(sessionBootstrap) {
             transport = await createInProcessSidecarTransport(sessionBootstrap, options);
             return transport;
         },
@@ -3810,7 +3404,7 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
     let disposed = false;
     let leaseRecord;
     try {
-        const session = await client.createSession({
+        const session = await client.createOwnershipSession({
             placement: cloneSidecarPlacement(state.description.placement),
         });
         const vm = await session.createVm();