@rivet-dev/agentos-core 0.2.5-rc.3 → 0.2.5-rc.4

package/dist/agent-os.js

@@ -1,7 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { tmpdir } from "node:os";
+import { 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";
@@ -13,14 +12,6 @@ export { isAcpTimeoutErrorData } from "./json-rpc.js";
 const ACP_PROTOCOL_VERSION = 1;
 const ACP_EXTENSION_NAMESPACE = "dev.rivet.agent-os.acp";
 const SHELL_DISPOSE_TIMEOUT_MS = 5_000;
-/**
- * Reserved `env` key on `AcpResumeSessionRequest` carrying the resolved adapter
- * bin entrypoint. The resume wire request omits a dedicated `adapterEntrypoint`
- * field; the sidecar reads the entrypoint from this key and strips it before
- * launching the adapter. Must stay in sync with the sidecar constant of the same
- * name in `crates/agentos-sidecar/src/acp_extension.rs`.
- */
-const RESUME_ADAPTER_ENTRYPOINT_ENV = "AGENT_OS_RESUME_ADAPTER_ENTRYPOINT";
 function defaultAcpClientCapabilities() {
     return {
         fs: {
@@ -45,12 +36,10 @@ import { getBaseEnvironment } from "./base-filesystem.js";
 import { CronManager } from "./cron/cron-manager.js";
 import { TimerScheduleDriver } from "./cron/timer-driver.js";
 import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
-import { createHostDirBackend } from "./host-dir-mount.js";
 import { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
-import { resolveAgentSnapshotBundle, } from "./packages.js";
-import { OPT_AGENTOS_BIN, OPT_AGENTOS_ROOT, tryReadAgentosPackageManifest, } from "./agentos-package.js";
-import { resolveDefaultSoftware, resolveDependencyAgents, } from "./default-software.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 { serializePermissionsForSidecar } from "./sidecar/permissions.js";
@@ -114,52 +103,27 @@ function toRecord(value) {
         : {};
 }
 function normalizePackageRef(value) {
+    // The single package reference is `packagePath`: the packed `.aospkg` file
+    // (registry-built packages export `{ packagePath }`), or a package dir for
+    // local transition fixtures. A raw string is shorthand for the same path.
     if (typeof value === "string") {
-        return { dir: value };
+        return { path: value };
     }
     const record = toRecord(value);
-    if (typeof record.packageDir === "string") {
-        return {
-            dir: record.packageDir,
-            legacyManifest: legacyPackageManifest(record),
-        };
+    if (typeof record.packagePath === "string") {
+        return { path: record.packagePath };
     }
-    if (typeof record.dir === "string") {
-        return {
-            dir: record.dir,
-            legacyManifest: legacyPackageManifest(record),
-        };
+    // Recognizably-legacy shapes fail loudly: silently dropping a software
+    // entry boots a VM with missing packages and no diagnostic.
+    for (const legacy of ["packageTar", "packageDir", "dir"]) {
+        if (typeof record[legacy] === "string") {
+            throw new Error(`agentOS package ref uses removed field "${legacy}" (value: ${JSON.stringify(record[legacy])}); ` +
+                "packages are referenced by a single `packagePath` — update the package " +
+                "(rebuild @agentos-software/* dependencies) or pass { packagePath }");
+        }
     }
     return undefined;
 }
-function legacyPackageManifest(record) {
-    if (typeof record.name !== "string") {
-        return undefined;
-    }
-    const manifest = { name: record.name };
-    const agent = toRecord(record.agent);
-    if (typeof agent.acpEntrypoint === "string") {
-        manifest.agent = {
-            acpEntrypoint: agent.acpEntrypoint,
-            ...(isStringRecord(agent.env) ? { env: agent.env } : {}),
-            ...(Array.isArray(agent.launchArgs) &&
-                agent.launchArgs.every((arg) => typeof arg === "string")
-                ? { launchArgs: agent.launchArgs }
-                : {}),
-            ...(typeof agent.snapshot === "boolean" ? { snapshot: agent.snapshot } : {}),
-        };
-    }
-    return manifest;
-}
-function readPackageManifestForClient(ref) {
-    return tryReadAgentosPackageManifest(ref.dir) ?? ref.legacyManifest;
-}
-function isStringRecord(value) {
-    return (value !== null &&
-        typeof value === "object" &&
-        !Array.isArray(value) &&
-        Object.values(value).every((entry) => typeof entry === "string"));
-}
 function parseAcpJson(value, context) {
     if (value === null) {
         return undefined;
@@ -475,7 +439,6 @@ const RUNTIME_BOOTSTRAP_COMMANDS = [
     "python",
     "python3",
 ];
-const KERNEL_COMMAND_STUB = "#!/bin/sh\n# kernel command stub\n";
 const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
 const SIDECAR_BINARY = join(REPO_ROOT, "target/debug/agentos-sidecar");
 const SIDECAR_BUILD_INPUTS = [
@@ -515,7 +478,7 @@ function findBootstrapSeedEntry(config, path) {
     const meta = KERNEL_POSIX_BOOTSTRAP_DIR_METADATA[path];
     return meta ? { path, type: "directory", ...meta } : undefined;
 }
-function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
+function createKernelBootstrapLower(config, extraEntries = []) {
     const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
     const existingPaths = collectConfiguredLowerPaths(config);
     const entries = [
@@ -557,22 +520,6 @@ function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
             encoding: "base64",
         });
     }
-    const uniqueCommands = [...new Set(commandNames)].sort((a, b) => a.localeCompare(b));
-    for (const command of uniqueCommands) {
-        const stubPath = `/bin/${command}`;
-        if (existingPaths.has(stubPath)) {
-            continue;
-        }
-        entries.push({
-            path: stubPath,
-            type: "file",
-            mode: "755",
-            uid: 0,
-            gid: 0,
-            content: KERNEL_COMMAND_STUB,
-            encoding: "utf8",
-        });
-    }
     for (const entry of sortFilesystemEntries(extraEntries)) {
         if (existingPaths.has(entry.path)) {
             continue;
@@ -769,28 +716,10 @@ function collectSidecarMountPlan(options) {
         }
         pushMount(mount);
     }
-    if (options.shimDir) {
-        pushMount({
-            path: "/usr/local/bin",
-            plugin: createHostDirBackend({
-                hostPath: options.shimDir,
-                readOnly: true,
-            }),
-            readOnly: true,
-        });
-    }
     hostMounts.sort((left, right) => right.vmPath.length - left.vmPath.length);
     hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
     return { sidecarMounts, hostMounts, hostPathMappings };
 }
-function materializeToolShimDir(toolKits) {
-    const shimDir = mkdtempSync(join(tmpdir(), "agentos-host-tools-shims-"));
-    writeFileSync(join(shimDir, "agentos"), KERNEL_COMMAND_STUB, { mode: 0o755 });
-    for (const toolKit of toolKits) {
-        writeFileSync(join(shimDir, `agentos-${toolKit.name}`), KERNEL_COMMAND_STUB, { mode: 0o755 });
-    }
-    return shimDir;
-}
 function collectToolkitBootstrapCommands(toolKits) {
     if (toolKits.length === 0) {
         return [];
@@ -1465,12 +1394,9 @@ export class AgentOs {
     _closedShellIds = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
     _pendingShellExitPromises = new Set();
     _shellCounter = 0;
-    /** Command names linked into `/opt/agentos/bin` at runtime (via the sidecar). */
-    _linkedCommands = new Set();
     _acpTerminals = new Map();
     _acpTerminalCounter = 0;
     _softwareRoots;
-    _softwareAgentConfigs;
     _cronManager;
     _toolKits = [];
     _toolReference = "";
@@ -1487,11 +1413,10 @@ export class AgentOs {
     _agentStderrHandler;
     _agentExitHandler;
     _limitWarningHandler;
-    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, agentStderrHandler, agentExitHandler, limitWarningHandler) {
+    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, agentStderrHandler, agentExitHandler, limitWarningHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
         this._softwareRoots = softwareRoots;
-        this._softwareAgentConfigs = softwareAgentConfigs;
         this._hostMounts = hostMounts;
         this._env = env;
         this._rootFilesystem = rootFilesystem;
@@ -1527,38 +1452,32 @@ export class AgentOs {
         // 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.
-        const defaultSoftware = options?.defaultSoftware === false ? [] : await resolveDefaultSoftware();
+        const defaultSoftware = options?.defaultSoftware === false ? [] : resolveDefaultSoftware();
         const software = options?.defaultSoftware === false
             ? (options.software ?? [])
             : [...defaultSoftware, ...(options?.software ?? [])];
-        // Package dirs are projected by the SIDECAR: the client forwards only
-        // `{dir}` over `configureVm` and the sidecar reads package metadata from
-        // `<dir>/agentos-package.json`.
+        // Packages are projected by the SIDECAR: the client forwards only the
+        // package `path` over `configureVm` and the sidecar reads metadata from
+        // the packed vbare manifest (chunk1 of the `.aospkg`).
         const flatSoftware = software.flat();
-        const packageRefs = flatSoftware.flatMap((entry) => {
+        // Honor the AgentOsOptions.defaultSoftware contract ("entries already present
+        // in `software` are not duplicated"): the default bundle and an explicitly
+        // passed one resolve to the same package paths, so dedup by path. Without
+        // this the sidecar rejects the second projection with a duplicate-command
+        // error (e.g. coreutils' `[`).
+        const seenPackagePaths = new Set();
+        const sidecarPackages = flatSoftware.flatMap((entry) => {
             const ref = normalizePackageRef(entry);
-            return ref ? [ref] : [];
+            if (!ref || seenPackagePaths.has(ref.path)) {
+                return [];
+            }
+            seenPackagePaths.add(ref.path);
+            return [{ path: ref.path }];
         });
-        const sidecarPackages = packageRefs.map((ref) => ({ dir: ref.dir }));
         // All package software is projected into `/opt/agentos` by the sidecar. The
-        // client stages nothing host-side; it only derives the agent configs.
-        const agentConfigs = new Map();
-        // Register `/opt/agentos` agent packages so `createSession(<name>)`
-        // launches via `/opt/agentos/bin/<acpEntrypoint>`. The wire no longer
-        // carries agent metadata; read it from the package manifest.
-        for (const ref of packageRefs) {
-            const manifest = readPackageManifestForClient(ref);
-            if (!manifest?.agent)
-                continue;
-            agentConfigs.set(manifest.name, {
-                adapterEntrypoint: `${OPT_AGENTOS_BIN}/${manifest.agent.acpEntrypoint}`,
-                launchArgs: manifest.agent.launchArgs,
-                defaultEnv: manifest.agent.env,
-            });
-        }
-        // Agent-SDK snapshot bundle (loaded once per sidecar into the V8 startup
-        // snapshot, reused across sessions) for any snapshot-enabled agent.
-        const snapshotUserlandCode = resolveAgentSnapshotBundle(packageRefs.map((ref) => ({ packageDir: ref.dir })));
+        // client stages nothing host-side and parses NO package manifests: the
+        // 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) {
@@ -1573,81 +1492,32 @@ export class AgentOs {
             // runtime `linkSoftware` appends to that live dir). The client no longer
             // stages packages host-side.
             const toolBootstrapCommands = collectToolkitBootstrapCommands(toolKits ?? []);
-            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem, [...RUNTIME_BOOTSTRAP_COMMANDS, ...toolBootstrapCommands]);
+            const bootstrapCommands = [
+                ...RUNTIME_BOOTSTRAP_COMMANDS,
+                ...toolBootstrapCommands,
+            ];
+            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem);
             let toolReference = "";
             let rootBridge = null;
             let kernel = null;
             let client = null;
             let createdNativeVm = null;
             let nativeSession = null;
-            let toolShimDir = null;
             let cleanedUp = false;
             const cleanup = async () => {
                 if (cleanedUp) {
                     return;
                 }
                 cleanedUp = true;
-                if (toolShimDir) {
-                    rmSync(toolShimDir, { recursive: true, force: true });
-                    toolShimDir = null;
-                }
             };
             try {
                 const env = getBaseEnvironment();
-                if (toolKits && toolKits.length > 0) {
-                    toolShimDir = materializeToolShimDir(toolKits);
-                }
-                // Guest command paths. The sidecar owns the `/opt/agentos` projection,
-                // but the client's command map (rpc-client) still needs to KNOW the
-                // projected command names so its shell-exec guard (`this.commands.has("sh")`)
-                // and wasmvm routing work. Seed each projected package's commands from its
-                // `bin` map (mirroring the sidecar projection's command derivation), mapped
-                // to their projected `/opt/agentos/bin/<cmd>` path. Tool-shim commands are
-                // added below.
+                // 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.
                 const commandGuestPaths = new Map();
-                const deriveProjectedCommandNames = (dir) => {
-                    try {
-                        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
-                        if (pkg.bin && typeof pkg.bin === "object") {
-                            return Object.keys(pkg.bin);
-                        }
-                        if (typeof pkg.bin === "string") {
-                            const base = pkg.name?.split("/").pop();
-                            if (base)
-                                return [base];
-                        }
-                    }
-                    catch {
-                        // no/invalid package.json — fall through to the bin/ scan
-                    }
-                    try {
-                        return readdirSync(join(dir, "bin"));
-                    }
-                    catch {
-                        return [];
-                    }
-                };
-                for (const ref of packageRefs) {
-                    for (const cmd of deriveProjectedCommandNames(ref.dir)) {
-                        commandGuestPaths.set(cmd, `/opt/agentos/bin/${cmd}`);
-                    }
-                }
-                const requestedMounts = options?.moduleAccessCwd
-                    ? [
-                        ...(options.mounts ?? []),
-                        {
-                            path: "/root/node_modules",
-                            plugin: createHostDirBackend({
-                                hostPath: join(options.moduleAccessCwd, "node_modules"),
-                                readOnly: true,
-                            }),
-                            readOnly: true,
-                        },
-                    ]
-                    : options?.mounts;
                 const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
-                    mounts: requestedMounts,
-                    shimDir: toolShimDir,
+                    mounts: options?.mounts,
                 });
                 // Reuse the sidecar handle's single shared native process; this VM
                 // becomes another tenant of it rather than spawning its own process.
@@ -1666,6 +1536,7 @@ export class AgentOs {
                     permissions: sidecarPermissions,
                     limits: options?.limits,
                     loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
+                    bootstrapCommands,
                     // 0.3: the Node builtin allow-list moved from configureVm to
                     // VM creation. `undefined` => engine default allow-list;
                     // `[]` => deny all; `[..]` => exactly those. Platform and
@@ -1673,8 +1544,7 @@ export class AgentOs {
                     // emulation), matching the prior behavior where Agent OS only
                     // constrained the builtin allow-list.
                     ...(options?.allowedNodeBuiltins !== undefined ||
-                        options?.highResolutionTime !== undefined ||
-                        snapshotUserlandCode !== undefined
+                        options?.highResolutionTime !== undefined
                         ? {
                             jsRuntime: {
                                 platform: "node",
@@ -1685,9 +1555,6 @@ export class AgentOs {
                                 ...(options?.highResolutionTime !== undefined
                                     ? { highResolutionTime: options.highResolutionTime }
                                     : {}),
-                                ...(snapshotUserlandCode !== undefined
-                                    ? { snapshotUserlandCode }
-                                    : {}),
                             },
                         }
                         : {}),
@@ -1703,14 +1570,18 @@ export class AgentOs {
                     event.payload.state === "ready" &&
                     event.ownership.scope === "vm" &&
                     event.ownership.vm_id === nativeVm.vmId, 10_000);
-                await client.configureVm(session, nativeVm, {
+                const configuredVm = await client.configureVm(session, nativeVm, {
                     mounts: sidecarMounts,
                     permissions: sidecarPermissions,
                     commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     packages: sidecarPackages,
                     packagesMountAt: OPT_AGENTOS_ROOT,
+                    toolShimCommands: toolBootstrapCommands,
                 });
+                for (const command of configuredVm.projectedCommands) {
+                    commandGuestPaths.set(command.name, command.guestPath);
+                }
                 if (toolKits && toolKits.length > 0) {
                     toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
                     commandGuestPaths.set("agentos", "/bin/agentos");
@@ -1796,7 +1667,7 @@ export class AgentOs {
                 createVm: async () => createVmAdmin(),
             });
             const vmAdmin = sidecarLease.admin;
-            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], agentConfigs, 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?.additionalInstructions, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onAgentExit ?? defaultAgentExitHandler, options?.onLimitWarning);
             vm._sidecarLease = sidecarLease;
             vm._toolKits = vmAdmin.toolKits;
             vm._toolReference = vmAdmin.toolReference;
@@ -1933,35 +1804,6 @@ export class AgentOs {
     _vfs() {
         return this.#kernel.vfs;
     }
-    async _copyPath(from, to) {
-        const stat = await this._vfs().lstat(from);
-        if (stat.isSymbolicLink) {
-            const target = await this._vfs().readlink(from);
-            await this._vfs().symlink(target, to);
-            return;
-        }
-        if (stat.isDirectory) {
-            await this._mkdirp(posixPath.dirname(to));
-            if (!(await this.#kernel.exists(to))) {
-                await this.#kernel.mkdir(to);
-            }
-            await this._vfs().chmod(to, stat.mode);
-            await this._vfs().chown(to, stat.uid, stat.gid);
-            const entries = await this.#kernel.readdir(from);
-            for (const entry of entries) {
-                if (entry === "." || entry === "..")
-                    continue;
-                const fromPath = from === "/" ? `/${entry}` : `${from}/${entry}`;
-                const toPath = to === "/" ? `/${entry}` : `${to}/${entry}`;
-                await this._copyPath(fromPath, toPath);
-            }
-            return;
-        }
-        const content = await this.#kernel.readFile(from);
-        await this.writeFile(to, content);
-        await this._vfs().chmod(to, stat.mode);
-        await this._vfs().chown(to, stat.uid, stat.gid);
-    }
     async readFile(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readFile(path);
@@ -2035,49 +1877,31 @@ export class AgentOs {
     }
     async readdirRecursive(path, options) {
         this._assertSafeAbsolutePath(path);
-        const maxDepth = options?.maxDepth;
         const exclude = options?.exclude ? new Set(options.exclude) : undefined;
+        const entries = await this.#kernel.readdirRecursive(path, {
+            maxDepth: options?.maxDepth,
+        });
+        const excludedPrefixes = [];
         const results = [];
-        // BFS queue: [dirPath, currentDepth]
-        const queue = [[path, 0]];
-        while (queue.length > 0) {
-            const item = queue.shift();
-            if (!item)
-                break;
-            const [dirPath, depth] = item;
-            const entries = await this.#kernel.readdir(dirPath);
-            for (const name of entries) {
-                if (name === "." || name === "..")
-                    continue;
-                if (exclude?.has(name))
-                    continue;
-                const fullPath = dirPath === "/" ? `/${name}` : `${dirPath}/${name}`;
-                const s = await this.#kernel.stat(fullPath);
-                if (s.isSymbolicLink) {
-                    results.push({
-                        path: fullPath,
-                        type: "symlink",
-                        size: s.size,
-                    });
-                }
-                else if (s.isDirectory) {
-                    results.push({
-                        path: fullPath,
-                        type: "directory",
-                        size: s.size,
-                    });
-                    if (maxDepth === undefined || depth < maxDepth) {
-                        queue.push([fullPath, depth + 1]);
-                    }
-                }
-                else {
-                    results.push({
-                        path: fullPath,
-                        type: "file",
-                        size: s.size,
-                    });
+        for (const entry of entries) {
+            if (excludedPrefixes.some((prefix) => entry.path === prefix || entry.path.startsWith(`${prefix}/`))) {
+                continue;
+            }
+            if (exclude?.has(entry.name)) {
+                if (entry.isDirectory && !entry.isSymbolicLink) {
+                    excludedPrefixes.push(entry.path);
                 }
+                continue;
             }
+            results.push({
+                path: entry.path,
+                type: entry.isSymbolicLink
+                    ? "symlink"
+                    : entry.isDirectory
+                        ? "directory"
+                        : "file",
+                size: entry.size,
+            });
         }
         return results;
     }
@@ -2105,30 +1929,15 @@ export class AgentOs {
         this.#kernel.unmountFs(path);
     }
     async move(from, to) {
-        this._assertSafeAbsolutePath(from);
-        this._assertSafeAbsolutePath(to);
-        const sourceStat = await this._vfs().lstat(from);
-        if (!sourceStat.isDirectory || sourceStat.isSymbolicLink) {
-            return this.#kernel.rename(from, to);
-        }
-        await this._copyPath(from, to);
-        await this.delete(from, { recursive: true });
+        this._assertWritableAbsolutePath(from);
+        this._assertWritableAbsolutePath(to);
+        await this.#kernel.movePath(from, to);
     }
     async delete(path, options) {
-        this._assertSafeAbsolutePath(path);
-        const s = await this._vfs().lstat(path);
-        if (s.isDirectory) {
-            if (options?.recursive) {
-                const entries = await this.#kernel.readdir(path);
-                for (const entry of entries) {
-                    if (entry === "." || entry === "..")
-                        continue;
-                    await this.delete(`${path}/${entry}`, { recursive: true });
-                }
-            }
-            return this.#kernel.removeDir(path);
-        }
-        return this.#kernel.removeFile(path);
+        this._assertWritableAbsolutePath(path);
+        await this.#kernel.removePath(path, {
+            recursive: options?.recursive ?? false,
+        });
     }
     async fetch(port, request) {
         const url = new URL(request.url);
@@ -2359,78 +2168,39 @@ export class AgentOs {
         // 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, { dir: ref.dir });
-        for (const command of commands) {
-            this._linkedCommands.add(command);
-        }
-        const manifest = readPackageManifestForClient(ref);
-        if (manifest?.agent) {
-            this._softwareAgentConfigs.set(manifest.name, {
-                adapterEntrypoint: `${OPT_AGENTOS_BIN}/${manifest.agent.acpEntrypoint}`,
-                launchArgs: manifest.agent.launchArgs,
-                defaultEnv: manifest.agent.env,
-            });
+        const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, { path: ref.path });
+        if (this.#kernel instanceof NativeSidecarKernelProxy) {
+            this.#kernel.registerCommandGuestPaths(new Map(commands.projectedCommands.map((command) => [
+                command.name,
+                command.guestPath,
+            ])));
         }
+        // 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.
     }
-    /** Returns all registered agents with their installation status. */
-    listAgents() {
-        // Collect agent IDs from package configs, the hardcoded configs, and the
-        // @agentos-software/* agent dependencies (linked lazily on first
-        // createSession — see createSession).
-        const dependencyAgents = resolveDependencyAgents();
-        const allIds = new Set([
-            ...this._softwareAgentConfigs.keys(),
-            ...dependencyAgents.keys(),
-        ]);
-        return [...allIds]
-            .map((id) => {
-            let config = this._resolveAgentConfig(id);
-            if (!config) {
-                // Dependency agent not linked yet — report it from its manifest.
-                const dependencyAgent = dependencyAgents.get(id);
-                if (!dependencyAgent)
-                    return null;
-                config = {
-                    adapterEntrypoint: `${OPT_AGENTOS_BIN}/${dependencyAgent.acpEntrypoint}`,
-                };
-            }
-            // An `/opt/agentos` agent package is materialized into the VM at
-            // boot, so it is always "installed" — its adapter is a real command.
-            if (config.adapterEntrypoint || !config.acpAdapter) {
-                return {
-                    id,
-                    adapterEntrypoint: config.adapterEntrypoint,
-                    installed: true,
-                };
-            }
-            let installed = false;
-            try {
-                // Check the software roots that provide this adapter package.
-                const vmPrefix = `/root/node_modules/${config.acpAdapter}`;
-                let hostPkgJsonPath = null;
-                for (const root of this._softwareRoots) {
-                    if (root.vmPath === vmPrefix) {
-                        hostPkgJsonPath = join(root.hostPath, "package.json");
-                        break;
-                    }
-                }
-                if (!hostPkgJsonPath) {
-                    throw new Error("no package source");
-                }
-                readFileSync(hostPkgJsonPath);
-                installed = true;
-            }
-            catch {
-                // Package not installed
-            }
-            return {
-                id,
-                acpAdapter: config.acpAdapter,
-                agentPackage: config.agentPackage,
-                installed,
-            };
-        })
-            .filter((entry) => entry !== null);
+    async providedCommands() {
+        return this._sidecarClient.providedCommands(this._sidecarSession, this._sidecarVm);
+    }
+    /**
+     * Returns all registered agents with their installation status. Thin forwarder:
+     * sends `AcpListAgentsRequest` and maps the response. The sidecar enumerates the
+     * 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() {
+        const response = await this._sendAcpRequest({
+            tag: "AcpListAgentsRequest",
+            val: { reserved: false },
+        });
+        if (response.tag !== "AcpListAgentsResponse") {
+            throw new Error(`unexpected list_agents response: ${response.tag}`);
+        }
+        return response.val.agents.map((agent) => ({
+            id: agent.id,
+            installed: agent.installed,
+            adapterEntrypoint: agent.adapterEntrypoint,
+        }));
     }
     _syncSessionState(session, state) {
         session.processId = state.processId;
@@ -2913,42 +2683,21 @@ export class AgentOs {
         this._syncSessionState(session, state);
     }
     async createSession(agentType, options) {
-        let config = this._resolveAgentConfig(agentType);
-        if (!config) {
-            // Lazily link an agent dependency on first use: agent packages are not
-            // projected by default (each carries a full node closure), so resolve
-            // the @agentos-software/* dep whose packed manifest name matches and
-            // link it into the running VM now. linkSoftware registers its
-            // entrypoint/env from the package's own agentos-package.json.
-            const dependencyAgent = resolveDependencyAgents().get(String(agentType));
-            if (dependencyAgent) {
-                await this.linkSoftware({ packageDir: dependencyAgent.packageDir });
-                config = this._resolveAgentConfig(agentType);
-            }
-        }
-        if (!config) {
-            throw new Error(`Unknown agent type: ${agentType}`);
-        }
-        // System-prompt assembly and injection (launch args / OPENCODE_CONTEXTPATHS) are owned by
-        // the sidecar at AcpCreateSessionRequest. The host only forwards additionalInstructions /
-        // skipOsInstructions plus the agent's static launch args and env.
-        const launchArgs = [...(config.launchArgs ?? [])];
-        const launchEnv = { ...config.defaultEnv, ...options?.env };
+        // 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";
-        // Every agent is an `/opt/agentos` package now: the config carries a
-        // pre-resolved guest command path (`adapterEntrypoint`) that the sidecar
-        // spawns directly. There is no npm adapter resolution.
-        const adapterEntrypoint = config.adapterEntrypoint;
-        if (!adapterEntrypoint) {
-            throw new Error(`agent "${String(agentType)}" config has no adapterEntrypoint`);
-        }
         const response = await this._sendAcpRequest({
             tag: "AcpCreateSessionRequest",
             val: {
                 agentType: String(agentType),
                 runtime: AcpRuntimeKind.JavaScript,
-                adapterEntrypoint,
-                args: launchArgs,
+                args: [],
                 env: new Map(Object.entries(launchEnv)),
                 cwd: sessionCwd,
                 mcpServers: JSON.stringify(options?.mcpServers ?? []),
@@ -3008,26 +2757,11 @@ export class AgentOs {
      * 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}`);
-        }
-        // Every agent is an `/opt/agentos` package now: the config carries a
-        // pre-resolved guest command path (`adapterEntrypoint`). There is no npm
-        // adapter resolution.
-        const adapterEntrypoint = config.adapterEntrypoint;
-        if (!adapterEntrypoint) {
-            throw new Error(`agent "${String(agentType)}" config has no adapterEntrypoint`);
-        }
+        // 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";
-        // 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.
-        const launchEnv = {
-            ...config.defaultEnv,
-            ...options?.env,
-            [RESUME_ADAPTER_ENTRYPOINT_ENV]: adapterEntrypoint,
-        };
+        const launchEnv = { ...options?.env };
         const response = await this._sendAcpRequest({
             tag: "AcpResumeSessionRequest",
             val: {
@@ -3578,14 +3312,6 @@ export class AgentOs {
             return "reject";
         }
     }
-    /**
-     * Resolve an agent config by ID. Agents are /opt/agentos packages
-     * registered from their manifests (explicit software at create, or lazily
-     * linked dependency agents) — there is no hardcoded fallback config.
-     */
-    _resolveAgentConfig(agentType) {
-        return this._softwareAgentConfigs.get(agentType);
-    }
     /**
      * Gracefully destroy a session: cancel any pending work, close the client,
      * and remove from tracking. Unlike close() which is abrupt, this attempts
@@ -3902,13 +3628,13 @@ function ensureSharedSidecarNativeProcess(sidecar) {
             // the spawned child is untracked, unreapable, and pins the loop).
             state.sharedChild = sidecarChildHandle(client);
             if (!state.sharedChild) {
-                // We reached into @secure-exec/core internals to get the child for
+                // We reached into @rivet-dev/agentos-runtime-core internals to get the child for
                 // idle-unref. If that shape ever changes this returns undefined and
                 // the optimization silently stops working (one-shot scripts would
                 // hang again). Make it loud rather than a silent regression.
                 console.warn("[agentos] could not resolve the shared sidecar child handle; " +
                     "standalone scripts may not exit cleanly after dispose(). " +
-                    "This usually means @secure-exec/core internals changed.");
+                    "This usually means @rivet-dev/agentos-runtime-core internals changed.");
             }
             // Apply the current hold state to the just-spawned child.
             applySharedSidecarHold(state);