@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.2

package/packages/agent/src/services/sandbox-manager.d.ts

@@ -1,5 +1,5 @@
 /** Sandbox container lifecycle: create, exec, health check, teardown. */
-import { type SandboxEngineType } from "./sandbox-engine";
+import { type SandboxEngineType } from "./sandbox-engine.ts";
 export type SandboxMode = "off" | "light" | "standard" | "max";
 export type SandboxState = "uninitialized" | "initializing" | "ready" | "degraded" | "stopping" | "stopped" | "recovering";
 export interface SandboxManagerConfig {
@@ -62,6 +62,19 @@ export interface SandboxExecResult {
     durationMs: number;
     executedInSandbox: boolean;
 }
+export interface SandboxRunOptions {
+    cmd: string;
+    args: readonly string[];
+    workdir?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    stdin?: string;
+    /**
+     * Override sandbox image. Currently informational; the manager runs commands
+     * in the long-lived container provisioned at start(), not a per-call image.
+     */
+    image?: string;
+}
 export interface SandboxEvent {
     timestamp: number;
     type: "state_change" | "exec" | "exec_denied" | "container_start" | "container_stop" | "health_check" | "error";
@@ -75,6 +88,7 @@ export declare class SandboxManager {
     private containerId;
     private browserContainerId;
     private eventLog;
+    private lifecycleQueue;
     constructor(config: SandboxManagerConfig);
     getState(): SandboxState;
     getMode(): SandboxMode;
@@ -83,10 +97,19 @@ export declare class SandboxManager {
     private createMainContainer;
     private cleanupContainer;
     private setState;
+    private queueLifecycle;
     start(): Promise<void>;
     recover(): Promise<void>;
     stop(): Promise<void>;
     exec(options: SandboxExecOptions): Promise<SandboxExecResult>;
+    /**
+     * Argv-aware variant of {@link exec}. Builds a properly-quoted command
+     * string from `cmd` + `args` and forwards to the underlying engine. Use
+     * this from the shell-execution router so callers that already have
+     * argv-shaped requests don't have to re-quote and risk shell-injection
+     * mismatches.
+     */
+    run(options: SandboxRunOptions): Promise<SandboxExecResult>;
     getBrowserCdpEndpoint(): string | null;
     getBrowserWsEndpoint(): string | null;
     getBrowserNoVncEndpoint(): string | null;

package/packages/agent/src/services/sandbox-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/sandbox-manager.ts"],"names":[],"mappings":"AAAA,yEAAyE;AAKzE,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,CAAC;AAE/D,MAAM,MAAM,YAAY,GACpB,eAAe,GACf,cAAc,GACd,OAAO,GACP,UAAU,GACV,UAAU,GACV,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,oBAAoB;IACnC,oBAAoB;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,mBAAmB;IACnB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,+EAA+E;IAC/E,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,gCAAgC;IAChC,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EACA,cAAc,GACd,MAAM,GACN,aAAa,GACb,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACtD;AAID,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAsB;gBAE1B,MAAM,EAAE,oBAAoB;IAkBxC,QAAQ,IAAI,YAAY;IAIxB,OAAO,IAAI,WAAW;IAItB,OAAO,IAAI,OAAO;IAIlB,OAAO,CAAC,sBAAsB;YAwBhB,mBAAmB;YAqBnB,gBAAgB;IAM9B,OAAO,CAAC,QAAQ;IAUV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiFtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2CxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBrB,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA8DnE,qBAAqB,IAAI,MAAM,GAAG,IAAI;IAMtC,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAMrC,uBAAuB,IAAI,MAAM,GAAG,IAAI;YAW1B,sBAAsB;YAmCtB,WAAW;IAWzB,OAAO,CAAC,SAAS;IAQjB,WAAW,IAAI,YAAY,EAAE;IAI7B,SAAS,IAAI;QACX,KAAK,EAAE,YAAY,CAAC;QACpB,IAAI,EAAE,WAAW,CAAC;QAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;KACnC;CAQF"}
+{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/sandbox-manager.ts"],"names":[],"mappings":"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"}

package/packages/agent/src/services/sandbox-manager.js

@@ -2,7 +2,20 @@
 import { mkdirSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
-import { createEngine, detectBestEngine, } from "./sandbox-engine";
+import { createEngine, detectBestEngine, } from "./sandbox-engine.js";
+/**
+ * Quote a single argv token using POSIX single-quote rules so the engine's
+ * string-based command parser round-trips it back to exactly one argument.
+ * Single-quoted strings preserve every character except `'`, which is encoded
+ * as the standard `'\''` sequence.
+ */
+function shQuote(token) {
+    if (token.length === 0)
+        return "''";
+    if (/^[A-Za-z0-9_+\-./=:@%]+$/.test(token))
+        return token;
+    return `'${token.replace(/'/g, "'\\''")}'`;
+}
 // ── Implementation ───────────────────────────────────────────────────────────
 export class SandboxManager {
     state = "uninitialized";
@@ -11,6 +24,7 @@ export class SandboxManager {
     containerId = null;
     browserContainerId = null;
     eventLog = [];
+    lifecycleQueue = Promise.resolve();
     constructor(config) {
         this.config = {
             image: "eliza-sandbox:bookworm-slim",
@@ -83,131 +97,157 @@ export class SandboxManager {
             detail: `${oldState} → ${newState}`,
         });
     }
+    queueLifecycle(operation) {
+        const run = this.lifecycleQueue.then(operation, operation);
+        this.lifecycleQueue = run.then(() => undefined, () => undefined);
+        return run;
+    }
     async start() {
-        if (this.config.mode === "off") {
-            this.setState("stopped");
-            return;
-        }
-        if (this.config.mode === "light") {
-            // Light mode: no container, just tokenization + fetch proxy
-            this.setState("ready");
-            return;
-        }
-        // Standard / Max: create container
-        this.setState("initializing");
-        try {
-            const config = this.getMainContainerConfig();
-            if (!this.engine.isAvailable()) {
-                throw new Error(`Container engine "${this.engine.engineType}" is not available. Install Docker or Apple Container.`);
-            }
-            if (!this.engine.imageExists(config.image)) {
-                try {
-                    await this.engine.pullImage(config.image);
+        return await this.queueLifecycle(async () => {
+            if (this.config.mode === "off") {
+                if (this.state !== "stopped") {
+                    this.setState("stopped");
                 }
-                catch {
-                    throw new Error(`Sandbox image "${config.image}" not found. Build with: scripts/sandbox-setup.sh`);
+                return;
+            }
+            if (this.config.mode === "light") {
+                if (this.state !== "ready") {
+                    this.setState("ready");
                 }
+                return;
             }
-            // Cleanup orphans from previous runs
-            const orphans = this.engine.listContainers(config.containerPrefix);
-            for (const id of orphans) {
-                await this.engine.stopContainer(id);
-                await this.engine.removeContainer(id);
+            if (this.state === "ready" ||
+                this.state === "initializing" ||
+                this.state === "recovering") {
+                return;
             }
-            this.containerId = await this.createMainContainer();
-            this.emitEvent({
-                timestamp: Date.now(),
-                type: "container_start",
-                detail: `Container started: ${this.containerId}`,
-            });
-            // Start browser container if configured
-            if (this.config.browser?.enabled && this.config.browser?.autoStart) {
-                try {
-                    this.browserContainerId = await this.createBrowserContainer();
+            // Standard / Max: create container
+            this.setState("initializing");
+            try {
+                const config = this.getMainContainerConfig();
+                if (!this.engine.isAvailable()) {
+                    throw new Error(`Container engine "${this.engine.engineType}" is not available. Install Docker or Apple Container.`);
                 }
-                catch (err) {
-                    this.emitEvent({
-                        timestamp: Date.now(),
-                        type: "error",
-                        detail: `Browser container start failed: ${err instanceof Error ? err.message : String(err)}`,
-                    });
-                    // Non-fatal: sandbox can work without browser
+                if (!this.engine.imageExists(config.image)) {
+                    try {
+                        await this.engine.pullImage(config.image);
+                    }
+                    catch {
+                        throw new Error(`Sandbox image "${config.image}" not found. Build with: scripts/sandbox-setup.sh`);
+                    }
+                }
+                // Cleanup orphans from previous runs
+                const orphans = this.engine.listContainers(config.containerPrefix);
+                for (const id of orphans) {
+                    await this.engine.stopContainer(id);
+                    await this.engine.removeContainer(id);
+                }
+                this.containerId = await this.createMainContainer();
+                this.emitEvent({
+                    timestamp: Date.now(),
+                    type: "container_start",
+                    detail: `Container started: ${this.containerId}`,
+                });
+                // Start browser container if configured
+                if (this.config.browser?.enabled && this.config.browser?.autoStart) {
+                    try {
+                        this.browserContainerId = await this.createBrowserContainer();
+                    }
+                    catch (err) {
+                        this.emitEvent({
+                            timestamp: Date.now(),
+                            type: "error",
+                            detail: `Browser container start failed: ${String(err)}`,
+                        });
+                        // Non-fatal: sandbox can work without browser
+                    }
+                }
+                // Health check
+                const healthy = await this.healthCheck();
+                if (healthy) {
+                    this.setState("ready");
+                }
+                else {
+                    this.setState("degraded");
                 }
             }
-            // Health check
-            const healthy = await this.healthCheck();
-            if (healthy) {
-                this.setState("ready");
-            }
-            else {
+            catch (err) {
+                this.emitEvent({
+                    timestamp: Date.now(),
+                    type: "error",
+                    detail: `Sandbox start failed: ${String(err)}`,
+                });
                 this.setState("degraded");
+                throw err;
             }
-        }
-        catch (err) {
-            this.emitEvent({
-                timestamp: Date.now(),
-                type: "error",
-                detail: `Sandbox start failed: ${err instanceof Error ? err.message : String(err)}`,
-            });
-            this.setState("degraded");
-            throw err;
-        }
+        });
     }
     async recover() {
-        if (this.state !== "degraded") {
-            return; // Only recover from degraded
-        }
-        this.setState("recovering");
-        this.emitEvent({
-            timestamp: Date.now(),
-            type: "state_change",
-            detail: "Attempting recovery from degraded state",
-        });
-        try {
-            const config = this.getMainContainerConfig();
-            await this.cleanupContainer(this.containerId);
-            await this.cleanupContainer(this.browserContainerId);
-            this.containerId = null;
-            this.browserContainerId = null;
-            const orphans = this.engine.listContainers(config.containerPrefix);
-            for (const id of orphans) {
-                await this.engine.stopContainer(id);
-                await this.engine.removeContainer(id);
-            }
-            this.containerId = await this.createMainContainer();
-            const healthy = await this.healthCheck();
-            if (healthy) {
-                this.setState("ready");
+        return await this.queueLifecycle(async () => {
+            if (this.state !== "degraded") {
+                return; // Only recover from degraded
             }
-            else {
-                this.setState("degraded");
-            }
-        }
-        catch (err) {
+            this.setState("recovering");
             this.emitEvent({
                 timestamp: Date.now(),
-                type: "error",
-                detail: `Recovery failed: ${err instanceof Error ? err.message : String(err)}`,
+                type: "state_change",
+                detail: "Attempting recovery from degraded state",
             });
-            this.setState("degraded");
-        }
+            try {
+                const config = this.getMainContainerConfig();
+                await this.cleanupContainer(this.containerId);
+                await this.cleanupContainer(this.browserContainerId);
+                this.containerId = null;
+                this.browserContainerId = null;
+                const orphans = this.engine.listContainers(config.containerPrefix);
+                for (const id of orphans) {
+                    await this.engine.stopContainer(id);
+                    await this.engine.removeContainer(id);
+                }
+                this.containerId = await this.createMainContainer();
+                const healthy = await this.healthCheck();
+                if (healthy) {
+                    this.setState("ready");
+                }
+                else {
+                    this.setState("degraded");
+                }
+            }
+            catch (err) {
+                this.emitEvent({
+                    timestamp: Date.now(),
+                    type: "error",
+                    detail: `Recovery failed: ${String(err)}`,
+                });
+                this.setState("degraded");
+            }
+        });
     }
     async stop() {
-        this.setState("stopping");
-        try {
-            await this.cleanupContainer(this.browserContainerId);
-            await this.cleanupContainer(this.containerId);
-            this.browserContainerId = null;
-            this.containerId = null;
-        }
-        catch (err) {
-            this.emitEvent({
-                timestamp: Date.now(),
-                type: "error",
-                detail: `Sandbox stop error: ${err instanceof Error ? err.message : String(err)}`,
-            });
-        }
-        this.setState("stopped");
+        return await this.queueLifecycle(async () => {
+            if (this.state === "stopped") {
+                return;
+            }
+            if (this.state === "uninitialized") {
+                this.setState("stopped");
+                return;
+            }
+            this.setState("stopping");
+            try {
+                await this.cleanupContainer(this.browserContainerId);
+                await this.cleanupContainer(this.containerId);
+                this.browserContainerId = null;
+                this.containerId = null;
+            }
+            catch (err) {
+                this.emitEvent({
+                    timestamp: Date.now(),
+                    type: "error",
+                    detail: `Sandbox stop error: ${String(err)}`,
+                });
+            }
+            this.setState("stopped");
+        });
     }
     async exec(options) {
         const start = Date.now();
@@ -258,15 +298,40 @@ export class SandboxManager {
             };
         }
         catch (err) {
+            this.emitEvent({
+                timestamp: Date.now(),
+                type: "error",
+                detail: `Sandbox exec failed: ${String(err)}`,
+                metadata: {
+                    command: options.command.substring(0, 200),
+                },
+            });
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Exec error: ${err instanceof Error ? err.message : String(err)}`,
+                stderr: `Exec error: ${String(err)}`,
                 durationMs: Date.now() - start,
                 executedInSandbox: false,
             };
         }
     }
+    /**
+     * Argv-aware variant of {@link exec}. Builds a properly-quoted command
+     * string from `cmd` + `args` and forwards to the underlying engine. Use
+     * this from the shell-execution router so callers that already have
+     * argv-shaped requests don't have to re-quote and risk shell-injection
+     * mismatches.
+     */
+    async run(options) {
+        const tokens = [options.cmd, ...options.args].map(shQuote).join(" ");
+        return this.exec({
+            command: tokens,
+            workdir: options.workdir,
+            env: options.env,
+            timeoutMs: options.timeoutMs,
+            stdin: options.stdin,
+        });
+    }
     getBrowserCdpEndpoint() {
         if (!this.browserContainerId)
             return null;

package/packages/agent/src/services/self-updater.d.ts

@@ -2,7 +2,7 @@
  * Detects the installation method and runs the appropriate upgrade command.
  * Falls back to npm if detection is ambiguous.
  */
-import type { ReleaseChannel } from "../config/types.eliza";
+import type { ReleaseChannel } from "../config/types.eliza.ts";
 export type InstallMethod = "npm-global" | "bun-global" | "homebrew" | "snap" | "apt" | "flatpak" | "local-dev" | "unknown";
 export interface UpdateResult {
     success: boolean;

package/packages/agent/src/services/self-updater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-updater.d.ts","sourceRoot":"","sources":["../../../../../src/services/self-updater.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,MAAM,GACN,KAAK,GACL,SAAS,GACT,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AA8BD,wBAAgB,mBAAmB,IAAI,aAAa,CAyBnD;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,cAAc,GACtB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAkC5C;AA6CD,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAsCvB"}
+{"version":3,"file":"self-updater.d.ts","sourceRoot":"","sources":["../../../../../src/services/self-updater.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAK/D,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,MAAM,GACN,KAAK,GACL,SAAS,GACT,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AA8BD,wBAAgB,mBAAmB,IAAI,aAAa,CAyBnD;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,cAAc,GACtB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAkC5C;AA6CD,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAsCvB"}

package/packages/agent/src/services/self-updater.js

@@ -6,7 +6,7 @@ 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";
+import { CHANNEL_DIST_TAGS } from "./update-checker.js";
 const NPM_PACKAGE_NAME = "elizaos";
 function whichSync(binary) {
     try {

package/packages/agent/src/services/send-handler-availability.d.ts

@@ -0,0 +1,5 @@
+import { type IAgentRuntime } from "@elizaos/core";
+export declare function hasRuntimeSendHandler(runtime: IAgentRuntime, source: string): boolean;
+export declare function logMissingSendHandlerOnce(context: string, source: string): void;
+export declare function _resetMissingSendHandlerLogsForTests(): void;
+//# sourceMappingURL=send-handler-availability.d.ts.map

package/packages/agent/src/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,CAMT;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,IAAI,CASN;AAED,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D"}

package/packages/agent/src/services/send-handler-availability.js

@@ -0,0 +1,20 @@
+import { logger } from "@elizaos/core";
+const missingSendHandlerLogs = new Set();
+export function hasRuntimeSendHandler(runtime, source) {
+    const sendHandlers = runtime.sendHandlers;
+    if (!(sendHandlers instanceof Map)) {
+        return true;
+    }
+    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/packages/agent/src/services/shell-execution-router.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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" | "none";
+export interface ShellRequest {
+    command: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    /** 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.
+ *
+ * On Windows, `local-safe` currently throws because no Windows sandbox
+ * backend is wired up yet; callers must opt in to `local-yolo` explicitly.
+ */
+export declare function runShell(req: ShellRequest, ctx?: ShellRouterContext | null): Promise<ShellResult>;
+//# sourceMappingURL=shell-execution-router.d.ts.map

package/packages/agent/src/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;AAIH,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEtD,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,QAAQ,GACR,iBAAiB,GACjB,MAAM,GACN,cAAc,GACd,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,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;AAED,wBAAgB,yBAAyB,CACvC,GAAG,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,GACxD,kBAAkB,CAGpB;AA8CD,+DAA+D;AAC/D,wBAAgB,gCAAgC,IAAI,IAAI,CAGvD;AA2GD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,YAAY,EACjB,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAC9B,OAAO,CAAC,WAAW,CAAC,CAgCtB"}