@elizaos/agent 2.0.0-beta.1 → 2.0.11-beta.5

package/services/self-updater.js

@@ -0,0 +1,248 @@
+/**
+ * Detects the installation method and runs the appropriate upgrade command.
+ * Falls back to npm if detection is ambiguous.
+ */
+import { execSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CHANNEL_DIST_TAGS } from "./update-checker.js";
+const NPM_PACKAGE_NAME = "elizaos";
+function whichSync(binary) {
+    try {
+        return execSync(`which ${binary}`, {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+function isLocalDev() {
+    try {
+        const rootPkg = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+        const content = JSON.parse(fs.readFileSync(rootPkg, "utf-8"));
+        return content.devDependencies !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectInstallMethod() {
+    const elizaBin = whichSync("eliza");
+    if (!elizaBin) {
+        return isLocalDev() ? "local-dev" : "unknown";
+    }
+    let resolved;
+    try {
+        resolved = fs.realpathSync(elizaBin);
+    }
+    catch {
+        resolved = elizaBin;
+    }
+    if (resolved.includes("/Cellar/") || resolved.includes("/homebrew/"))
+        return "homebrew";
+    if (resolved.includes("/snap/"))
+        return "snap";
+    if (resolved.includes("/flatpak/") || resolved.includes("ai.eliza.Eliza"))
+        return "flatpak";
+    if (resolved.startsWith("/usr/") && !resolved.includes("node_modules"))
+        return "apt";
+    if (resolved.includes("/.bun/"))
+        return "bun-global";
+    if (resolved.includes("node_modules"))
+        return "npm-global";
+    return "unknown";
+}
+export function buildUpdateCommand(method, channel) {
+    const spec = `${NPM_PACKAGE_NAME}@${CHANNEL_DIST_TAGS[channel]}`;
+    switch (method) {
+        case "npm-global":
+            return {
+                command: "npm",
+                args: ["install", "-g", spec],
+                displayCommand: `npm install -g ${spec}`,
+            };
+        case "bun-global":
+            return {
+                command: "bun",
+                args: ["install", "-g", spec],
+                displayCommand: `bun install -g ${spec}`,
+            };
+        case "homebrew":
+            return {
+                command: "brew",
+                args: ["upgrade", "eliza"],
+                displayCommand: "brew upgrade eliza",
+            };
+        case "snap": {
+            // nightly → edge (snap doesn't have a "nightly" channel)
+            const snapCh = channel === "nightly" ? "edge" : channel === "beta" ? "beta" : "stable";
+            return {
+                command: "sudo",
+                args: ["snap", "refresh", "eliza", `--channel=${snapCh}`],
+                displayCommand: `sudo snap refresh eliza --channel=${snapCh}`,
+            };
+        }
+        case "apt":
+            return {
+                command: "sh",
+                args: [
+                    "-c",
+                    "sudo apt-get update && sudo apt-get install --only-upgrade -y eliza",
+                ],
+                displayCommand: "sudo apt-get update && sudo apt-get install --only-upgrade -y eliza",
+            };
+        case "flatpak":
+            return {
+                command: "flatpak",
+                args: ["update", "ai.eliza.Eliza"],
+                displayCommand: "flatpak update ai.eliza.Eliza",
+            };
+        case "local-dev":
+            return null;
+        case "unknown":
+            return {
+                command: "npm",
+                args: ["install", "-g", spec],
+                displayCommand: `npm install -g ${spec}`,
+            };
+    }
+}
+function getUpdateAuthority(method) {
+    switch (method) {
+        case "npm-global":
+        case "bun-global":
+        case "homebrew":
+            return "package-manager";
+        case "apt":
+        case "snap":
+        case "flatpak":
+            return "os-package-manager";
+        case "local-dev":
+            return "developer";
+        case "unknown":
+            return "operator";
+    }
+}
+function getUpdateMessage(method, command, remoteDisplay) {
+    if (remoteDisplay) {
+        if (method === "local-dev") {
+            return "This is a remote status view. Update the checkout on the host with git pull; no remote execution endpoint is exposed.";
+        }
+        if (command) {
+            return `This is a remote status view. Run "${command}" on the host; no remote execution endpoint is exposed.`;
+        }
+        return "This is a remote status view. Review the host installation; no remote execution endpoint is exposed.";
+    }
+    switch (method) {
+        case "local-dev":
+            return "Local development install detected. Update the checkout with git pull.";
+        case "unknown":
+            return "Install method is unknown. The CLI will fall back to npm, but reviewing the installation first is recommended.";
+        case "apt":
+        case "snap":
+        case "flatpak":
+            return "Updates are delegated to the OS package manager and must run on the host.";
+        case "npm-global":
+        case "bun-global":
+        case "homebrew":
+            return "Updates are delegated to the detected package manager.";
+    }
+}
+export function getUpdateActionPlan(method, channel, options) {
+    const remoteDisplay = options?.remoteDisplay ?? false;
+    const cmdInfo = buildUpdateCommand(method, channel);
+    const command = cmdInfo?.displayCommand ?? (method === "local-dev" ? "git pull" : null);
+    const canAutoUpdate = method !== "local-dev" && cmdInfo !== null;
+    const nextAction = method === "local-dev"
+        ? "run-git-pull"
+        : method === "unknown"
+            ? "review-installation"
+            : cmdInfo
+                ? "run-package-manager-command"
+                : "none";
+    return {
+        method,
+        authority: getUpdateAuthority(method),
+        nextAction,
+        canAutoUpdate,
+        canExecuteFromContext: canAutoUpdate && !remoteDisplay,
+        remoteDisplay,
+        command,
+        message: getUpdateMessage(method, command, remoteDisplay),
+    };
+}
+function runCommand(command, args) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            stdio: ["inherit", "inherit", "pipe"],
+            // shell:true removed — all update commands are safe to run directly.
+            // The apt case uses sh -c explicitly, so no shell wrapper is needed.
+        });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+            process.stderr.write(chunk);
+        });
+        child.on("error", (err) => {
+            resolve({ exitCode: 1, stderr: err.message });
+        });
+        child.on("close", (code) => {
+            resolve({ exitCode: code ?? 1, stderr });
+        });
+    });
+}
+function readPostUpdateVersion() {
+    try {
+        const output = execSync("eliza --version", {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+        })
+            .toString()
+            .trim();
+        // Version output may include a prefix like "eliza/2.0.0"
+        const match = output.match(/(\d+\.\d+\.\d+(?:-[\w.]+)?)/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function performUpdate(currentVersion, channel, method) {
+    method ??= detectInstallMethod();
+    const cmdInfo = buildUpdateCommand(method, channel);
+    if (!cmdInfo) {
+        return {
+            success: false,
+            method,
+            command: "",
+            previousVersion: currentVersion,
+            newVersion: null,
+            error: "Cannot auto-update a local development install. Use git pull instead.",
+        };
+    }
+    const commandString = cmdInfo.displayCommand;
+    const { exitCode, stderr } = await runCommand(cmdInfo.command, cmdInfo.args);
+    if (exitCode !== 0) {
+        return {
+            success: false,
+            method,
+            command: commandString,
+            previousVersion: currentVersion,
+            newVersion: null,
+            error: stderr || `Update command exited with code ${exitCode}.`,
+        };
+    }
+    return {
+        success: true,
+        method,
+        command: commandString,
+        previousVersion: currentVersion,
+        newVersion: readPostUpdateVersion(),
+        error: null,
+    };
+}

package/services/send-handler-availability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-handler-availability.d.ts","sourceRoot":"","sources":["../../src/services/send-handler-availability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,eAAe,CAAC;AAQ3D,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAST;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,IAAI,CASN;AAED,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D"}

package/services/send-handler-availability.js

@@ -0,0 +1,23 @@
+import { logger } from "@elizaos/core";
+const missingSendHandlerLogs = new Set();
+export function hasRuntimeSendHandler(runtime, source) {
+    const sendHandlers = runtime.sendHandlers;
+    if (!(sendHandlers instanceof Map)) {
+        // The handler registry could not be introspected. This gates whether we
+        // attempt delivery, so treat an unknown registry as "no handler" — skip
+        // and log rather than asserting availability we can't verify.
+        return false;
+    }
+    return sendHandlers.has(source);
+}
+export function logMissingSendHandlerOnce(context, source) {
+    const key = `${context}:${source}`;
+    if (missingSendHandlerLogs.has(key)) {
+        return;
+    }
+    missingSendHandlerLogs.add(key);
+    logger.info(`[${context}] Send handler "${source}" is not registered yet; skipping delivery until runtime wiring completes`);
+}
+export function _resetMissingSendHandlerLogsForTests() {
+    missingSendHandlerLogs.clear();
+}

package/services/shell-execution-router.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Single chokepoint for shell execution.
+ *
+ * The runtime has a 3-mode switch via `ELIZA_RUNTIME_MODE`:
+ *  - `cloud`        — agent code runs in the hosted backend; local exec is
+ *                     refused with a clear error.
+ *  - `local-safe`   — every shell exec is routed through `SandboxManager`
+ *                     (Docker / Apple Container) so the host filesystem is
+ *                     not directly touched.
+ *  - `local-yolo`   — direct host exec (the historical default).
+ *
+ * Plugins, services, and CLI helpers that previously called `child_process.spawn`
+ * for one-shot command execution should call `runShell()` instead. This keeps
+ * the mode dispatch in one place and lets the privacy/sandbox guarantees of
+ * `local-safe` actually hold.
+ */
+import { type RuntimeExecutionMode } from "@elizaos/shared";
+import type { SandboxManager } from "./sandbox-manager.ts";
+export type ShellExecutionMode = RuntimeExecutionMode;
+export type ShellSandboxBackend = "host" | "docker" | "apple-container" | "wsl2" | "appcontainer" | "vfs" | "none";
+export interface ShellRequest {
+    command: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    /** Caller identity for audit trails. Required so logs are traceable. */
+    toolName: string;
+}
+export interface ShellResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    sandbox: ShellSandboxBackend;
+}
+export interface ShellRouterContext {
+    /** Explicit override for the active mode. When unset, env vars are read. */
+    mode?: ShellExecutionMode;
+    /** Runtime-style settings source consulted before falling back to env. */
+    runtime?: {
+        getSetting?: (key: string) => unknown;
+    } | null;
+    /** Optional pre-resolved sandbox manager (used by tests + agent code paths). */
+    sandboxManager?: SandboxManager | null;
+    /**
+     * Lazy provider for SandboxManager. Awaited only when local-safe is active,
+     * so callers in local-yolo mode never pay for sandbox-engine imports.
+     */
+    resolveSandboxManager?: () => Promise<SandboxManager | null>;
+}
+export declare function resolveShellExecutionMode(ctx?: Pick<ShellRouterContext, "mode" | "runtime"> | null): ShellExecutionMode;
+/** Test-only escape hatch — drops the cached router broker. */
+export declare function __resetShellRouterBrokerForTests(): void;
+/**
+ * Single entry point for one-shot shell execution. Mode dispatch:
+ *   - `cloud`      → throws.
+ *   - `local-safe` → routed through SandboxManager.run; if no manager is
+ *                    available the call throws so callers cannot silently
+ *                    fall back to the host.
+ *   - `local-yolo` → direct host exec via child_process.spawn.
+ *
+ * Platform support is determined by the resolved SandboxManager backend; the
+ * router does not silently downgrade `local-safe` to host execution.
+ */
+export declare function runShell(req: ShellRequest, ctx?: ShellRouterContext | null): Promise<ShellResult>;
+//# sourceMappingURL=shell-execution-router.d.ts.map

package/services/shell-execution-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-execution-router.d.ts","sourceRoot":"","sources":["../../src/services/shell-execution-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEtD,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,QAAQ,GACR,iBAAiB,GACjB,MAAM,GACN,cAAc,GACd,KAAK,GACL,MAAM,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,0EAA0E;IAC1E,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3D,gFAAgF;IAChF,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC9D;AAOD,wBAAgB,yBAAyB,CACvC,GAAG,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,GACxD,kBAAkB,CAGpB;AA0CD,+DAA+D;AAC/D,wBAAgB,gCAAgC,IAAI,IAAI,CAGvD;AA+OD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,YAAY,EACjB,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAC9B,OAAO,CAAC,WAAW,CAAC,CAuDtB"}

package/services/shell-execution-router.js

@@ -0,0 +1,329 @@
+/**
+ * Single chokepoint for shell execution.
+ *
+ * The runtime has a 3-mode switch via `ELIZA_RUNTIME_MODE`:
+ *  - `cloud`        — agent code runs in the hosted backend; local exec is
+ *                     refused with a clear error.
+ *  - `local-safe`   — every shell exec is routed through `SandboxManager`
+ *                     (Docker / Apple Container) so the host filesystem is
+ *                     not directly touched.
+ *  - `local-yolo`   — direct host exec (the historical default).
+ *
+ * Plugins, services, and CLI helpers that previously called `child_process.spawn`
+ * for one-shot command execution should call `runShell()` instead. This keeps
+ * the mode dispatch in one place and lets the privacy/sandbox guarantees of
+ * `local-safe` actually hold.
+ */
+import { spawn } from "node:child_process";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { resolveRuntimeExecutionMode, } from "@elizaos/shared";
+import { CapabilityBroker } from "./capability-broker.js";
+import { isVfsUri, runVfsBuiltinShell } from "./vfs-builtin-shell.js";
+import { createVirtualFilesystemService } from "./virtual-filesystem.js";
+export function resolveShellExecutionMode(ctx) {
+    if (ctx?.mode)
+        return ctx.mode;
+    return resolveRuntimeExecutionMode(ctx?.runtime ?? null);
+}
+function backendForSandboxManager(manager) {
+    // "auto" only appears in config; a constructed engine is always concrete.
+    const engineType = manager.engineType;
+    if (engineType === "docker")
+        return "docker";
+    if (engineType === "apple-container")
+        return "apple-container";
+    return "none";
+}
+async function resolveSandboxManager(ctx) {
+    if (ctx?.sandboxManager !== undefined)
+        return ctx.sandboxManager;
+    if (ctx?.resolveSandboxManager)
+        return await ctx.resolveSandboxManager();
+    return null;
+}
+// Router-scoped broker so the shell.exec policy is driven by the same mode
+// resolver runShell uses for dispatch. The broker singleton in
+// capability-broker.ts hardcodes `local-safe` as its default mode, which is
+// correct for cloud-side callers but wrong for host-side runShell — those
+// must follow ELIZA_RUNTIME_MODE/RUNTIME_MODE/LOCAL_RUNTIME_MODE. The
+// internal mutable holder lets the broker re-read mode on every call without
+// constructing a new CapabilityBroker per runShell invocation.
+const routerModeHolder = {
+    current: "local-yolo",
+};
+let cachedRouterBroker = null;
+function getRouterBroker(modeSource) {
+    routerModeHolder.current = modeSource();
+    if (cachedRouterBroker)
+        return cachedRouterBroker;
+    cachedRouterBroker = new CapabilityBroker({
+        mode: () => routerModeHolder.current,
+    });
+    return cachedRouterBroker;
+}
+/** Test-only escape hatch — drops the cached router broker. */
+export function __resetShellRouterBrokerForTests() {
+    cachedRouterBroker = null;
+    routerModeHolder.current = "local-yolo";
+}
+async function runOnHost(req) {
+    const start = Date.now();
+    return await new Promise((resolve) => {
+        const timeoutMs = req.timeoutMs ?? 30_000;
+        const useDetachedProcessGroup = process.platform !== "win32";
+        const child = spawn(req.command, req.args.slice(), {
+            cwd: req.cwd,
+            env: req.env ? { ...process.env, ...req.env } : process.env,
+            detached: useDetachedProcessGroup,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const killChildTree = () => {
+            try {
+                if (useDetachedProcessGroup && child.pid !== undefined) {
+                    process.kill(-child.pid, "SIGKILL");
+                    return;
+                }
+            }
+            catch {
+                // Fall back to killing the direct child below.
+            }
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // child may already have exited
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killChildTree();
+        }, timeoutMs);
+        if (typeof timer.unref === "function")
+            timer.unref();
+        child.stdout.on("data", (chunk) => {
+            const text = chunk.toString("utf8");
+            stdout += text;
+            req.onStdout?.(text);
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString("utf8");
+            stderr += text;
+            req.onStderr?.(text);
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: -1,
+                stdout,
+                stderr: stderr.length > 0 ? `${stderr}\n${err.message}` : err.message,
+                durationMs: Date.now() - start,
+                sandbox: "host",
+            });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            const exitCode = timedOut ? 124 : (code ?? -1);
+            resolve({
+                exitCode,
+                stdout,
+                stderr: timedOut
+                    ? `${stderr}${stderr.endsWith("\n") || stderr.length === 0 ? "" : "\n"}[shell-router] command timed out after ${timeoutMs}ms`
+                    : stderr,
+                durationMs: Date.now() - start,
+                sandbox: "host",
+            });
+        });
+    });
+}
+async function runInSandbox(req, manager) {
+    const result = await manager.run({
+        cmd: req.command,
+        args: req.args,
+        workdir: req.cwd,
+        env: req.env,
+        timeoutMs: req.timeoutMs,
+    });
+    if (result.stdout)
+        req.onStdout?.(result.stdout);
+    if (result.stderr)
+        req.onStderr?.(result.stderr);
+    return {
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        durationMs: result.durationMs,
+        sandbox: backendForSandboxManager(manager),
+    };
+}
+async function runVfsInSandbox(req, cwd, manager) {
+    const workspaceRoot = manager.getWorkspaceRoot();
+    if (!workspaceRoot) {
+        throw new Error("[shell-router] VFS sandbox execution requires SandboxManager.getWorkspaceRoot()");
+    }
+    const vfs = createVirtualFilesystemService({ projectId: cwd.projectId });
+    await vfs.initialize();
+    const normalizedCwd = vfs.resolveVirtualPath(cwd.virtualPath);
+    const materializedRoot = path.join(workspaceRoot, "vfs-projects", vfs.projectId, "files");
+    await fsp.rm(materializedRoot, { recursive: true, force: true });
+    await fsp.mkdir(materializedRoot, { recursive: true, mode: 0o700 });
+    await materializeVfsTree(vfs, materializedRoot);
+    const hostCwd = path.resolve(materializedRoot, normalizedCwd.replace(/^\/+/, ""));
+    if (!isInsideOrEqual(materializedRoot, hostCwd)) {
+        throw new Error("[shell-router] vfs:// cwd escapes materialized root");
+    }
+    await fsp.mkdir(hostCwd, { recursive: true, mode: 0o700 });
+    const sandboxCwd = manager.getContainerWorkspacePath(hostCwd) ??
+        `/workspace/${path
+            .relative(workspaceRoot, hostCwd)
+            .replace(/\\/g, "/")
+            .replace(/^\/+/, "")}`;
+    try {
+        return await runInSandbox({
+            ...req,
+            cwd: sandboxCwd,
+        }, manager);
+    }
+    finally {
+        await importMaterializedTree(vfs, materializedRoot);
+    }
+}
+async function materializeVfsTree(vfs, root) {
+    for (const file of await vfs.exportFiles()) {
+        const target = path.resolve(root, file.path.replace(/^\/+/, ""));
+        if (!isInsideOrEqual(root, target)) {
+            throw new Error(`[shell-router] VFS export path escapes materialized root: ${file.path}`);
+        }
+        await fsp.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+        await fsp.writeFile(target, file.bytes, { mode: 0o600 });
+    }
+}
+async function importMaterializedTree(vfs, root) {
+    const nextFiles = new Map();
+    await walkMaterialized(root, root, nextFiles);
+    const currentFiles = await vfs.exportFiles();
+    for (const file of currentFiles) {
+        const normalized = file.path.replace(/^\/+/, "");
+        if (!nextFiles.has(normalized)) {
+            await vfs.delete(normalized);
+        }
+    }
+    for (const [virtualPath, bytes] of nextFiles) {
+        await vfs.writeFile(virtualPath, bytes);
+    }
+}
+async function walkMaterialized(root, dir, files) {
+    let entries;
+    try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const entry of entries) {
+        const absolute = path.join(dir, entry.name);
+        if (entry.isSymbolicLink()) {
+            throw new Error(`VFS sandbox import rejects symlink: ${absolute}`);
+        }
+        if (entry.isDirectory()) {
+            await walkMaterialized(root, absolute, files);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const virtualPath = path.relative(root, absolute).replace(/\\/g, "/");
+        files.set(virtualPath, await fsp.readFile(absolute));
+    }
+}
+function parseVfsShellCwd(value) {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "vfs:" || !parsed.hostname) {
+        throw new Error(`Invalid VFS uri: ${value}`);
+    }
+    return {
+        projectId: parsed.hostname,
+        virtualPath: decodeURIComponent(parsed.pathname || "/"),
+    };
+}
+function assertShellCapability(req, mode, toolName) {
+    const decision = getRouterBroker(() => mode).check({
+        kind: "shell",
+        op: "exec",
+        target: req.command,
+        toolName,
+    });
+    if (decision.allowed !== true) {
+        throw new Error(`[shell] capability denied: ${decision.reason}`);
+    }
+}
+/**
+ * Single entry point for one-shot shell execution. Mode dispatch:
+ *   - `cloud`      → throws.
+ *   - `local-safe` → routed through SandboxManager.run; if no manager is
+ *                    available the call throws so callers cannot silently
+ *                    fall back to the host.
+ *   - `local-yolo` → direct host exec via child_process.spawn.
+ *
+ * Platform support is determined by the resolved SandboxManager backend; the
+ * router does not silently downgrade `local-safe` to host execution.
+ */
+export async function runShell(req, ctx) {
+    if (!req.command || req.command.length === 0) {
+        throw new Error("[shell-router] runShell requires a non-empty command");
+    }
+    if (!req.toolName || req.toolName.length === 0) {
+        throw new Error("[shell-router] runShell requires toolName for audit");
+    }
+    const mode = resolveShellExecutionMode(ctx);
+    if (mode === "cloud") {
+        throw new Error("Local shell execution disabled in cloud mode.");
+    }
+    if (isVfsUri(req.cwd)) {
+        const vfsCwd = parseVfsShellCwd(req.cwd);
+        if (mode === "local-yolo") {
+            throw new Error("[shell-router] local-yolo uses the normal host filesystem; pass a real cwd path instead of vfs://");
+        }
+        const manager = await resolveSandboxManager(ctx);
+        if (manager) {
+            assertShellCapability(req, mode, `sandbox.${req.toolName}`);
+            return await runVfsInSandbox(req, vfsCwd, manager);
+        }
+        if (mode === "local-safe" && !isIosPlatform()) {
+            throw new Error("[shell-router] local-safe mode requires SandboxManager but none is available");
+        }
+        const result = await runVfsBuiltinShell({
+            cwdUri: req.cwd,
+            command: req.command,
+            args: req.args,
+            ...(req.timeoutMs ? { timeoutMs: req.timeoutMs } : {}),
+        });
+        if (result.stdout)
+            req.onStdout?.(result.stdout);
+        if (result.stderr)
+            req.onStderr?.(result.stderr);
+        return result;
+    }
+    if (mode === "local-safe") {
+        assertShellCapability(req, mode, `sandbox.${req.toolName}`);
+        const manager = await resolveSandboxManager(ctx);
+        if (!manager) {
+            throw new Error("[shell-router] local-safe mode requires SandboxManager but none is available");
+        }
+        return await runInSandbox(req, manager);
+    }
+    assertShellCapability(req, mode, req.toolName);
+    return await runOnHost(req);
+}
+function isInsideOrEqual(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return (!relative || (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+function isIosPlatform() {
+    return process.env.ELIZA_PLATFORM?.trim().toLowerCase() === "ios";
+}