@rivet-dev/agentos-core 0.0.0-nathan-binding-workspace.dd41c31 → 0.0.0-nathan-binding-workspace.806210d

package/dist/{agentos.js → agent-os.js}

@@ -4,14 +4,22 @@ import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, w
 import { tmpdir } from "node:os";
 import { dirname, join, posix as posixPath, resolve as resolveHostPath, } from "node:path";
 import { fileURLToPath } from "node:url";
-import { validateBindings } from "./bindings.js";
-import { zodToJsonSchema } from "./bindings-zod.js";
+import { validateToolkits } from "./host-tools.js";
+import { zodToJsonSchema } from "./host-tools-zod.js";
 import { resolvePublishedSidecarBinary } from "./sidecar/binary.js";
 import { findCargoBinary, resolveCargoBinary } from "./sidecar/cargo.js";
 export { isAcpTimeoutErrorData } from "./json-rpc.js";
 const ACP_PROTOCOL_VERSION = 1;
-const ACP_EXTENSION_NAMESPACE = "dev.rivet.agentos.acp";
+const ACP_EXTENSION_NAMESPACE = "dev.rivet.agent-os.acp";
 const SHELL_DISPOSE_TIMEOUT_MS = 5_000;
+/**
+ * Reserved `env` key on `AcpResumeSessionRequest` carrying the resolved adapter
+ * bin entrypoint. The resume wire request omits a dedicated `adapterEntrypoint`
+ * field; the sidecar reads the entrypoint from this key and strips it before
+ * launching the adapter. Must stay in sync with the sidecar constant of the same
+ * name in `crates/agentos-sidecar/src/acp_extension.rs`.
+ */
+const RESUME_ADAPTER_ENTRYPOINT_ENV = "AGENT_OS_RESUME_ADAPTER_ENTRYPOINT";
 function defaultAcpClientCapabilities() {
     return {
         fs: {
@@ -41,15 +49,10 @@ import { createHostDirBackend } from "./host-dir-mount.js";
 import { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
 import { processSoftware, resolvePackageDir, } from "./packages.js";
-// `@agentos-software/common` (coreutils, sed, grep, gawk, findutils, diffutils,
-// tar, gzip) is part of the default VM software set, so callers never have to add
-// it explicitly. It is prepended to any user-supplied `software` (deduped by
-// reference, so passing it explicitly is still harmless).
-import defaultCommonSoftware from "@agentos-software/common";
 import { allowAll } from "./runtime-compat.js";
 import { AcpRuntimeKind, decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
 import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
-import { createAgentOSSidecarClient, NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarKernelProxy, NativeSidecarProcessClient, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
+import { createAgentOsSidecarClient, NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
 const LEGACY_PERMISSION_METHOD = "request/permission";
 const ACP_PERMISSION_METHOD = "session/request_permission";
 class AcpDispatchError extends Error {
@@ -364,7 +367,6 @@ const KERNEL_POSIX_BOOTSTRAP_DIRS = [
     "/media",
     "/home",
     "/home/user",
-    "/workspace",
     "/usr",
     "/usr/bin",
     "/usr/games",
@@ -832,19 +834,19 @@ function collectSidecarMountPlan(options) {
     hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
     return { sidecarMounts, hostMounts, hostPathMappings };
 }
-function materializeToolShimDir(bindingGroups) {
-    const shimDir = mkdtempSync(join(tmpdir(), "agentos-bindings-shims-"));
+function materializeToolShimDir(toolKits) {
+    const shimDir = mkdtempSync(join(tmpdir(), "agentos-host-tools-shims-"));
     writeFileSync(join(shimDir, "agentos"), KERNEL_COMMAND_STUB, { mode: 0o755 });
-    for (const group of bindingGroups) {
-        writeFileSync(join(shimDir, `agentos-${group.name}`), KERNEL_COMMAND_STUB, { mode: 0o755 });
+    for (const toolKit of toolKits) {
+        writeFileSync(join(shimDir, `agentos-${toolKit.name}`), KERNEL_COMMAND_STUB, { mode: 0o755 });
     }
     return shimDir;
 }
-function collectToolkitBootstrapCommands(bindingGroups) {
-    if (bindingGroups.length === 0) {
+function collectToolkitBootstrapCommands(toolKits) {
+    if (toolKits.length === 0) {
         return [];
     }
-    return ["agentos", ...bindingGroups.map((group) => `agentos-${group.name}`)];
+    return ["agentos", ...toolKits.map((toolKit) => `agentos-${toolKit.name}`)];
 }
 function validationMessage(error) {
     if (typeof error === "object" &&
@@ -886,42 +888,42 @@ function combineInstructions(additionalInstructions, toolReference) {
     }
     return parts.join("\n\n");
 }
-function buildHostToolReference(bindingGroups) {
-    if (bindingGroups.length === 0) {
+function buildHostToolReference(toolKits) {
+    if (toolKits.length === 0) {
         return "";
     }
     const lines = [
-        "## Available Bindings",
+        "## Available Host Tools",
         "",
-        "Run `agentos list-tools` to see all available bindings.",
+        "Run `agentos list-tools` to see all available tools.",
         "",
     ];
-    for (const group of bindingGroups) {
-        lines.push(`### ${group.name}`);
+    for (const toolKit of toolKits) {
+        lines.push(`### ${toolKit.name}`);
         lines.push("");
-        lines.push(group.description);
+        lines.push(toolKit.description);
         lines.push("");
-        for (const [bindingName, tool] of Object.entries(group.bindings)) {
+        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
             const sidecarTool = toolToSidecarDefinition(tool);
             const signature = buildToolFlagSignature(sidecarTool.inputSchema);
             const suffix = signature.length > 0 ? ` ${signature}` : "";
-            lines.push(`- \`agentos-${group.name} ${bindingName}${suffix}\` — ${tool.description}`);
+            lines.push(`- \`agentos-${toolKit.name} ${toolName}${suffix}\` — ${tool.description}`);
         }
         lines.push("");
-        const toolsWithExamples = Object.entries(group.bindings).filter(([, tool]) => tool.examples && tool.examples.length > 0);
+        const toolsWithExamples = Object.entries(toolKit.tools).filter(([, tool]) => tool.examples && tool.examples.length > 0);
         if (toolsWithExamples.length > 0) {
             lines.push("**Examples:**");
             lines.push("");
-            for (const [bindingName, tool] of toolsWithExamples) {
+            for (const [toolName, tool] of toolsWithExamples) {
                 for (const example of tool.examples ?? []) {
                     const args = inputToToolFlags(example.input);
                     const suffix = args.length > 0 ? ` ${args}` : "";
-                    lines.push(`- ${example.description}: \`agentos-${group.name} ${bindingName}${suffix}\``);
+                    lines.push(`- ${example.description}: \`agentos-${toolKit.name} ${toolName}${suffix}\``);
                 }
             }
             lines.push("");
         }
-        lines.push(`Run \`agentos-${group.name} <binding> --help\` for details.`);
+        lines.push(`Run \`agentos-${toolKit.name} <tool> --help\` for details.`);
         lines.push("");
     }
     return lines.join("\n");
@@ -1062,11 +1064,11 @@ async function handleHostCallback(request, context) {
         };
     }
 }
-function buildToolMap(bindingGroups) {
+function buildToolMap(toolKits) {
     const toolMap = new Map();
-    for (const group of bindingGroups) {
-        for (const [bindingName, tool] of Object.entries(group.bindings)) {
-            toolMap.set(`${group.name}:${bindingName}`, tool);
+    for (const toolKit of toolKits) {
+        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
+            toolMap.set(`${toolKit.name}:${toolName}`, tool);
         }
     }
     return toolMap;
@@ -1088,33 +1090,33 @@ function parseHostCommandCallbackInput(input) {
     };
 }
 async function handleHostCommandCallback(command, context) {
-    const directToolKit = context.bindings.find((group) => `agentos-${group.name}` === command.command);
+    const directToolKit = context.toolKits.find((toolKit) => `agentos-${toolKit.name}` === command.command);
     if (command.command === "agentos") {
-        return handleAgentOSRegistryCommand(command, context);
+        return handleAgentOsRegistryCommand(command, context);
     }
     if (directToolKit) {
-        return handleAgentOSToolkitCommand(command, context, directToolKit);
+        return handleAgentOsToolkitCommand(command, context, directToolKit);
     }
     throw new Error(`Unknown host callback command "${command.command}"`);
 }
-async function handleAgentOSRegistryCommand(command, context) {
+async function handleAgentOsRegistryCommand(command, context) {
     const [subcommand, toolkitName, toolName, ...toolArgs] = command.args;
     if (!subcommand || isHelpFlag(subcommand)) {
         return {
-            usage: "agentos <command>: list-tools [bindings], <bindings> --help, or <bindings> <binding> ...",
+            usage: "agentos <command>: list-tools [toolkit], <toolkit> --help, or <toolkit> <tool> ...",
         };
     }
     if (subcommand === "list-tools") {
         return toolkitName
-            ? describeToolkitPayload(context.bindings, toolkitName)
-            : listToolkitsPayload(context.bindings);
+            ? describeToolkitPayload(context.toolKits, toolkitName)
+            : listToolkitsPayload(context.toolKits);
     }
-    const toolKit = context.bindings.find((kit) => kit.name === subcommand);
+    const toolKit = context.toolKits.find((kit) => kit.name === subcommand);
     if (!toolKit) {
-        throw new Error(`No bindings "${subcommand}". Available: ${toolkitNames(context.bindings)}`);
+        throw new Error(`No toolkit "${subcommand}". Available: ${toolkitNames(context.toolKits)}`);
     }
     if (!toolkitName || isHelpFlag(toolkitName)) {
-        return describeToolkitPayload(context.bindings, subcommand);
+        return describeToolkitPayload(context.toolKits, subcommand);
     }
     if (toolName && isHelpFlag(toolName)) {
         return describeToolPayload(toolKit, toolkitName);
@@ -1127,10 +1129,10 @@ async function handleAgentOSRegistryCommand(command, context) {
         context,
     });
 }
-async function handleAgentOSToolkitCommand(command, context, toolKit) {
+async function handleAgentOsToolkitCommand(command, context, toolKit) {
     const [toolName, helpOrFirstArg, ...rest] = command.args;
     if (!toolName || isHelpFlag(toolName)) {
-        return describeToolkitPayload(context.bindings, toolKit.name);
+        return describeToolkitPayload(context.toolKits, toolKit.name);
     }
     if (helpOrFirstArg && isHelpFlag(helpOrFirstArg)) {
         return describeToolPayload(toolKit, toolName);
@@ -1144,14 +1146,14 @@ async function handleAgentOSToolkitCommand(command, context, toolKit) {
     });
 }
 async function invokeHostTool({ toolKit, toolName, args, cwd, context, }) {
-    const tool = toolKit.bindings[toolName];
+    const tool = toolKit.tools[toolName];
     if (!tool) {
-        throw new Error(`No binding "${toolName}" in bindings "${toolKit.name}". Available: ${toolNames(toolKit)}`);
+        throw new Error(`No tool "${toolName}" in toolkit "${toolKit.name}". Available: ${toolNames(toolKit)}`);
     }
     const callbackKey = `${toolKit.name}:${toolName}`;
     const permissionMode = toolPermissionMode(context.permissions, callbackKey);
     if (permissionMode !== "allow") {
-        throw new Error(`EACCES: blocked by binding.invoke policy for ${callbackKey}`);
+        throw new Error(`EACCES: blocked by tool.invoke policy for ${callbackKey}`);
     }
     const input = await parseHostToolInput(tool, args, cwd, context.readFile);
     return executeHostTool(tool, callbackKey, input);
@@ -1264,25 +1266,25 @@ function parseToolArgv(schema, argv) {
     }
     return input;
 }
-function listToolkitsPayload(bindingGroups) {
+function listToolkitsPayload(toolKits) {
     return {
-        bindings: bindingGroups.map((group) => ({
-            name: group.name,
-            description: group.description,
-            bindings: Object.keys(group.bindings),
+        toolkits: toolKits.map((toolKit) => ({
+            name: toolKit.name,
+            description: toolKit.description,
+            tools: Object.keys(toolKit.tools),
         })),
     };
 }
-function describeToolkitPayload(bindingGroups, toolkitName) {
-    const toolKit = bindingGroups.find((kit) => kit.name === toolkitName);
+function describeToolkitPayload(toolKits, toolkitName) {
+    const toolKit = toolKits.find((kit) => kit.name === toolkitName);
     if (!toolKit) {
-        throw new Error(`No bindings "${toolkitName}". Available: ${toolkitNames(bindingGroups)}`);
+        throw new Error(`No toolkit "${toolkitName}". Available: ${toolkitNames(toolKits)}`);
     }
     return {
         name: toolKit.name,
         description: toolKit.description,
-        bindings: Object.fromEntries(Object.entries(toolKit.bindings).map(([bindingName, tool]) => [
-            bindingName,
+        tools: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
+            toolName,
             {
                 description: tool.description,
                 flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
@@ -1291,13 +1293,13 @@ function describeToolkitPayload(bindingGroups, toolkitName) {
     };
 }
 function describeToolPayload(toolKit, toolName) {
-    const tool = toolKit.bindings[toolName];
+    const tool = toolKit.tools[toolName];
     if (!tool) {
-        throw new Error(`No binding "${toolName}" in bindings "${toolKit.name}". Available: ${toolNames(toolKit)}`);
+        throw new Error(`No tool "${toolName}" in toolkit "${toolKit.name}". Available: ${toolNames(toolKit)}`);
     }
     return {
-        bindings: toolKit.name,
-        binding: toolName,
+        toolkit: toolKit.name,
+        tool: toolName,
         description: tool.description,
         flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
         examples: tool.examples?.map((example) => ({
@@ -1307,7 +1309,7 @@ function describeToolPayload(toolKit, toolName) {
     };
 }
 function toolPermissionMode(permissions, callbackKey) {
-    const scope = permissions.binding;
+    const scope = permissions.tool;
     if (!scope) {
         return "deny";
     }
@@ -1341,11 +1343,11 @@ function permissionPatternMatches(pattern, value) {
         .join("");
     return new RegExp(`^${source}$`).test(value);
 }
-function toolkitNames(bindingGroups) {
-    return bindingGroups.map((group) => group.name).join(", ");
+function toolkitNames(toolKits) {
+    return toolKits.map((toolKit) => toolKit.name).join(", ");
 }
 function toolNames(toolKit) {
-    return Object.keys(toolKit.bindings).join(", ");
+    return Object.keys(toolKit.tools).join(", ");
 }
 function isHelpFlag(value) {
     return value === "--help" || value === "-h";
@@ -1354,25 +1356,25 @@ function jsonSchemaType(schema) {
     const schemaObject = asRecord(schema);
     return typeof schemaObject.type === "string" ? schemaObject.type : undefined;
 }
-async function registerToolkitsOnSidecar(client, session, vm, bindingGroups) {
-    if (bindingGroups.length === 0) {
+async function registerToolkitsOnSidecar(client, session, vm, toolKits) {
+    if (toolKits.length === 0) {
         return "";
     }
-    for (const group of bindingGroups) {
+    for (const toolKit of toolKits) {
         await client.registerHostCallbacks(session, vm, {
-            name: group.name,
-            description: group.description,
-            commandAliases: [`agentos-${group.name}`],
+            name: toolKit.name,
+            description: toolKit.description,
+            commandAliases: [`agentos-${toolKit.name}`],
             registryCommandAliases: ["agentos"],
-            callbacks: Object.fromEntries(Object.entries(group.bindings).map(([bindingName, tool]) => [
-                bindingName,
+            callbacks: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
+                toolName,
                 toolToSidecarDefinition(tool),
             ])),
         });
     }
-    return buildHostToolReference(bindingGroups);
+    return buildHostToolReference(toolKits);
 }
-export class AgentOS {
+export class AgentOs {
     #kernel;
     sidecar;
     _sessions = new Map();
@@ -1389,7 +1391,7 @@ export class AgentOS {
     _softwareRoots;
     _softwareAgentConfigs;
     _cronManager;
-    _bindings = [];
+    _toolKits = [];
     _toolReference = "";
     _permissions = allowAll;
     _hostMounts;
@@ -1414,7 +1416,7 @@ export class AgentOS {
         this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
             this._handleSidecarEvent(event);
         });
-        agentOSRuntimeAdmins.set(this, {
+        agentOsRuntimeAdmins.set(this, {
             kernel,
             rootView: rootFilesystem,
             env,
@@ -1422,28 +1424,21 @@ export class AgentOS {
         });
     }
     static async createSidecar(options = {}) {
-        return createAgentOSSidecarInternal(options);
+        return createAgentOsSidecarInternal(options);
     }
     static async getSharedSidecar(options = {}) {
-        return getSharedAgentOSSidecarInternal(options);
+        return getSharedAgentOsSidecarInternal(options);
     }
     static async create(options) {
-        // Prepend the default common software set, skipping any descriptors the
-        // caller already passed (so an explicit `software: [common, ...]` is safe).
-        const userSoftware = options?.software ?? [];
-        const software = [
-            ...defaultCommonSoftware.filter((pkg) => !userSoftware.includes(pkg)),
-            ...userSoftware,
-        ];
-        const processed = processSoftware(software);
+        const processed = processSoftware(options?.software ?? []);
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
-        const bindingGroups = options?.bindings;
-        if (bindingGroups && bindingGroups.length > 0) {
-            validateBindings(bindingGroups);
+        const toolKits = options?.toolKits;
+        if (toolKits && toolKits.length > 0) {
+            validateToolkits(toolKits);
         }
         const createVmAdmin = async () => {
             const preparedCommandDirs = prepareCommandDirs(processed.commandPackages);
-            const toolBootstrapCommands = collectToolkitBootstrapCommands(bindingGroups ?? []);
+            const toolBootstrapCommands = collectToolkitBootstrapCommands(toolKits ?? []);
             const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem, [
                 ...collectBootstrapWasmCommands(preparedCommandDirs.commandDirs),
                 ...NODE_RUNTIME_BOOTSTRAP_COMMANDS,
@@ -1468,8 +1463,8 @@ export class AgentOS {
             };
             try {
                 const env = getBaseEnvironment();
-                if (bindingGroups && bindingGroups.length > 0) {
-                    toolShimDir = materializeToolShimDir(bindingGroups);
+                if (toolKits && toolKits.length > 0) {
+                    toolShimDir = materializeToolShimDir(toolKits);
                 }
                 const commandGuestPaths = collectGuestCommandPaths(preparedCommandDirs.commandDirs);
                 const requestedMounts = options?.moduleAccessCwd
@@ -1491,7 +1486,7 @@ export class AgentOS {
                     commandDirs: preparedCommandDirs.commandDirs,
                     shimDir: toolShimDir,
                 });
-                client = NativeSidecarProcessClient.spawn({
+                client = SidecarProcess.spawn({
                     cwd: REPO_ROOT,
                     command: ensureNativeSidecarBinary(),
                     args: [],
@@ -1500,7 +1495,7 @@ export class AgentOS {
                 const session = await client.authenticateAndOpenSession();
                 const hostPermissions = options?.permissions ?? {
                     ...allowAll,
-                    binding: "allow",
+                    tool: "allow",
                 };
                 const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
                 const createVmConfig = {
@@ -1537,11 +1532,11 @@ export class AgentOS {
                     commandPermissions: processed.commandPermissions,
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                 });
-                if (bindingGroups && bindingGroups.length > 0) {
-                    toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, bindingGroups);
+                if (toolKits && toolKits.length > 0) {
+                    toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
                     commandGuestPaths.set("agentos", "/bin/agentos");
-                    for (const group of bindingGroups) {
-                        commandGuestPaths.set(`agentos-${group.name}`, `/bin/agentos-${group.name}`);
+                    for (const toolKit of toolKits) {
+                        commandGuestPaths.set(`agentos-${toolKit.name}`, `/bin/agentos-${toolKit.name}`);
                     }
                 }
                 rootBridge = new NativeSidecarKernelProxy({
@@ -1549,7 +1544,7 @@ export class AgentOS {
                     session,
                     vm: nativeVm,
                     env,
-                    cwd: "/workspace",
+                    cwd: "/home/user",
                     localMounts,
                     commandGuestPaths,
                     onDispose: cleanup,
@@ -1567,7 +1562,7 @@ export class AgentOS {
                     sidecarVm: nativeVm,
                     permissions: hostPermissions,
                     snapshotRootFilesystem: async () => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm))),
-                    bindings: bindingGroups ?? [],
+                    toolKits: toolKits ?? [],
                     toolReference,
                     async dispose() {
                         if (kernel) {
@@ -1599,16 +1594,16 @@ export class AgentOS {
                 throw error;
             }
         };
-        const sidecar = resolveAgentOSSidecar(options?.sidecar);
+        const sidecar = resolveAgentOsSidecar(options?.sidecar);
         let sidecarLease = null;
         try {
-            sidecarLease = await leaseAgentOSSidecarVm(sidecar, {
+            sidecarLease = await leaseAgentOsSidecarVm(sidecar, {
                 createVm: async () => createVmAdmin(),
             });
             const vmAdmin = sidecarLease.admin;
-            const vm = new AgentOS(vmAdmin.kernel, sidecar, processed.softwareRoots, processed.agentConfigs, vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm);
+            const vm = new AgentOs(vmAdmin.kernel, sidecar, processed.softwareRoots, processed.agentConfigs, vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm);
             vm._sidecarLease = sidecarLease;
-            vm._bindings = vmAdmin.bindings;
+            vm._toolKits = vmAdmin.toolKits;
             vm._toolReference = vmAdmin.toolReference;
             vm._permissions = vmAdmin.permissions;
             vm._installSidecarRequestHandler();
@@ -2529,7 +2524,7 @@ export class AgentOS {
         // skipOsInstructions plus the agent's static launch args and env.
         const launchArgs = [...(config.launchArgs ?? [])];
         let launchEnv = { ...config.defaultEnv, ...options?.env };
-        const sessionCwd = options?.cwd ?? "/workspace";
+        const sessionCwd = options?.cwd ?? "/home/user";
         const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
         if ((agentType === "pi" || agentType === "pi-cli") &&
             !launchEnv.PI_ACP_PI_COMMAND) {
@@ -2585,6 +2580,70 @@ export class AgentOS {
         }
         return { sessionId: created.sessionId };
     }
+    /**
+     * Resume a session that exists in durable storage but is not live in this VM
+     * (e.g. after a Rivet actor slept and woke with a fresh VM). Thin forwarder:
+     * resolves the agent config + adapter entrypoint exactly as {@link createSession}
+     * does, then forwards a single `AcpResumeSessionRequest` to the sidecar, which
+     * owns the resume state machine (native `session/load` when the agent supports
+     * it, else `session/new` + a transcript-continuation preamble). The returned
+     * `sessionId` is the live id in this VM (equal to the requested id for native
+     * loads, freshly assigned for the fallback); the caller remaps `external -> live`.
+     * The new live session is registered + hydrated locally so subsequent prompts
+     * route to it.
+     *
+     * Resume depends on a durable root; on a non-durable (default in-memory) root
+     * there is no surviving store and the fallback tier always runs.
+     */
+    async resumeSession(sessionId, agentType, options) {
+        const config = this._resolveAgentConfig(agentType);
+        if (!config) {
+            throw new Error(`Unknown agent type: ${agentType}`);
+        }
+        const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
+        let launchEnv = { ...config.defaultEnv, ...options?.env };
+        const sessionCwd = options?.cwd ?? "/home/user";
+        if ((agentType === "pi" || agentType === "pi-cli") &&
+            !launchEnv.PI_ACP_PI_COMMAND) {
+            launchEnv = {
+                ...launchEnv,
+                PI_ACP_PI_COMMAND: this._resolvePackageBin(config.agentPackage, "pi"),
+            };
+        }
+        // The resume wire request has no dedicated `adapterEntrypoint` field; carry
+        // the resolved entrypoint through env under the sidecar's reserved key. The
+        // sidecar reads it and strips it before launching the adapter.
+        launchEnv = {
+            ...launchEnv,
+            [RESUME_ADAPTER_ENTRYPOINT_ENV]: adapterEntrypoint,
+        };
+        const response = await this._sendAcpRequest({
+            tag: "AcpResumeSessionRequest",
+            val: {
+                sessionId,
+                agentType: String(agentType),
+                transcriptPath: options?.transcriptPath ?? null,
+                cwd: sessionCwd,
+                env: new Map(Object.entries(launchEnv)),
+            },
+        });
+        if (response.tag !== "AcpSessionResumedResponse") {
+            throw new Error(`unexpected resume_session response: ${response.tag}`);
+        }
+        const { sessionId: liveSessionId, mode } = response.val;
+        // Register + hydrate the live session so subsequent prompts route to it.
+        const session = sessionEntryFromInit(liveSessionId, String(agentType), {});
+        this._closedSessionIds.delete(liveSessionId);
+        this._sessions.set(liveSessionId, session);
+        try {
+            await this._hydrateSessionState(session);
+        }
+        catch (error) {
+            this._removeSession(liveSessionId);
+            throw error;
+        }
+        return { sessionId: liveSessionId, mode };
+    }
     /**
      * Resolve the VM bin entry point of an ACP adapter package.
      * Reads from the host filesystem since kernel.readFile() resolves through
@@ -2624,7 +2683,7 @@ export class AgentOS {
             if (!nodeModulesRoot) {
                 throw new Error(`Cannot resolve package "${packageName}": no software root provides it and ` +
                     `no /root/node_modules mount was supplied. Pass ` +
-                    `mounts: [nodeModulesMount("<host>/node_modules")] to AgentOS.create().`);
+                    `mounts: [nodeModulesMount("<host>/node_modules")] to AgentOs.create().`);
             }
             hostPkgJsonPath = join(resolvePackageDir(nodeModulesRoot, packageName), "package.json");
         }
@@ -2646,8 +2705,8 @@ export class AgentOS {
     }
     _installSidecarRequestHandler() {
         const context = {
-            bindings: this._bindings,
-            toolMap: buildToolMap(this._bindings),
+            toolKits: this._toolKits,
+            toolMap: buildToolMap(this._toolKits),
             permissions: this._permissions,
             readFile: (path) => this.readFile(path),
         };
@@ -3358,26 +3417,26 @@ export class AgentOS {
         return this.#kernel.dispose();
     }
 }
-const agentOSRuntimeAdmins = new WeakMap();
-export function getAgentOSRuntimeAdmin(vm) {
-    const admin = agentOSRuntimeAdmins.get(vm);
+const agentOsRuntimeAdmins = new WeakMap();
+export function getAgentOsRuntimeAdmin(vm) {
+    const admin = agentOsRuntimeAdmins.get(vm);
     if (!admin) {
         throw new Error("Agent OS runtime admin is not available for this VM");
     }
     return admin;
 }
-export function getAgentOSKernel(vm) {
-    return getAgentOSRuntimeAdmin(vm).kernel;
+export function getAgentOsKernel(vm) {
+    return getAgentOsRuntimeAdmin(vm).kernel;
 }
-function resolveAgentOSSidecar(config) {
+function resolveAgentOsSidecar(config) {
     if (!config || config.kind === "shared") {
-        return getSharedAgentOSSidecarInternal(config?.kind === "shared" ? { pool: config.pool } : undefined);
+        return getSharedAgentOsSidecarInternal(config?.kind === "shared" ? { pool: config.pool } : undefined);
     }
     return config.handle;
 }
 const sidecarStates = new WeakMap();
 const sharedSidecars = new Map();
-export class AgentOSSidecar {
+export class AgentOsSidecar {
     constructor(sidecarId, placement, sharedPool) {
         sidecarStates.set(this, {
             description: {
@@ -3420,9 +3479,9 @@ export class AgentOSSidecar {
         }
     }
 }
-function createAgentOSSidecarInternal(options = {}) {
+function createAgentOsSidecarInternal(options = {}) {
     const sidecarId = options.sidecarId ?? `agentos-sidecar-${randomUUID()}`;
-    return new AgentOSSidecar(sidecarId, {
+    return new AgentOsSidecar(sidecarId, {
         kind: "explicit",
         sidecarId,
     });
@@ -3430,7 +3489,7 @@ function createAgentOSSidecarInternal(options = {}) {
 /**
  * Test-only escape hatch: dispose every cached shared sidecar so vitest
  * workers can exit cleanly. The shared sidecar is normally process-global and
- * keeps its native subprocess alive across `AgentOS.create()` calls; without
+ * keeps its native subprocess alive across `AgentOs.create()` calls; without
  * this hook the vitest worker can hold open piped stdio handles after the
  * test suite finishes and stall `pnpm test` indefinitely.
  */
@@ -3450,23 +3509,23 @@ export async function __disposeAllSharedSidecarsForTesting() {
         throw new Error(`failed to dispose shared sidecars: ${errors.map((error) => error.message).join("; ")}`);
     }
 }
-function getSharedAgentOSSidecarInternal(options = {}) {
+function getSharedAgentOsSidecarInternal(options = {}) {
     const pool = options.pool ?? "default";
     const existing = sharedSidecars.get(pool);
     if (existing && existing.describe().state !== "disposed") {
         return existing;
     }
-    const sidecar = new AgentOSSidecar(`agentos-shared-sidecar:${pool}`, { kind: "shared", ...(pool ? { pool } : {}) }, pool);
+    const sidecar = new AgentOsSidecar(`agentos-shared-sidecar:${pool}`, { kind: "shared", ...(pool ? { pool } : {}) }, pool);
     sharedSidecars.set(pool, sidecar);
     return sidecar;
 }
-async function leaseAgentOSSidecarVm(sidecar, options) {
+async function leaseAgentOsSidecarVm(sidecar, options) {
     const state = getSidecarState(sidecar);
     if (state.description.state !== "ready") {
         throw new Error(`Cannot lease VM from sidecar ${state.description.sidecarId} while it is ${state.description.state}`);
     }
     let transport;
-    const client = createAgentOSSidecarClient({
+    const client = createAgentOsSidecarClient({
         async createSessionTransport(sessionBootstrap) {
             transport = await createInProcessSidecarTransport(sessionBootstrap, options);
             return transport;

package/dist/agents.d.ts

@@ -42,7 +42,7 @@ export declare const AGENT_CONFIGS: {
         defaultEnv: {
             CLAUDE_AGENT_SDK_CLIENT_APP: string;
             CLAUDE_CODE_SIMPLE: string;
-            CLAUDE_CODE_FORCE_AGENTOS_RIPGREP: string;
+            CLAUDE_CODE_FORCE_AGENT_OS_RIPGREP: string;
             CLAUDE_CODE_DEFER_GROWTHBOOK_INIT: string;
             CLAUDE_CODE_DISABLE_CWD_PERSIST: string;
             CLAUDE_CODE_DISABLE_DEV_NULL_REDIRECT: string;