@rivet-dev/agentos-core 0.0.0-main.2f99c77 → 0.0.0-main.5ac5a14

package/dist/agent-os.js

@@ -3,22 +3,143 @@ 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 * as executionProtocol from "@rivet-dev/agentos-runtime-core/protocol";
+import { SidecarRejectedError } from "@rivet-dev/agentos-runtime-core/sidecar-errors";
+import { validateBindings } from "./bindings.js";
+import { zodToJsonSchema } from "./bindings-zod.js";
 import { parseAgentOsOptions } from "./options-schema.js";
+import { getSandboxDisposeHooks, resolveSandboxOptions, } from "./sandbox.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() {
+const PROCESS_OUTPUT_EVENT_LIMIT = 1_024;
+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 +153,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 +243,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 +279,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 +474,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 +506,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 +522,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 +593,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 +766,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 +791,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 +808,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 +817,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 +867,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 +875,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 +898,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 +910,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 +954,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 +970,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 +982,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 +993,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 +1099,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 +1147,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 +1249,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 +1323,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 +1400,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,32 +1413,230 @@ 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);
+}
+function executionIdentity(options) {
+    return {
+        contextId: options.contextId ?? null,
+    };
+}
+function executionOutput(options, background = false) {
+    if (options.output?.retainEvents && !options.contextId && !background) {
+        throw new Error("retainEvents is available only for spawned processes; use output.capture for attached runs");
+    }
+    const capture = options.output?.capture;
+    return {
+        capture: capture === "all"
+            ? executionProtocol.ExecutionOutputCapture.All
+            : capture === "stderr"
+                ? executionProtocol.ExecutionOutputCapture.Stderr
+                : capture === "none"
+                    ? executionProtocol.ExecutionOutputCapture.None
+                    : null,
+        retainEvents: options.output?.retainEvents ?? null,
+    };
+}
+function executionBytes(data) {
+    if (data === undefined)
+        return null;
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    return bytes.slice().buffer;
+}
+function processExecutionOptions(options = {}, internal) {
+    const background = internal?.background ?? false;
+    return {
+        identity: executionIdentity(options),
+        output: executionOutput(options, background),
+        operationId: internal?.executionId ?? null,
+        background,
+        cwd: options.cwd ?? null,
+        env: options.env ? new Map(Object.entries(options.env)) : null,
+        args: options.args ?? [],
+        stdin: executionBytes(options.stdin),
+        timeoutMs: protocolTimeout(options.timeoutMs),
+        pty: options.pty
+            ? {
+                cols: options.pty.cols === undefined
+                    ? null
+                    : protocolUnsigned(options.pty.cols, 0xffff, "pty.cols"),
+                rows: options.pty.rows === undefined
+                    ? null
+                    : protocolUnsigned(options.pty.rows, 0xffff, "pty.rows"),
+            }
+            : null,
+    };
+}
+function protocolUnsigned(value, maximum, name) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > maximum) {
+        throw new RangeError(`${name} must be an integer between 0 and ${maximum}`);
+    }
+    return value;
+}
+function protocolTimeout(value) {
+    if (value === undefined)
+        return null;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("timeoutMs must be a non-negative safe integer");
+    }
+    return BigInt(value);
+}
+function safeProtocolNumber(value, name) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result)) {
+        throw new RangeError(`${name} exceeds JavaScript's safe integer range`);
+    }
+    return result;
+}
+function mapExecutionState(state) {
+    const mapped = state.toLowerCase();
+    return (mapped === "creating" ? "idle" : mapped);
+}
+function mapExecutionOutcome(outcome) {
+    return outcome === executionProtocol.ExecutionOutcome.TimedOut
+        ? "timed_out"
+        : outcome.toLowerCase();
+}
+function mapExecutionDescriptor(descriptor) {
+    return {
+        contextId: descriptor.executionId,
+        state: mapExecutionState(descriptor.state),
+        ...(descriptor.retainedLanguage
+            ? {
+                language: descriptor.retainedLanguage ===
+                    executionProtocol.RetainedExecutionLanguage.JavaScript
+                    ? "javascript"
+                    : "python",
+            }
+            : {}),
+        createdAtMs: safeProtocolNumber(descriptor.createdAtMs, "createdAtMs"),
+        ...(descriptor.lastStartedAtMs !== null
+            ? {
+                lastStartedAtMs: safeProtocolNumber(descriptor.lastStartedAtMs, "lastStartedAtMs"),
+            }
+            : {}),
+        ...(descriptor.lastCompletedAtMs !== null
+            ? {
+                lastCompletedAtMs: safeProtocolNumber(descriptor.lastCompletedAtMs, "lastCompletedAtMs"),
+            }
+            : {}),
+    };
+}
+function mapExecutionError(error) {
+    if (!error)
+        return undefined;
+    return {
+        code: error.code,
+        name: error.name,
+        message: error.message,
+        ...(error.stack ? { stack: error.stack } : {}),
+        ...(error.details
+            ? { details: JSON.parse(error.details) }
+            : {}),
+    };
+}
+function mapExecutionResult(result) {
+    const base = {
+        ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+        ...(result.stdout !== null
+            ? { stdout: new TextDecoder().decode(result.stdout) }
+            : {}),
+        ...(result.stderr !== null
+            ? { stderr: new TextDecoder().decode(result.stderr) }
+            : {}),
+        ...(result.stdoutTruncated !== null
+            ? { stdoutTruncated: result.stdoutTruncated }
+            : {}),
+        ...(result.stderrTruncated !== null
+            ? { stderrTruncated: result.stderrTruncated }
+            : {}),
+        ...(result.evaluationValue
+            ? { evaluationValue: JSON.parse(result.evaluationValue) }
+            : {}),
+        ...(result.typeScriptCheckResult
+            ? {
+                typeScriptCheckResult: JSON.parse(result.typeScriptCheckResult),
+            }
+            : {}),
+    };
+    const outcome = mapExecutionOutcome(result.outcome);
+    if (outcome === "succeeded") {
+        return { ...base, outcome };
+    }
+    return {
+        ...base,
+        outcome,
+        error: mapExecutionError(result.error) ?? {
+            code: "execution_failed",
+            name: "ExecutionError",
+            message: `execution completed with ${outcome}`,
+        },
+    };
+}
+function mapTypeScriptCheckResult(result) {
+    if (result.outcome !== "succeeded") {
+        return { ...result, diagnostics: [] };
+    }
+    const data = result.typeScriptCheckResult;
+    if (!data || Array.isArray(data) || typeof data !== "object") {
+        throw new Error("TypeScript checker returned no diagnostic result");
+    }
+    const hasErrors = data.hasErrors;
+    const diagnostics = data.diagnostics;
+    if (typeof hasErrors !== "boolean" || !Array.isArray(diagnostics)) {
+        throw new Error("TypeScript checker returned an invalid diagnostic result");
+    }
+    return {
+        ...result,
+        hasErrors,
+        diagnostics: diagnostics,
+    };
+}
+function mapExecutionOutputEvent(event) {
+    return {
+        executionId: event.executionId,
+        generation: safeProtocolNumber(event.generation, "execution generation"),
+        ...(event.processId ? { processId: event.processId } : {}),
+        sequence: safeProtocolNumber(event.sequence, "execution output sequence"),
+        channel: event.channel.toLowerCase(),
+        chunk: new Uint8Array(event.chunk),
+        timestampMs: safeProtocolNumber(event.timestampMs, "execution timestamp"),
+    };
+}
+function mapExecutionCompletedEvent(event) {
+    return {
+        executionId: event.executionId,
+        generation: safeProtocolNumber(event.generation, "execution generation"),
+        outcome: mapExecutionOutcome(event.outcome),
+        ...(event.exitCode !== null ? { exitCode: event.exitCode } : {}),
+        ...(event.error ? { error: mapExecutionError(event.error) } : {}),
+    };
 }
 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();
+    _languageProcesses = new Map();
+    _languageProcessIds = new Map();
+    _executionOutputHandlers = new Map();
+    _executionCompletedHandlers = new Map();
     _shells = new Map();
     // Value is the recorded exit code (undefined until/unless the exit
     // resolves) so waitShell can still report it after the entry is dropped.
@@ -1398,13 +1647,12 @@ export class AgentOs {
     _acpTerminalCounter = 0;
     _softwareRoots;
     _cronManager;
-    _toolKits = [];
-    _toolReference = "";
+    _bindings = [];
+    _bindingReference = "";
     _permissions = allowAll;
     _hostMounts;
     _env;
     _rootFilesystem;
-    _additionalInstructions;
     _sidecarLease = null;
     _sidecarClient;
     _sidecarSession;
@@ -1413,7 +1661,121 @@ export class AgentOs {
     _agentStderrHandler;
     _agentExitHandler;
     _limitWarningHandler;
-    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, agentStderrHandler, agentExitHandler, limitWarningHandler) {
+    _disposeHooks = [];
+    /**
+     * Execute commands and manage child processes in the VM.
+     *
+     * `exec` evaluates a command with the configured shell, while `execFile`
+     * invokes an executable directly with an argv array.
+     */
+    process = {
+        exec: this._exec.bind(this),
+        execFile: this._execFile.bind(this),
+        spawn: this._spawnProcess.bind(this),
+        get: this._getProcess.bind(this),
+        list: this._listProcesses.bind(this),
+        tree: this._processTree.bind(this),
+        wait: this._waitProcess.bind(this),
+        signal: this._signalProcess.bind(this),
+        kill: this._killProcess.bind(this),
+        writeStdin: this._writeProcessStdin.bind(this),
+        closeStdin: this._closeProcessStdin.bind(this),
+        resizePty: this._resizeProcessPty.bind(this),
+        readOutput: this._readProcessOutput.bind(this),
+    };
+    javascript = {
+        execute: this._executeJavaScript.bind(this),
+        evaluate: this._evaluateJavaScript.bind(this),
+        executeFile: this._executeJavaScriptFile.bind(this),
+        spawn: this._spawnJavaScript.bind(this),
+        spawnFile: this._spawnJavaScriptFile.bind(this),
+        npm: {
+            install: this._installNpmPackages.bind(this),
+            runScript: this._executeNpmScript.bind(this),
+            runPackage: this._executeNpmPackage.bind(this),
+        },
+    };
+    typescript = {
+        execute: this._executeTypeScript.bind(this),
+        evaluate: this._evaluateTypeScript.bind(this),
+        executeFile: this._executeTypeScriptFile.bind(this),
+        spawn: this._spawnTypeScript.bind(this),
+        spawnFile: this._spawnTypeScriptFile.bind(this),
+        check: this._checkTypeScript.bind(this),
+        checkProject: this._checkTypeScriptProject.bind(this),
+    };
+    python = {
+        execute: this._executePython.bind(this),
+        evaluate: this._evaluatePython.bind(this),
+        executeFile: this._executePythonFile.bind(this),
+        executeModule: this._executePythonModule.bind(this),
+        spawn: this._spawnPython.bind(this),
+        spawnFile: this._spawnPythonFile.bind(this),
+        spawnModule: this._spawnPythonModule.bind(this),
+        install: this._installPythonPackages.bind(this),
+    };
+    contexts = {
+        get: this._getContext.bind(this),
+        list: this._listContexts.bind(this),
+        reset: this._resetContext.bind(this),
+        delete: this._deleteContext.bind(this),
+    };
+    terminal = {
+        open: this._openTerminal.bind(this),
+        write: this._writeTerminal.bind(this),
+        resize: this._resizeTerminal.bind(this),
+        wait: this._waitTerminal.bind(this),
+        close: this._closeTerminal.bind(this),
+    };
+    filesystem = {
+        readFile: this._readFile.bind(this),
+        writeFile: this._writeFile.bind(this),
+        readFiles: this._readFiles.bind(this),
+        writeFiles: this._writeFiles.bind(this),
+        stat: this._stat.bind(this),
+        mkdir: this._mkdir.bind(this),
+        readdir: this._readdir.bind(this),
+        readdirEntries: this._readdirEntries.bind(this),
+        readdirRecursive: this._readdirRecursive.bind(this),
+        exists: this._exists.bind(this),
+        move: this._move.bind(this),
+        remove: this._remove.bind(this),
+        export: this._exportRootFilesystem.bind(this),
+        mount: this._mountFs.bind(this),
+        unmount: this._unmountFs.bind(this),
+        listMounts: this._listMounts.bind(this),
+    };
+    network = {
+        httpRequest: this._httpRequest.bind(this),
+    };
+    software = {
+        list: this._listSoftware.bind(this),
+        link: this._linkSoftware.bind(this),
+    };
+    agents = {
+        list: this._listAgents.bind(this),
+    };
+    sessions = {
+        open: this._openSession.bind(this),
+        get: this._getSession.bind(this),
+        list: this._listSessions.bind(this),
+        delete: this._deleteSession.bind(this),
+        unload: this._unloadSession.bind(this),
+        prompt: this._prompt.bind(this),
+        cancelPrompt: this._cancelPrompt.bind(this),
+        respondPermission: this._respondPermission.bind(this),
+        readHistory: this._readHistory.bind(this),
+        getConfig: this._getSessionConfig.bind(this),
+        setConfigOption: this._setSessionConfigOption.bind(this),
+        getCapabilities: this._getSessionCapabilities.bind(this),
+        getAgentInfo: this._getSessionAgentInfo.bind(this),
+    };
+    cron = {
+        schedule: this._scheduleCron.bind(this),
+        list: this._listCronJobs.bind(this),
+        cancel: this._cancelCronJob.bind(this),
+    };
+    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, agentStderrHandler, agentExitHandler, limitWarningHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
         this._softwareRoots = softwareRoots;
@@ -1423,7 +1785,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 +1809,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,25 +1840,27 @@ 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);
+        if (options?.bindings && options.bindings.length > 0) {
+            validateBindings(options.bindings);
         }
-        // Resolve the sidecar handle up front so every VM created here leases the
-        // one shared native sidecar process owned by that handle.
+        // Resolve the sidecar handle before starting an external sandbox so option
+        // validation failures cannot leak provider resources.
         const sidecar = resolveAgentOsSidecar(options?.sidecar);
+        options = await resolveSandboxOptions(options);
+        const sandboxDisposeHooks = getSandboxDisposeHooks(options);
+        const bindings = options.bindings;
         const createVmAdmin = async () => {
             // The `/opt/agentos` projection is built by the sidecar from the
             // 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 +1877,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 +1895,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 +1953,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 +1978,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 +2006,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,112 +2051,804 @@ 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._disposeHooks.push(...sandboxDisposeHooks);
             vm._installSidecarRequestHandler();
             vm._cronManager = new CronManager(vm, options?.scheduleDriver ?? new TimerScheduleDriver());
             return vm;
         }
         catch (error) {
-            await sidecarLease?.dispose().catch(() => { });
+            const cleanupErrors = [];
+            try {
+                await sidecarLease?.dispose();
+            }
+            catch (disposeError) {
+                cleanupErrors.push(disposeError);
+            }
+            const sandboxCleanupResults = await Promise.allSettled(sandboxDisposeHooks.map((hook) => hook()));
+            cleanupErrors.push(...sandboxCleanupResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []));
+            if (cleanupErrors.length > 0) {
+                throw new AggregateError([error, ...cleanupErrors], "AgentOS VM creation and cleanup failed");
+            }
+            throw error;
+        }
+    }
+    async createContext(contextId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "create_context", request: { contextId } });
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected createContext response: ${response.type}`);
+        }
+    }
+    async _executionOperation(payload, options, background = false) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+        }
+        let executionId;
+        const earlyOutput = [];
+        const completedBeforeAdmission = new Set();
+        let resolveCompletion;
+        const completion = new Promise((resolve) => {
+            resolveCompletion = resolve;
+        });
+        let warnedAboutEarlyEvents = false;
+        const warnAboutEarlyEvents = () => {
+            if (warnedAboutEarlyEvents)
+                return;
+            warnedAboutEarlyEvents = true;
+            console.warn("[agentos] execution admission received more than 1024 early events; use process.readOutput() to replay any omitted output");
+        };
+        const deliverOutput = (event) => {
+            if (event.channel === "stderr")
+                options.onStderr?.(event.chunk);
+            else
+                options.onStdout?.(event.chunk);
+        };
+        const unsubscribeOutput = this._onExecutionOutput("*", (event) => {
+            if (executionId === undefined) {
+                if (earlyOutput.length < 1_024)
+                    earlyOutput.push(event);
+                else
+                    warnAboutEarlyEvents();
+                return;
+            }
+            if (event.executionId === executionId)
+                deliverOutput(event);
+        });
+        let completed = false;
+        const unsubscribeCompleted = this._onExecutionCompleted("*", (event) => {
+            if (executionId === undefined) {
+                if (completedBeforeAdmission.size < 1_024) {
+                    completedBeforeAdmission.add(event.executionId);
+                }
+                else
+                    warnAboutEarlyEvents();
+                return;
+            }
+            if (event.executionId === executionId) {
+                completed = true;
+                resolveCompletion?.();
+            }
+        });
+        let response;
+        try {
+            response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, payload);
+        }
+        catch (error) {
+            unsubscribeOutput();
+            unsubscribeCompleted();
             throw error;
         }
+        if (response.type !== "execution_accepted") {
+            unsubscribeOutput();
+            unsubscribeCompleted();
+            throw new Error(`unexpected execution response: ${response.type}`);
+        }
+        const descriptor = response.response.execution;
+        executionId = response.response.operationId;
+        for (const event of earlyOutput) {
+            if (event.executionId === executionId)
+                deliverOutput(event);
+        }
+        completed = completedBeforeAdmission.has(executionId);
+        if (completed)
+            resolveCompletion?.();
+        const abort = () => {
+            // Admitted executions report cancellation through their structured result.
+            void this._cancelExecution(response.response.operationId).catch((error) => {
+                console.error("[agentos] failed to cancel aborted execution", error);
+            });
+        };
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        const cleanup = () => {
+            unsubscribeOutput();
+            unsubscribeCompleted();
+            options.signal?.removeEventListener("abort", abort);
+        };
+        if (background) {
+            if (!descriptor || descriptor.pid === null) {
+                cleanup();
+                throw new Error("spawned execution admission returned no process id");
+            }
+            if (completed)
+                cleanup();
+            else {
+                const unsubscribeBackgroundCompletion = this._onExecutionCompleted(descriptor.executionId, () => {
+                    unsubscribeBackgroundCompletion();
+                    cleanup();
+                });
+            }
+            return {
+                executionId: descriptor.executionId,
+                pid: descriptor.pid,
+                completed,
+                completion,
+                createdAtMs: safeProtocolNumber(descriptor.createdAtMs, "process startedAtMs"),
+            };
+        }
+        try {
+            await completion;
+            return await this._waitExecutionResult(response.response.operationId);
+        }
+        finally {
+            cleanup();
+        }
     }
+    async _spawnLanguageOperation(buildPayload, options, language) {
+        if ("contextId" in options) {
+            throw new Error("contextId is not supported for spawned processes; contexts are for attached operations");
+        }
+        const executionId = `process-${randomUUID()}`;
+        const internalOptions = {
+            ...options,
+            output: options.output,
+        };
+        const admitted = (await this._executionOperation(buildPayload(internalOptions, executionId), internalOptions, true));
+        const descriptor = {
+            pid: admitted.pid,
+            state: "running",
+            language,
+            startedAtMs: admitted.createdAtMs,
+        };
+        this._languageProcesses.set(admitted.pid, {
+            executionId: admitted.executionId,
+            descriptor,
+            outputHandlers: new Set(),
+            exitHandlers: new Set(),
+        });
+        this._languageProcessIds.set(admitted.executionId, admitted.pid);
+        const reconcileCompletion = async () => {
+            if (!this._languageProcesses.get(admitted.pid)?.exit) {
+                await this._waitProcess(admitted.pid);
+            }
+        };
+        if (admitted.completed)
+            await reconcileCompletion();
+        else {
+            void admitted.completion
+                .then(reconcileCompletion)
+                .catch((error) => console.error("[agentos] failed to reconcile spawned process completion", error));
+        }
+        if (options.signal) {
+            const abort = () => {
+                void this._killProcess(admitted.pid);
+            };
+            options.signal.addEventListener("abort", abort, { once: true });
+        }
+        return this._languageProcesses.get(admitted.pid)?.descriptor ?? descriptor;
+    }
+    async _exec(command, options = {}) {
+        return (await this._executionOperation({
+            type: "shell_execution",
+            request: { process: processExecutionOptions(options), command },
+        }, options));
+    }
+    async _execFile(command, args = [], options = {}) {
+        const operationOptions = { ...options, args: [...args] };
+        return (await this._executionOperation({
+            type: "argv_execution",
+            request: {
+                process: processExecutionOptions(operationOptions),
+                command,
+            },
+        }, operationOptions));
+    }
+    /** @deprecated Use `process.exec()` for lifecycle-aware execution. */
     async exec(command, options) {
         return this.#kernel.exec(command, options);
     }
+    /** @deprecated Use `process.execFile()` for lifecycle-aware execution. */
     async execArgv(command, args = [], options) {
         const kernel = this.#kernel;
         return kernel.execArgv(command, args, options);
     }
-    _trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers) {
-        const entry = {
-            proc,
-            command,
-            args,
-            stdoutHandlers,
-            stderrHandlers,
-            exitHandlers,
-        };
-        this._processes.set(proc.pid, entry);
-        // NOTE: do NOT delete from `_processes` on exit — the public API contract
-        // (getProcess/listProcesses/stopProcess, see process-management.test.ts)
-        // requires exited processes to stay queryable (running:false, exitCode set).
-        // `_processes` is a process table for this VM's lifetime; it is freed wholesale
-        // in dispose(). (H5: the leak was that dispose() never cleared it.)
-        void proc.wait().then((code) => {
-            for (const h of exitHandlers)
-                h(code);
-        });
-        return { pid: proc.pid };
+    async _executeJavaScript(source, options = {}) {
+        return (await this._executionOperation({
+            type: "javascript_execution",
+            request: {
+                process: processExecutionOptions(options),
+                source,
+                format: options.format === "commonjs"
+                    ? executionProtocol.JavaScriptModuleFormat.CommonJs
+                    : executionProtocol.JavaScriptModuleFormat.Module,
+                filePath: options.filePath ?? null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options));
     }
-    spawn(command, args, options) {
-        const stdoutHandlers = new Set();
-        const stderrHandlers = new Set();
-        const exitHandlers = new Set();
-        // Include caller-provided callbacks in the initial handler sets.
-        if (options?.onStdout)
-            stdoutHandlers.add(options.onStdout);
-        if (options?.onStderr)
-            stderrHandlers.add(options.onStderr);
-        const proc = this.#kernel.spawn(command, args, {
-            ...options,
-            onStdout: (data) => {
-                for (const h of stdoutHandlers)
-                    h(data);
+    async _evaluationOperation(payload, options) {
+        const result = (await this._executionOperation(payload, options));
+        if (result.outcome !== "succeeded")
+            return result;
+        const value = result.evaluationValue;
+        if (value === undefined) {
+            throw new Error("successful evaluation did not return a JSON-serializable value");
+        }
+        return { ...result, value: value };
+    }
+    async _evaluateJavaScript(expression, options = {}) {
+        return this._evaluationOperation({
+            type: "javascript_evaluation",
+            request: {
+                process: processExecutionOptions(options),
+                expression,
+                format: options.format === "commonjs"
+                    ? executionProtocol.JavaScriptModuleFormat.CommonJs
+                    : executionProtocol.JavaScriptModuleFormat.Module,
+                filePath: options.filePath ?? null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
             },
-            onStderr: (data) => {
-                for (const h of stderrHandlers)
-                    h(data);
+        }, options);
+    }
+    async _executeJavaScriptFile(path, options = {}) {
+        return (await this._executionOperation({
+            type: "javascript_file_execution",
+            request: { process: processExecutionOptions(options), path },
+        }, options));
+    }
+    _spawnJavaScript(source, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "javascript_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                source,
+                format: executionProtocol.JavaScriptModuleFormat.Module,
+                filePath: null,
+                inputs: null,
             },
-        });
-        return this._trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers);
-    }
-    /** Write data to a process's stdin. */
-    writeProcessStdin(pid, data) {
-        const entry = this._processes.get(pid);
-        if (!entry)
-            throw new Error(`Process not found: ${pid}`);
-        return entry.proc.writeStdin(data);
-    }
-    /** Close a process's stdin stream. */
-    closeProcessStdin(pid) {
-        const entry = this._processes.get(pid);
-        if (!entry)
-            throw new Error(`Process not found: ${pid}`);
-        return entry.proc.closeStdin();
+        }), options, "javascript");
+    }
+    _spawnJavaScriptFile(path, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "javascript_file_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                path,
+            },
+        }), options, "javascript");
+    }
+    async _executeTypeScript(source, options = {}) {
+        return (await this._executionOperation({
+            type: "typescript_execution",
+            request: {
+                process: processExecutionOptions(options),
+                source,
+                filePath: options.filePath ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options));
+    }
+    async _evaluateTypeScript(expression, options = {}) {
+        return this._evaluationOperation({
+            type: "typescript_evaluation",
+            request: {
+                process: processExecutionOptions(options),
+                expression,
+                filePath: options.filePath ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options);
+    }
+    async _executeTypeScriptFile(path, options = {}) {
+        return (await this._executionOperation({
+            type: "typescript_file_execution",
+            request: {
+                process: processExecutionOptions(options),
+                path,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+            },
+        }, options));
+    }
+    _spawnTypeScript(source, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "typescript_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                source,
+                filePath: null,
+                tsconfigPath: null,
+                compilerOptions: null,
+                inputs: null,
+            },
+        }), options, "javascript");
+    }
+    _spawnTypeScriptFile(path, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "typescript_file_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                path,
+                tsconfigPath: null,
+                compilerOptions: null,
+            },
+        }), options, "javascript");
+    }
+    async _checkTypeScript(source, options = {}) {
+        const result = (await this._executionOperation({
+            type: "typescript_check",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                source,
+                cwd: options.cwd ?? null,
+                filePath: options.filePath ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+            },
+        }, options));
+        return mapTypeScriptCheckResult(result);
+    }
+    async _checkTypeScriptProject(options = {}) {
+        const result = (await this._executionOperation({
+            type: "typescript_project_check",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                cwd: options.cwd ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+            },
+        }, options));
+        return mapTypeScriptCheckResult(result);
+    }
+    async _installNpmPackages(packagesOrOptions = {}, maybeOptions = {}) {
+        if (typeof packagesOrOptions === "string" ||
+            Array.isArray(packagesOrOptions)) {
+            const packages = Array.isArray(packagesOrOptions)
+                ? packagesOrOptions
+                : [packagesOrOptions];
+            return (await this._executionOperation({
+                type: "npm_package_install",
+                request: {
+                    identity: executionIdentity(maybeOptions),
+                    output: executionOutput(maybeOptions),
+                    cwd: maybeOptions.cwd ?? null,
+                    env: maybeOptions.env
+                        ? new Map(Object.entries(maybeOptions.env))
+                        : null,
+                    timeoutMs: protocolTimeout(maybeOptions.timeoutMs),
+                    packages,
+                    dev: maybeOptions.dev ?? null,
+                    global: maybeOptions.global ?? null,
+                },
+            }, maybeOptions));
+        }
+        const options = packagesOrOptions;
+        return (await this._executionOperation({
+            type: "npm_project_install",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                cwd: options.cwd ?? null,
+                env: options.env ? new Map(Object.entries(options.env)) : null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+                frozen: options.frozen ?? null,
+            },
+        }, options));
+    }
+    async _executeNpmScript(script, options = {}) {
+        return (await this._executionOperation({
+            type: "npm_script_execution",
+            request: { process: processExecutionOptions(options), script },
+        }, options));
+    }
+    async _executeNpmPackage(packageSpec, options = {}) {
+        return (await this._executionOperation({
+            type: "npm_package_execution",
+            request: {
+                process: processExecutionOptions(options),
+                packageSpec,
+                binary: options.binary ?? null,
+            },
+        }, options));
+    }
+    async _executePython(source, options = {}) {
+        return (await this._executionOperation({
+            type: "python_execution",
+            request: {
+                process: processExecutionOptions(options),
+                source,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options));
+    }
+    async _evaluatePython(expression, options = {}) {
+        return this._evaluationOperation({
+            type: "python_evaluation",
+            request: {
+                process: processExecutionOptions(options),
+                expression,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options);
+    }
+    async _executePythonFile(path, options = {}) {
+        return (await this._executionOperation({
+            type: "python_file_execution",
+            request: { process: processExecutionOptions(options), path },
+        }, options));
+    }
+    async _executePythonModule(module, options = {}) {
+        return (await this._executionOperation({
+            type: "python_module_execution",
+            request: { process: processExecutionOptions(options), module },
+        }, options));
+    }
+    _spawnPython(source, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "python_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                source,
+                inputs: null,
+            },
+        }), options, "python");
+    }
+    _spawnPythonFile(path, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "python_file_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                path,
+            },
+        }), options, "python");
+    }
+    _spawnPythonModule(module, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "python_module_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                module,
+            },
+        }), options, "python");
+    }
+    async _installPythonPackages(packagesOrOptions = {}, maybeOptions = {}) {
+        const packages = typeof packagesOrOptions === "string"
+            ? [packagesOrOptions]
+            : Array.isArray(packagesOrOptions)
+                ? packagesOrOptions
+                : [];
+        const options = typeof packagesOrOptions === "string" || Array.isArray(packagesOrOptions)
+            ? maybeOptions
+            : packagesOrOptions;
+        return (await this._executionOperation({
+            type: "python_install",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                cwd: options.cwd ?? null,
+                env: options.env ? new Map(Object.entries(options.env)) : null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+                packages,
+                upgrade: options.upgrade ?? null,
+                requirementsFile: options.requirementsFile ?? null,
+                indexUrl: options.indexUrl ?? null,
+                extraIndexUrls: options.extraIndexUrls ?? [],
+            },
+        }, options));
+    }
+    async _getContext(contextId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "get_execution", request: { executionId: contextId } });
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected getContext response: ${response.type}`);
+        }
+        return mapExecutionDescriptor(response.response.execution);
+    }
+    async _listContexts() {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "list_executions" });
+        if (response.type !== "execution_list") {
+            throw new Error(`unexpected listContexts response: ${response.type}`);
+        }
+        return response.response.executions.map(mapExecutionDescriptor);
+    }
+    async _waitExecutionResult(executionId) {
+        let resolveCompletion;
+        const completion = new Promise((resolve) => {
+            resolveCompletion = resolve;
+        });
+        const unsubscribe = this._onExecutionCompleted(executionId, () => {
+            resolveCompletion?.();
+        });
+        let response;
+        try {
+            try {
+                response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "wait_execution", request: { executionId } });
+            }
+            catch (error) {
+                if (!(error instanceof SidecarRejectedError) ||
+                    error.detail.code !== "execution_busy") {
+                    throw error;
+                }
+                await completion;
+                response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "wait_execution", request: { executionId } });
+            }
+        }
+        finally {
+            unsubscribe();
+        }
+        if (response.type !== "execution_completed") {
+            throw new Error(`unexpected waitExecution response: ${response.type}`);
+        }
+        return mapExecutionResult(response.response);
+    }
+    async _cancelExecution(executionId) {
+        await this._descriptorLifecycleRequest("cancel_execution", executionId);
+    }
+    async _signalExecution(executionId, signal) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "signal_execution", request: { executionId, signal } });
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected signalExecution response: ${response.type}`);
+        }
+    }
+    async _resetContext(contextId) {
+        await this._descriptorLifecycleRequest("reset_execution", contextId);
+    }
+    async _descriptorLifecycleRequest(type, executionId) {
+        const payload = type === "cancel_execution"
+            ? { type, request: { executionId } }
+            : { type, request: { executionId } };
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, payload);
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected ${type} response: ${response.type}`);
+        }
+        return mapExecutionDescriptor(response.response.execution);
+    }
+    async _deleteContext(contextId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "delete_execution", request: { executionId: contextId } });
+        if (response.type !== "execution_deleted") {
+            throw new Error(`unexpected deleteContext response: ${response.type}`);
+        }
+    }
+    async _writeExecutionStdin(executionId, data) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
+            type: "write_execution_stdin",
+            request: { executionId, chunk: executionBytes(data) },
+        });
+        if (response.type !== "execution_io") {
+            throw new Error(`unexpected writeExecutionStdin response: ${response.type}`);
+        }
+    }
+    async _closeExecutionStdin(executionId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "close_execution_stdin", request: { executionId } });
+        if (response.type !== "execution_io") {
+            throw new Error(`unexpected closeExecutionStdin response: ${response.type}`);
+        }
+    }
+    async _resizeExecutionPty(executionId, size) {
+        const cols = protocolUnsigned(size.cols, 0xffff, "size.cols");
+        const rows = protocolUnsigned(size.rows, 0xffff, "size.rows");
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
+            type: "resize_execution_pty",
+            request: { executionId, cols, rows },
+        });
+        if (response.type !== "execution_io") {
+            throw new Error(`unexpected resizeExecutionPty response: ${response.type}`);
+        }
+    }
+    async _readExecutionOutput(executionId, options = {}) {
+        const limit = options.limit === undefined
+            ? null
+            : protocolUnsigned(options.limit, 0xffff_ffff, "limit");
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
+            type: "read_execution_output",
+            request: {
+                executionId,
+                cursor: options.cursor ?? null,
+                limit,
+            },
+        });
+        if (response.type !== "execution_output_page") {
+            throw new Error(`unexpected readExecutionOutput response: ${response.type}`);
+        }
+        return {
+            events: response.response.events.map(mapExecutionOutputEvent),
+            nextCursor: response.response.nextCursor,
+            hasMore: response.response.hasMore,
+            truncated: response.response.truncated,
+        };
+    }
+    _onExecutionOutput(executionId, handler) {
+        const handlers = this._executionOutputHandlers.get(executionId) ?? new Set();
+        handlers.add(handler);
+        this._executionOutputHandlers.set(executionId, handlers);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this._executionOutputHandlers.delete(executionId);
+        };
+    }
+    _onExecutionCompleted(executionId, handler) {
+        const handlers = this._executionCompletedHandlers.get(executionId) ?? new Set();
+        handlers.add(handler);
+        this._executionCompletedHandlers.set(executionId, handlers);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this._executionCompletedHandlers.delete(executionId);
+        };
+    }
+    _trackProcess(proc, command, args, retainEvents, outputHandlers, exitHandlers) {
+        const entry = {
+            proc,
+            command,
+            args,
+            startedAtMs: Date.now(),
+            retainEvents,
+            events: [],
+            nextSequence: 0,
+            signal: undefined,
+            exit: undefined,
+            outputHandlers,
+            exitHandlers,
+        };
+        this._processes.set(proc.pid, entry);
+        // NOTE: do NOT delete from `_processes` on exit — the public API contract
+        // (getProcess/listProcesses/stopProcess, see process-management.test.ts)
+        // requires exited processes to stay queryable (running:false, exitCode set).
+        // `_processes` is a process table for this VM's lifetime; it is freed wholesale
+        // in dispose(). (H5: the leak was that dispose() never cleared it.)
+        void proc.wait().then((code) => {
+            const exit = {
+                pid: proc.pid,
+                outcome: entry.signal ? "signalled" : "exited",
+                exitCode: code,
+                ...(entry.signal ? { signal: entry.signal } : {}),
+            };
+            entry.exit = exit;
+            for (const h of exitHandlers)
+                h(exit);
+        });
+        return {
+            pid: proc.pid,
+            state: "running",
+            command,
+            startedAtMs: entry.startedAtMs,
+        };
+    }
+    async _spawnProcess(command, args = [], options = {}) {
+        const outputHandlers = new Set();
+        const exitHandlers = new Set();
+        const recordOutput = (channel, data) => {
+            const entry = this._processes.get(proc.pid);
+            if (!entry?.retainEvents)
+                return;
+            if (entry.events.length >= PROCESS_OUTPUT_EVENT_LIMIT) {
+                entry.events.shift();
+            }
+            entry.events.push({
+                pid: proc.pid,
+                sequence: entry.nextSequence++,
+                channel,
+                chunk: data,
+                timestampMs: Date.now(),
+            });
+        };
+        const proc = this.#kernel.spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdin: options.stdin,
+            timeout: options.timeoutMs,
+            streamStdin: true,
+            onStdout: (data) => {
+                recordOutput("stdout", data);
+                options?.onStdout?.(data);
+                for (const h of outputHandlers) {
+                    h({ pid: proc.pid, stream: "stdout", data });
+                }
+            },
+            onStderr: (data) => {
+                recordOutput("stderr", data);
+                options?.onStderr?.(data);
+                for (const h of outputHandlers) {
+                    h({ pid: proc.pid, stream: "stderr", data });
+                }
+            },
+        });
+        return this._trackProcess(proc, command, args, options.output?.retainEvents ?? false, outputHandlers, exitHandlers);
+    }
+    spawn(command, args = [], options) {
+        return this.process.spawn(command, args, options);
     }
-    /** Subscribe to stdout data from a process. Returns an unsubscribe function. */
-    onProcessStdout(pid, handler) {
+    /** Write data to a process's stdin. */
+    _writeProcessStdin(pid, data) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            return this._writeExecutionStdin(language.executionId, data);
+        }
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.stdoutHandlers.add(handler);
-        return () => {
-            entry.stdoutHandlers.delete(handler);
-        };
+        return entry.proc.writeStdin(data);
     }
-    /** Subscribe to stderr data from a process. Returns an unsubscribe function. */
-    onProcessStderr(pid, handler) {
+    /** Close a process's stdin stream. */
+    _closeProcessStdin(pid) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            return this._closeExecutionStdin(language.executionId);
+        }
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.stderrHandlers.add(handler);
+        return entry.proc.closeStdin();
+    }
+    /** Subscribe to stdout and stderr from a process. */
+    onProcessOutput(pid, handler) {
+        const entry = this._processes.get(pid) ?? this._languageProcesses.get(pid);
+        if (!entry)
+            throw new Error(`Process not found: ${pid}`);
+        entry.outputHandlers.add(handler);
         return () => {
-            entry.stderrHandlers.delete(handler);
+            entry.outputHandlers.delete(handler);
         };
     }
     /** Subscribe to process exit. Returns an unsubscribe function. */
     onProcessExit(pid, handler) {
-        const entry = this._processes.get(pid);
+        const entry = this._processes.get(pid) ?? this._languageProcesses.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
         // If already exited, call immediately.
-        if (entry.proc.exitCode !== null) {
-            handler(entry.proc.exitCode);
+        if ("exit" in entry && entry.exit) {
+            handler(entry.exit);
             return () => { };
         }
         entry.exitHandlers.add(handler);
@@ -1787,11 +2857,39 @@ export class AgentOs {
         };
     }
     /** Wait for a process to exit. Returns the exit code. */
-    waitProcess(pid) {
+    async _waitProcess(pid) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            if (language.exit)
+                return language.exit;
+            const result = await this._waitExecutionResult(language.executionId);
+            const exit = {
+                pid,
+                outcome: result.outcome === "timed_out"
+                    ? "timed_out"
+                    : result.outcome === "cancelled"
+                        ? "signalled"
+                        : "exited",
+                ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
+                ...(language.signal ? { signal: language.signal } : {}),
+            };
+            language.exit = exit;
+            language.descriptor = { ...language.descriptor, state: "exited" };
+            for (const handler of language.exitHandlers)
+                handler(exit);
+            return exit;
+        }
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        return entry.proc.wait();
+        if (entry.exit)
+            return entry.exit;
+        const exitCode = await entry.proc.wait();
+        return (entry.exit ?? {
+            pid,
+            outcome: "exited",
+            exitCode,
+        });
     }
     _assertSafeAbsolutePath(path) {
         if (!path.startsWith("/")) {
@@ -1810,15 +2908,15 @@ export class AgentOs {
     _vfs() {
         return this.#kernel.vfs;
     }
-    async readFile(path) {
+    async _readFile(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readFile(path);
     }
-    async writeFile(path, content) {
+    async _writeFile(path, content) {
         this._assertWritableAbsolutePath(path);
         return this.#kernel.writeFile(path, content);
     }
-    async writeFiles(entries) {
+    async _writeFiles(entries) {
         const results = [];
         for (const entry of entries) {
             try {
@@ -1841,7 +2939,7 @@ export class AgentOs {
         }
         return results;
     }
-    async readFiles(paths) {
+    async _readFiles(paths) {
         const results = [];
         for (const path of paths) {
             try {
@@ -1870,18 +2968,27 @@ export class AgentOs {
         // exists() loop makes `mkdir -p` cost O(components * tree).
         await this.#kernel.mkdir(path);
     }
-    async mkdir(path, options) {
+    async _mkdir(path, options) {
         if (options?.recursive) {
             return this._mkdirp(path);
         }
         this._assertSafeAbsolutePath(path);
         return this.#kernel.mkdir(path);
     }
-    async readdir(path) {
+    async _readdir(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readdir(path);
     }
-    async readdirRecursive(path, options) {
+    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;
         const entries = await this.#kernel.readdirRecursive(path, {
@@ -1911,20 +3018,27 @@ export class AgentOs {
         }
         return results;
     }
-    async stat(path) {
+    async _stat(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.stat(path);
     }
-    async exists(path) {
+    async _exists(path) {
         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,25 +3046,144 @@ 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) {
+    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 move(from, to) {
+    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,
         });
     }
+    /** @deprecated Use `filesystem.readFile()`. */
+    readFile(path) {
+        return this.filesystem.readFile(path);
+    }
+    /** @deprecated Use `filesystem.writeFile()`. */
+    writeFile(path, content) {
+        return this.filesystem.writeFile(path, content);
+    }
+    /** @deprecated Use `filesystem.writeFiles()`. */
+    writeFiles(entries) {
+        return this.filesystem.writeFiles(entries);
+    }
+    /** @deprecated Use `filesystem.readFiles()`. */
+    readFiles(paths) {
+        return this.filesystem.readFiles(paths);
+    }
+    /** @deprecated Use `filesystem.mkdir()`. */
+    mkdir(path, options) {
+        return this.filesystem.mkdir(path, options);
+    }
+    /** @deprecated Use `filesystem.readdir()`. */
+    readdir(path) {
+        return this.filesystem.readdir(path);
+    }
+    /** @deprecated Use `filesystem.readdirEntries()`. */
+    readdirEntries(path) {
+        return this.filesystem.readdirEntries(path);
+    }
+    /** @deprecated Use `filesystem.readdirRecursive()`. */
+    readdirRecursive(path, options) {
+        return this.filesystem.readdirRecursive(path, options);
+    }
+    /** @deprecated Use `filesystem.stat()`. */
+    stat(path) {
+        return this.filesystem.stat(path);
+    }
+    /** @deprecated Use `filesystem.exists()`. */
+    exists(path) {
+        return this.filesystem.exists(path);
+    }
+    /** @deprecated Use `filesystem.export()`. */
+    exportRootFilesystem(options) {
+        return this.filesystem.export(options);
+    }
+    /** @deprecated Use `filesystem.mount()`. */
+    mountFs(descriptor) {
+        return this.filesystem.mount(descriptor);
+    }
+    /** @deprecated Use `filesystem.unmount()`. */
+    unmountFs(path) {
+        return this.filesystem.unmount(path);
+    }
+    /** @deprecated Use `filesystem.listMounts()`. */
+    listMounts() {
+        return this.filesystem.listMounts();
+    }
+    /** @deprecated Use `filesystem.move()`. */
+    move(from, to) {
+        return this.filesystem.move(from, to);
+    }
+    /** @deprecated Use `filesystem.remove()`. */
+    remove(path, options) {
+        return this.filesystem.remove(path, options);
+    }
+    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: request.port,
+            method,
+            path: request.path,
+            headersJson: JSON.stringify(request.headers ?? {}),
+            ...(method !== "GET" && method !== "HEAD" && body !== undefined
+                ? { body }
+                : {}),
+        }));
+        const headers = {};
+        for (const [key, value] of responsePayload.headers ?? []) {
+            headers[key] = value;
+        }
+        return {
+            status: responsePayload.status,
+            statusText: responsePayload.statusText ?? "",
+            headers,
+            body: new Uint8Array(Buffer.from(responsePayload.body ?? "", "base64")),
+        };
+    }
+    /** @deprecated Use `network.httpRequest()`. */
+    httpRequest(request) {
+        return this.network.httpRequest(request);
+    }
+    /**
+     * Fetch an HTTP endpoint inside the VM while preserving duplicate response
+     * headers and arbitrary binary bodies. agentOS Apps uses this compatibility
+     * surface for its direct actor API.
+     */
     async fetch(port, request) {
         const url = new URL(request.url);
         const responsePayload = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
@@ -1959,7 +3192,9 @@ export class AgentOs {
             path: `${url.pathname}${url.search}`,
             headersJson: JSON.stringify(Object.fromEntries(request.headers.entries())),
             ...(request.method !== "GET" && request.method !== "HEAD"
-                ? { body: await request.text() }
+                ? {
+                    bodyBase64: Buffer.from(await request.arrayBuffer()).toString("base64"),
+                }
                 : {}),
         }));
         const headers = new Headers();
@@ -1968,22 +3203,72 @@ export class AgentOs {
         }
         return new Response(Buffer.from(responsePayload.body ?? "", "base64"), {
             status: responsePayload.status,
-            statusText: responsePayload.statusText,
+            statusText: responsePayload.statusText ?? "",
             headers,
         });
     }
-    openShell(options) {
+    async fetchStreamStart(port, request) {
+        const url = new URL(request.url);
+        return 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"
+                ? {
+                    bodyBase64: Buffer.from(await request.arrayBuffer()).toString("base64"),
+                }
+                : {}),
+            streamOperation: "start",
+        }));
+    }
+    async fetchStreamRead(streamId, maxBytes = 64 * 1024) {
+        const response = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
+            port: 0,
+            method: "GET",
+            path: "/",
+            headersJson: "{}",
+            streamOperation: "read",
+            streamId,
+            maxBytes,
+        }));
+        return {
+            body: new Uint8Array(Buffer.from(response.body, "base64")),
+            done: response.done,
+        };
+    }
+    async fetchStreamCancel(streamId) {
+        await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
+            port: 0,
+            method: "GET",
+            path: "/",
+            headersJson: "{}",
+            streamOperation: "cancel",
+            streamId,
+        });
+    }
+    _openTerminal(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 +3283,8 @@ export class AgentOs {
         };
         entry.exitPromise = exitPromise.then((exitCode) => {
             finalize(exitCode);
+            for (const handler of exitHandlers)
+                handler({ shellId, exitCode });
             return exitCode;
         }, (error) => {
             finalize();
@@ -2011,13 +3298,17 @@ export class AgentOs {
         return this.#kernel.connectTerminal(options);
     }
     /** Write data to a shell's PTY input. */
-    writeShell(shellId, data) {
+    _writeTerminal(shellId, data) {
         const entry = this._shells.get(shellId);
         if (!entry)
             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,8 +3318,30 @@ 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) {
+    _resizeTerminal(shellId, cols, rows) {
         const entry = this._shells.get(shellId);
         if (!entry)
             throw new Error(`Shell not found: ${shellId}`);
@@ -2039,7 +3352,7 @@ export class AgentOs {
      * immediately for a shell that has already exited (within the closed-shell
      * retention window).
      */
-    waitShell(shellId) {
+    _waitTerminal(shellId) {
         const entry = this._shells.get(shellId);
         if (!entry) {
             const exitCode = this._closedShellIds.get(shellId);
@@ -2050,7 +3363,7 @@ export class AgentOs {
         return entry.exitPromise;
     }
     /** Kill a shell process and remove it from tracking. */
-    closeShell(shellId) {
+    _closeTerminal(shellId) {
         const entry = this._shells.get(shellId);
         if (!entry) {
             if (this._closedShellIds.has(shellId)) {
@@ -2062,6 +3375,26 @@ export class AgentOs {
         this._shells.delete(shellId);
         this._closedShellIds.add(shellId);
     }
+    /** @deprecated Use `terminal.open()`. */
+    openShell(options) {
+        return this.terminal.open(options);
+    }
+    /** @deprecated Use `terminal.write()`. */
+    writeShell(shellId, data) {
+        return this.terminal.write(shellId, data);
+    }
+    /** @deprecated Use `terminal.resize()`. */
+    resizeShell(shellId, cols, rows) {
+        this.terminal.resize(shellId, cols, rows);
+    }
+    /** @deprecated Use `terminal.wait()`. */
+    waitShell(shellId) {
+        return this.terminal.wait(shellId);
+    }
+    /** @deprecated Use `terminal.close()`. */
+    closeShell(shellId) {
+        this.terminal.close(shellId);
+    }
     _resolveVmPathToHostPath(vmPath) {
         const normalizedVmPath = posixPath.normalize(vmPath);
         for (const mount of this._hostMounts) {
@@ -2077,34 +3410,51 @@ export class AgentOs {
         return null;
     }
     /** Returns info about all processes spawned via spawn(). */
-    listProcesses() {
-        return [...this._processes.values()].map(({ proc, command, args }) => ({
-            pid: proc.pid,
-            command,
-            args,
-            running: proc.exitCode === null,
-            exitCode: proc.exitCode,
-        }));
+    async _listProcesses() {
+        return [
+            ...[...this._processes.values()].map(({ proc, command, startedAtMs }) => ({
+                pid: proc.pid,
+                command,
+                state: proc.exitCode === null ? "running" : "exited",
+                startedAtMs,
+            })),
+            ...[...this._languageProcesses.values()].map((entry) => entry.descriptor),
+        ];
     }
     /** Returns all kernel processes across all active runtimes (WASM and Node). */
-    allProcesses() {
+    _listAllProcesses() {
         if (this.#kernel instanceof NativeSidecarKernelProxy) {
             return this.#kernel.snapshotProcesses();
         }
         return [...this.#kernel.processes.values()];
     }
     /** Returns processes organized as a tree using ppid relationships. */
-    processTree() {
-        const all = this.allProcesses();
+    async _processTree() {
+        const all = this._listAllProcesses();
         const nodeMap = new Map();
         // Index: create a tree node for each process
         for (const proc of all) {
-            nodeMap.set(proc.pid, { ...proc, children: [] });
+            nodeMap.set(proc.pid, {
+                pid: proc.pid,
+                ppid: proc.ppid,
+                command: proc.command,
+                state: proc.status,
+                startedAtMs: proc.startTime,
+                children: [],
+            });
+        }
+        for (const process of this._languageProcesses.values()) {
+            if (!nodeMap.has(process.descriptor.pid)) {
+                nodeMap.set(process.descriptor.pid, {
+                    ...process.descriptor,
+                    children: [],
+                });
+            }
         }
         // Wire: attach each node to its parent
         const roots = [];
         for (const node of nodeMap.values()) {
-            const parent = nodeMap.get(node.ppid);
+            const parent = node.ppid === undefined ? undefined : nodeMap.get(node.ppid);
             if (parent) {
                 parent.children.push(node);
             }
@@ -2115,7 +3465,10 @@ export class AgentOs {
         return roots;
     }
     /** Returns info about a specific process by PID. Throws if not found. */
-    getProcess(pid) {
+    async _getProcess(pid) {
+        const language = this._languageProcesses.get(pid);
+        if (language)
+            return language.descriptor;
         const entry = this._processes.get(pid);
         if (!entry) {
             throw new Error(`Process not found: ${pid}`);
@@ -2123,64 +3476,337 @@ export class AgentOs {
         return {
             pid: entry.proc.pid,
             command: entry.command,
-            args: entry.args,
-            running: entry.proc.exitCode === null,
-            exitCode: entry.proc.exitCode,
+            state: entry.proc.exitCode === null ? "running" : "exited",
+            startedAtMs: entry.startedAtMs,
         };
     }
-    /** Send SIGTERM to gracefully stop a process. No-op if already exited. */
-    stopProcess(pid) {
+    async _signalProcess(pid, signal) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            language.signal = signal;
+            await this._signalExecution(language.executionId, signal);
+            return;
+        }
         const entry = this._processes.get(pid);
         if (!entry) {
             throw new Error(`Process not found: ${pid}`);
         }
         if (entry.proc.exitCode !== null)
             return;
-        entry.proc.kill();
+        entry.signal = signal;
+        const number = signal === "SIGKILL" ? 9 : signal === "SIGINT" ? 2 : 15;
+        entry.proc.kill(number);
     }
     /** Send SIGKILL to force-kill a process. No-op if already exited. */
-    killProcess(pid) {
+    async _killProcess(pid) {
+        await this._signalProcess(pid, "SIGKILL");
+    }
+    async _resizeProcessPty(pid, size) {
+        const language = this._languageProcesses.get(pid);
+        if (!language) {
+            throw new Error(`Process ${pid} does not have a managed PTY`);
+        }
+        await this._resizeExecutionPty(language.executionId, size);
+    }
+    async _readProcessOutput(pid, options = {}) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            const page = await this._readExecutionOutput(language.executionId, {
+                cursor: options.after === undefined ? undefined : `1:${options.after + 1}`,
+            });
+            return {
+                pid,
+                events: page.events.map((event) => ({
+                    pid,
+                    sequence: event.sequence,
+                    channel: event.channel,
+                    chunk: event.chunk,
+                    timestampMs: event.timestampMs,
+                })),
+                nextCursor: page.nextCursor,
+                hasMore: page.hasMore,
+                truncated: page.truncated,
+            };
+        }
         const entry = this._processes.get(pid);
-        if (!entry) {
+        if (!entry)
             throw new Error(`Process not found: ${pid}`);
+        if (!entry.retainEvents) {
+            throw new Error(`Process ${pid} was not spawned with output.retainEvents enabled`);
         }
-        if (entry.proc.exitCode !== null)
-            return;
-        entry.proc.kill(9);
+        const after = options.after ?? -1;
+        const events = entry.events.filter((event) => event.sequence > after);
+        return {
+            pid,
+            events,
+            nextCursor: String(events.at(-1)?.sequence ?? after),
+            hasMore: false,
+            truncated: entry.events.length === PROCESS_OUTPUT_EVENT_LIMIT &&
+                after < (entry.events[0]?.sequence ?? 0) - 1,
+        };
     }
-    /** 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 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}`);
         }
-        return session;
+    }
+    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);
+    }
+    /** @deprecated Use `sessions.open()`. */
+    openSession(input) {
+        return this.sessions.open(input);
+    }
+    /** @deprecated Use `sessions.get()`. */
+    getSession(input) {
+        return this.sessions.get(input);
+    }
+    /** @deprecated Use `sessions.list()`. */
+    listSessions(input) {
+        return this.sessions.list(input);
+    }
+    /** @deprecated Use `sessions.delete()`. */
+    deleteSession(input = {}) {
+        return this.sessions.delete(input);
+    }
+    /** @deprecated Use `sessions.unload()`. */
+    unloadSession(input) {
+        return this.sessions.unload(input);
+    }
+    /** @deprecated Use `sessions.prompt()`. */
+    prompt(input) {
+        return this.sessions.prompt(input);
+    }
+    /** @deprecated Use `sessions.cancelPrompt()`. */
+    cancelPrompt(input) {
+        return this.sessions.cancelPrompt(input);
+    }
+    /** @deprecated Use `sessions.respondPermission()`. */
+    respondPermission(input) {
+        return this.sessions.respondPermission(input);
+    }
+    /** @deprecated Use `sessions.readHistory()`. */
+    readHistory(input) {
+        return this.sessions.readHistory(input);
+    }
+    /** @deprecated Use `sessions.getConfig()`. */
+    getSessionConfig(input) {
+        return this.sessions.getConfig(input);
+    }
+    /** @deprecated Use `sessions.setConfigOption()`. */
+    setSessionConfigOption(input) {
+        return this.sessions.setConfigOption(input);
+    }
+    /** @deprecated Use `sessions.getCapabilities()`. */
+    getSessionCapabilities(input) {
+        return this.sessions.getCapabilities(input);
+    }
+    /** @deprecated Use `sessions.getAgentInfo()`. */
+    getSessionAgentInfo(input) {
+        return this.sessions.getAgentInfo(input);
     }
     /**
      * 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");
-        }
+    async _linkSoftware(descriptor) {
         // 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 +3815,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);
     }
     /**
@@ -2204,7 +3830,7 @@ export class AgentOs {
      * projected `/opt/agentos` packages (the client parses no manifests). Every such
      * agent is a package materialized into the VM, so `installed` is always `true`.
      */
-    async listAgents() {
+    async _listAgents() {
         const response = await this._sendAcpRequest({
             tag: "AcpListAgentsRequest",
             val: { reserved: false },
@@ -2215,201 +3841,148 @@ 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.
-            }
-        }
+    /** @deprecated Use `software.link()`. */
+    linkSoftware(descriptor) {
+        return this.software.link(descriptor);
     }
-    _subscribeSessionEvents(session, handler) {
-        const subscriber = {
-            handler,
-        };
-        session.eventHandlers.add(subscriber);
-        return () => {
-            session.eventHandlers.delete(subscriber);
-        };
+    /** @deprecated Use `software.list()`. */
+    listSoftware() {
+        return this.software.list();
     }
-    /**
-     * 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.
-        }
+    /** @deprecated Use `agents.list()`. */
+    listAgents() {
+        return this.agents.list();
     }
     _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) {
-            return;
-        }
-        const handler = this._agentStderrHandler;
-        if (!handler) {
+        if (!event.sessionId) {
             return;
         }
-        try {
-            handler({
-                sessionId,
-                agentType: event.agentType || session?.agentType || "",
-                processId: event.processId,
-                pid: session?.pid ?? null,
-                chunk: new Uint8Array(event.chunk),
-            });
-        }
-        catch {
-            // Ignore subscriber callback failures and keep event delivery moving.
-        }
-    }
-    _recordAgentExit(event) {
-        const session = this._sessions.get(event.sessionId);
-        const handler = this._agentExitHandler;
+        const handler = this._agentStderrHandler;
         if (!handler) {
             return;
         }
         try {
             handler({
                 sessionId: event.sessionId,
-                agentType: event.agentType || session?.agentType || "",
+                agentType: event.agentType,
                 processId: event.processId,
-                pid: session?.pid ?? null,
-                exitCode: event.exitCode,
-                restart: event.restart,
-                restartCount: event.restartCount,
-                maxRestarts: event.maxRestarts,
+                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);
         }
     }
-    _applySyntheticConfigOverrides(session) {
-        if (session.configOverrides.size === 0) {
-            return;
+    _recordAgentExit(event) {
+        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) {
+            try {
+                handler(publicEvent);
+            }
+            catch (error) {
+                console.error("AgentOS agent-exit handler failed", error);
+            }
+        }
+        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 === "execution_output") {
+            const output = mapExecutionOutputEvent(event.payload.event);
+            const pid = this._languageProcessIds.get(output.executionId);
+            if (pid !== undefined) {
+                const process = this._languageProcesses.get(pid);
+                if (process) {
+                    const publicOutput = {
+                        pid,
+                        stream: output.channel === "stderr" ? "stderr" : "stdout",
+                        data: output.chunk,
+                    };
+                    for (const handler of process.outputHandlers) {
+                        try {
+                            handler(publicOutput);
+                        }
+                        catch (error) {
+                            console.error("AgentOS process output handler failed", error);
+                        }
+                    }
+                }
+            }
+            for (const key of ["*", output.executionId]) {
+                for (const handler of this._executionOutputHandlers.get(key) ?? []) {
+                    try {
+                        handler(output);
+                    }
+                    catch (error) {
+                        console.error("AgentOS execution output handler failed", error);
+                    }
+                }
+            }
+            return;
+        }
+        if (event.payload.type === "execution_completed") {
+            const completed = mapExecutionCompletedEvent(event.payload.event);
+            const pid = this._languageProcessIds.get(completed.executionId);
+            if (pid !== undefined) {
+                const process = this._languageProcesses.get(pid);
+                if (process && !process.exit) {
+                    const exit = {
+                        pid,
+                        outcome: completed.outcome === "timed_out"
+                            ? "timed_out"
+                            : completed.outcome === "cancelled"
+                                ? "signalled"
+                                : "exited",
+                        ...(completed.exitCode !== undefined
+                            ? { exitCode: completed.exitCode }
+                            : {}),
+                        ...(process.signal ? { signal: process.signal } : {}),
+                    };
+                    process.exit = exit;
+                    process.descriptor = { ...process.descriptor, state: "exited" };
+                    for (const handler of process.exitHandlers) {
+                        try {
+                            handler(exit);
+                        }
+                        catch (error) {
+                            console.error("AgentOS process exit handler failed", error);
+                        }
+                    }
+                }
+            }
+            for (const key of ["*", completed.executionId]) {
+                for (const handler of this._executionCompletedHandlers.get(key) ?? []) {
+                    try {
+                        handler(completed);
+                    }
+                    catch (error) {
+                        console.error("AgentOS execution completion handler failed", error);
+                    }
+                }
+            }
+            return;
+        }
         if (event.payload.type === "ext") {
             this._handleAcpExtEvent(event.payload.envelope);
             return;
@@ -2419,25 +3992,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 +4011,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 +4022,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 +4050,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 +4080,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 +4112,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 +4163,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 +4195,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 +4367,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,
@@ -3230,12 +4384,12 @@ export class AgentOs {
         this._acpTerminals.set(terminalId, terminal);
         return { terminalId };
     }
-    _handleAcpWriteTerminal(params) {
+    async _handleAcpWriteTerminal(params) {
         const method = "terminal/write";
         const terminal = this._requireAcpTerminal(params, method);
         const data = this._requireAcpStringParam(params, "data", method);
         const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        terminal.handle.write(encoding === "base64" ? Buffer.from(data, "base64") : data);
+        await terminal.handle.write(encoding === "base64" ? Buffer.from(data, "base64") : data);
         return null;
     }
     _handleAcpReadTerminal(params) {
@@ -3289,217 +4443,71 @@ 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 ────────────────────────────────────────────────────
     /** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
-    scheduleCron(options) {
+    _scheduleCron(options) {
         return this._cronManager.schedule(options);
     }
     /** List all registered cron jobs. */
-    listCronJobs() {
+    _listCronJobs() {
         return this._cronManager.list();
     }
     /** Cancel a cron job by ID. */
-    cancelCronJob(id) {
+    _cancelCronJob(id) {
         this._cronManager.cancel(id);
     }
+    /** @deprecated Use `cron.schedule()`. */
+    scheduleCron(options) {
+        return this.cron.schedule(options);
+    }
+    /** @deprecated Use `cron.list()`. */
+    listCronJobs() {
+        return this.cron.list();
+    }
+    /** @deprecated Use `cron.cancel()`. */
+    cancelCronJob(id) {
+        this.cron.cancel(id);
+    }
     /** Subscribe to cron lifecycle events (fire, complete, error). */
     onCronEvent(handler) {
         this._cronManager.onEvent(handler);
     }
     async dispose() {
         this._cronManager.dispose();
-        for (const sessionId of [...this._sessions.keys()]) {
-            await this._closeSessionInternal(sessionId).catch(() => { });
-        }
         for (const [id, entry] of this._shells) {
             entry.handle.kill();
         }
@@ -3512,14 +4520,30 @@ export class AgentOs {
         }
         this._acpTerminals.clear();
         this._processes.clear();
+        this._executionOutputHandlers.clear();
+        this._executionCompletedHandlers.clear();
         await waitForTrackedExitPromises([...shellExitPromises, ...terminalExitPromises], SHELL_DISPOSE_TIMEOUT_MS);
         this._disposeSidecarEventListener();
         const sidecarLease = this._sidecarLease;
         this._sidecarLease = null;
-        if (sidecarLease) {
-            return sidecarLease.dispose();
+        const disposeVm = sidecarLease
+            ? sidecarLease.dispose()
+            : this.#kernel.dispose();
+        const hooks = this._disposeHooks.splice(0);
+        const errors = [];
+        try {
+            await disposeVm;
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        const hookResults = await Promise.allSettled(hooks.map((hook) => hook()));
+        errors.push(...hookResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []));
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, "AgentOS VM disposal failed");
         }
-        return this.#kernel.dispose();
     }
 }
 const agentOsRuntimeAdmins = new WeakMap();
@@ -3583,7 +4607,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 +4824,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 +4844,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();