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

package/dist/packages/agent/src/services/research-task-executor.js

@@ -0,0 +1,138 @@
+import { ModelType } from "@elizaos/core";
+const RESEARCH_PATTERNS = /\b(research|investigate|analyze|find out|look into|explore|summarize|compare|evaluate|review|study|assess)\b/i;
+/**
+ * Decomposes research questions into sub-questions, answers each via the
+ * runtime's LLM, and synthesizes a final report.
+ */
+export class ResearchTaskExecutor {
+    type = "research";
+    description = "Decomposes research questions and produces analysis artifacts";
+    canHandle(spec, _runtime) {
+        if (spec.type === "research")
+            return true;
+        return RESEARCH_PATTERNS.test(spec.description);
+    }
+    async execute(spec, runtime) {
+        const startTime = Date.now();
+        try {
+            try {
+                const researchResult = (await runtime.useModel(ModelType.RESEARCH, {
+                    input: spec.description,
+                    tools: [{ type: "web_search_preview" }],
+                    background: true,
+                    reasoningSummary: "auto",
+                }));
+                const output = typeof researchResult === "string"
+                    ? researchResult
+                    : (researchResult.text ?? "");
+                if (output.trim().length > 0) {
+                    return {
+                        taskId: spec.id,
+                        success: true,
+                        output,
+                        durationMs: Date.now() - startTime,
+                    };
+                }
+            }
+            catch {
+                // Fall through to the sequential synthesis path when the runtime
+                // does not expose a RESEARCH model or the provider rejects it.
+            }
+            // Step 1: Decompose the research question into sub-questions
+            const decomposition = await runtime.useModel(ModelType.TEXT_LARGE, {
+                prompt: [
+                    "Decompose this research question into 3-5 focused sub-questions",
+                    "that can be answered independently:",
+                    "",
+                    spec.description,
+                    "",
+                    "Return each sub-question on its own line, one per line. No numbering, no bullets, no prose.",
+                ].join("\n"),
+            });
+            let subQuestions;
+            try {
+                // Parse line-delimited questions from the response.
+                // Strip markdown fences and numbering if the model adds them.
+                let raw = typeof decomposition === "string"
+                    ? decomposition
+                    : String(decomposition);
+                const fenceMatch = raw.match(/```(?:\w+)?\s*\n?([\s\S]*?)\n?\s*```/);
+                if (fenceMatch)
+                    raw = fenceMatch[1];
+                // Try line-based parsing first (preferred)
+                const lines = raw
+                    .split(/\r?\n/)
+                    .map((line) => line
+                    .replace(/^\s{0,32}(?:\d{1,8}[.)]\s{0,32}|-\s{0,32}|\*\s{0,32})/, "")
+                    .trim())
+                    .filter((line) => line.length > 0);
+                if (lines.length >= 2) {
+                    subQuestions = lines;
+                }
+                else {
+                    // Fallback: try JSON array parse for backwards compat
+                    const jsonParsed = JSON.parse(raw.trim());
+                    subQuestions = Array.isArray(jsonParsed)
+                        ? jsonParsed.filter((q) => typeof q === "string")
+                        : [spec.description];
+                }
+                if (subQuestions.length === 0)
+                    subQuestions = [spec.description];
+            }
+            catch {
+                subQuestions = [spec.description];
+            }
+            // Step 2: Answer each sub-question
+            const answers = [];
+            for (const question of subQuestions) {
+                const answer = await runtime.useModel(ModelType.TEXT_LARGE, {
+                    prompt: [
+                        "Answer this research question concisely but thoroughly:",
+                        "",
+                        question,
+                        "",
+                        `Context: This is part of a larger research task: "${spec.description}"`,
+                    ].join("\n"),
+                });
+                answers.push({
+                    question,
+                    answer: typeof answer === "string" ? answer : String(answer),
+                });
+            }
+            // Step 3: Synthesize into a final report
+            const findingsBlock = answers
+                .map((a, i) => `${i + 1}. Q: ${a.question}\n   A: ${a.answer}`)
+                .join("\n\n");
+            const synthesis = await runtime.useModel(ModelType.TEXT_LARGE, {
+                prompt: [
+                    "Synthesize these research findings into a coherent report:",
+                    "",
+                    `Original question: ${spec.description}`,
+                    "",
+                    `Findings:\n${findingsBlock}`,
+                    "",
+                    "Provide a structured summary with key findings, conclusions, and any caveats.",
+                ].join("\n"),
+            });
+            const report = typeof synthesis === "string" ? synthesis : String(synthesis);
+            return {
+                taskId: spec.id,
+                success: true,
+                output: report,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            return {
+                taskId: spec.id,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            };
+        }
+    }
+    async abort(_taskId) {
+        // Research tasks are sequential LLM calls — no persistent process to abort.
+        // Could add cancellation token support in the future.
+    }
+}

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

@@ -0,0 +1,127 @@
+/** Sandbox container lifecycle: create, exec, health check, teardown. */
+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 {
+    /** Sandbox mode. */
+    mode: SandboxMode;
+    /** Docker image for sandbox containers. */
+    image?: string;
+    /** Container name prefix. */
+    containerPrefix?: string;
+    /** Container workdir mount path. */
+    workdir?: string;
+    /** Run rootfs read-only. */
+    readOnlyRoot?: boolean;
+    /** Container network mode. */
+    network?: string;
+    /** Container user (uid:gid). */
+    user?: string;
+    /** Drop Linux capabilities. */
+    capDrop?: string[];
+    /** Environment variables for sandbox. */
+    env?: Record<string, string>;
+    /** Container memory limit. */
+    memory?: string;
+    /** Container CPU limit. */
+    cpus?: number;
+    /** PIDs limit. */
+    pidsLimit?: number;
+    /** Root directory for sandbox workspaces. */
+    workspaceRoot?: string;
+    /** Additional bind mounts. */
+    binds?: string[];
+    /** DNS servers. */
+    dns?: string[];
+    /** Container engine type: "docker", "apple-container", or "auto" (default). */
+    engineType?: SandboxEngineType;
+    /** Browser sandbox settings. */
+    browser?: {
+        enabled?: boolean;
+        image?: string;
+        cdpPort?: number;
+        vncPort?: number;
+        noVncPort?: number;
+        headless?: boolean;
+        enableNoVnc?: boolean;
+        autoStart?: boolean;
+        autoStartTimeoutMs?: number;
+    };
+}
+export interface SandboxExecOptions {
+    command: string;
+    workdir?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    stdin?: string;
+}
+export interface SandboxExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    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";
+    detail: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+export declare class SandboxManager {
+    private state;
+    private config;
+    private engine;
+    private containerId;
+    private browserContainerId;
+    private eventLog;
+    private lifecycleQueue;
+    constructor(config: SandboxManagerConfig);
+    getState(): SandboxState;
+    getMode(): SandboxMode;
+    isReady(): boolean;
+    private getMainContainerConfig;
+    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;
+    private createBrowserContainer;
+    private healthCheck;
+    private emitEvent;
+    getEventLog(): SandboxEvent[];
+    getStatus(): {
+        state: SandboxState;
+        mode: SandboxMode;
+        containerId: string | null;
+        browserContainerId: string | null;
+    };
+}
+//# sourceMappingURL=sandbox-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/sandbox-manager.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,418 @@
+/** Sandbox container lifecycle: create, exec, health check, teardown. */
+import { mkdirSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+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";
+    config;
+    engine;
+    containerId = null;
+    browserContainerId = null;
+    eventLog = [];
+    lifecycleQueue = Promise.resolve();
+    constructor(config) {
+        this.config = {
+            image: "eliza-sandbox:bookworm-slim",
+            containerPrefix: "eliza-sandbox",
+            workdir: "/workspace",
+            network: "none",
+            user: "1000:1000",
+            capDrop: ["ALL"],
+            memory: "512m",
+            cpus: 1,
+            pidsLimit: 256,
+            ...config,
+        };
+        this.engine = config.engineType
+            ? createEngine(config.engineType)
+            : detectBestEngine();
+    }
+    getState() {
+        return this.state;
+    }
+    getMode() {
+        return this.config.mode;
+    }
+    isReady() {
+        return this.state === "ready";
+    }
+    getMainContainerConfig() {
+        const image = this.config.image ?? "eliza-sandbox:bookworm-slim";
+        const containerPrefix = this.config.containerPrefix ?? "eliza-sandbox";
+        const workdir = this.config.workdir ?? "/workspace";
+        const network = this.config.network ?? "none";
+        const user = this.config.user ?? "1000:1000";
+        const wsRoot = this.config.workspaceRoot ??
+            join(process.env.HOME ?? process.env.USERPROFILE ?? os.tmpdir(), ".eliza", "sandbox-workspace");
+        mkdirSync(wsRoot, { recursive: true });
+        return { image, containerPrefix, workdir, network, user, wsRoot };
+    }
+    async createMainContainer() {
+        const config = this.getMainContainerConfig();
+        return this.engine.runContainer({
+            image: config.image,
+            name: `${config.containerPrefix}-${Date.now()}`,
+            detach: true,
+            mounts: [
+                { host: config.wsRoot, container: config.workdir, readonly: false },
+            ],
+            env: this.config.env ?? {},
+            network: config.network,
+            user: config.user,
+            capDrop: this.config.capDrop ?? [],
+            memory: this.config.memory,
+            cpus: this.config.cpus,
+            pidsLimit: this.config.pidsLimit,
+            readOnlyRoot: this.config.readOnlyRoot,
+            dns: this.config.dns,
+        });
+    }
+    async cleanupContainer(containerId) {
+        if (!containerId)
+            return;
+        await this.engine.stopContainer(containerId);
+        await this.engine.removeContainer(containerId);
+    }
+    setState(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.emitEvent({
+            timestamp: Date.now(),
+            type: "state_change",
+            detail: `${oldState} → ${newState}`,
+        });
+    }
+    queueLifecycle(operation) {
+        const run = this.lifecycleQueue.then(operation, operation);
+        this.lifecycleQueue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async start() {
+        return await this.queueLifecycle(async () => {
+            if (this.config.mode === "off") {
+                if (this.state !== "stopped") {
+                    this.setState("stopped");
+                }
+                return;
+            }
+            if (this.config.mode === "light") {
+                if (this.state !== "ready") {
+                    this.setState("ready");
+                }
+                return;
+            }
+            if (this.state === "ready" ||
+                this.state === "initializing" ||
+                this.state === "recovering") {
+                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);
+                    }
+                    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");
+                }
+            }
+            catch (err) {
+                this.emitEvent({
+                    timestamp: Date.now(),
+                    type: "error",
+                    detail: `Sandbox start failed: ${String(err)}`,
+                });
+                this.setState("degraded");
+                throw err;
+            }
+        });
+    }
+    async recover() {
+        return await this.queueLifecycle(async () => {
+            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");
+                }
+                else {
+                    this.setState("degraded");
+                }
+            }
+            catch (err) {
+                this.emitEvent({
+                    timestamp: Date.now(),
+                    type: "error",
+                    detail: `Recovery failed: ${String(err)}`,
+                });
+                this.setState("degraded");
+            }
+        });
+    }
+    async stop() {
+        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();
+        if (this.config.mode === "off" || this.config.mode === "light") {
+            // In off/light mode, refuse sandbox exec — caller must use local
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: "Sandbox exec not available in current mode",
+                durationMs: Date.now() - start,
+                executedInSandbox: false,
+            };
+        }
+        if (!this.containerId || this.state !== "ready") {
+            this.emitEvent({
+                timestamp: Date.now(),
+                type: "exec_denied",
+                detail: `Sandbox not ready (state=${this.state})`,
+            });
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `Sandbox not ready (state=${this.state})`,
+                durationMs: Date.now() - start,
+                executedInSandbox: false,
+            };
+        }
+        this.emitEvent({
+            timestamp: Date.now(),
+            type: "exec",
+            detail: options.command.substring(0, 200),
+            metadata: {
+                workdir: options.workdir ?? this.config.workdir ?? "/workspace",
+            },
+        });
+        try {
+            const result = await this.engine.execInContainer({
+                containerId: this.containerId,
+                command: options.command,
+                workdir: options.workdir,
+                env: options.env,
+                timeoutMs: options.timeoutMs,
+                stdin: options.stdin,
+            });
+            return {
+                ...result,
+                executedInSandbox: true,
+            };
+        }
+        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: ${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;
+        const port = this.config.browser?.cdpPort ?? 9222;
+        return `http://localhost:${port}`;
+    }
+    getBrowserWsEndpoint() {
+        if (!this.browserContainerId)
+            return null;
+        const port = this.config.browser?.cdpPort ?? 9222;
+        return `ws://localhost:${port}`;
+    }
+    getBrowserNoVncEndpoint() {
+        if (!this.browserContainerId)
+            return null;
+        const noVncEnabled = this.config.browser?.enableNoVnc ?? false;
+        const headless = this.config.browser?.headless ?? false;
+        if (!noVncEnabled || headless)
+            return null;
+        const port = this.config.browser?.noVncPort ?? 6080;
+        return `http://localhost:${port}/vnc.html?autoconnect=true&resize=scale&view_only=true`;
+    }
+    async createBrowserContainer() {
+        const name = `${this.config.containerPrefix}-browser-${Date.now()}`;
+        const cdpPort = this.config.browser?.cdpPort ?? 9222;
+        const vncPort = this.config.browser?.vncPort ?? 5900;
+        const noVncPort = this.config.browser?.noVncPort ?? 6080;
+        const enableNoVnc = this.config.browser?.enableNoVnc ?? false;
+        const headless = this.config.browser?.headless ?? false;
+        const image = this.config.browser?.image ?? "eliza-sandbox-browser:bookworm-slim";
+        return this.engine.runContainer({
+            image,
+            name,
+            detach: true,
+            mounts: [],
+            env: {
+                ELIZA_BROWSER_CDP_PORT: String(cdpPort),
+                ELIZA_BROWSER_VNC_PORT: String(vncPort),
+                ELIZA_BROWSER_NOVNC_PORT: String(noVncPort),
+                ELIZA_BROWSER_ENABLE_NOVNC: enableNoVnc ? "1" : "0",
+                ELIZA_BROWSER_HEADLESS: headless ? "1" : "0",
+            },
+            network: "bridge",
+            user: "1000:1000",
+            capDrop: [],
+            ports: [
+                { host: cdpPort, container: cdpPort },
+                { host: vncPort, container: vncPort },
+                ...(enableNoVnc && !headless
+                    ? [{ host: noVncPort, container: noVncPort }]
+                    : []),
+            ],
+        });
+    }
+    async healthCheck() {
+        if (!this.containerId)
+            return false;
+        const healthy = await this.engine.healthCheck(this.containerId);
+        this.emitEvent({
+            timestamp: Date.now(),
+            type: "health_check",
+            detail: healthy ? "healthy" : "unhealthy",
+        });
+        return healthy;
+    }
+    emitEvent(event) {
+        this.eventLog.push(event);
+        // Keep bounded
+        if (this.eventLog.length > 1000) {
+            this.eventLog = this.eventLog.slice(-500);
+        }
+    }
+    getEventLog() {
+        return [...this.eventLog];
+    }
+    getStatus() {
+        return {
+            state: this.state,
+            mode: this.config.mode,
+            containerId: this.containerId,
+            browserContainerId: this.browserContainerId,
+        };
+    }
+}