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

package/packages/agent/src/actions/terminal.js

@@ -1,146 +1,267 @@
 /**
- * RUN_IN_TERMINAL action — runs a shell command on the server.
+ * SHELL action — runs a shell command on the server.
  *
  * When triggered the action:
- *   1. Extracts the command from the parameters
+ *   1. Extracts the command from parameters or MCP-style JSON
  *   2. POSTs to the local API server to execute it
  *   3. The API broadcasts output via WebSocket for real-time display
- *   4. Returns a descriptive text response
+ *   4. Captures the output for planner follow-up
+ *   5. Stores the full output as a document attachment for follow-up actions
  *
  * @module actions/terminal
  */
+import { buildStoreVariantBlockedMessage, ContentType, isLocalCodeExecutionAllowed, logger, stringToUuid, } from "@elizaos/core";
+import { hasOwnerAccess } from "../security/access.js";
 /** API port for posting terminal requests. */
 const API_PORT = process.env.API_PORT || process.env.SERVER_PORT || "2138";
-function nonEmptyString(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
+const TERMINAL_ACTION_NAME = "SHELL";
+const MAX_TERMINAL_DATA_CHARS = 16000;
+const FAIL = { success: false, text: "" };
+function readStringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function isJsonRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function resolveCommandFromObject(value) {
-    if (!value || typeof value !== "object")
+function parseJsonArguments(value) {
+    if (typeof value !== "string" || !value.trim()) {
         return undefined;
-    const record = value;
-    const direct = nonEmptyString(record.command) ??
-        nonEmptyString(record.cmd) ??
-        nonEmptyString(record.commandLine) ??
-        nonEmptyString(record.shellCommand);
-    if (direct)
-        return direct;
-    const args = record.args;
-    if (Array.isArray(args) && args.every((entry) => typeof entry === "string")) {
-        const joined = args.join(" ").trim();
-        if (joined)
-            return joined;
     }
-    const nested = resolveCommandFromObject(record.arguments) ??
-        resolveCommandFromObject(record.input) ??
-        resolveCommandFromObject(record.parameters);
-    if (nested)
-        return nested;
+    try {
+        const parsed = JSON.parse(value);
+        if (isJsonRecord(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore invalid MCP-style argument payloads and fall back to NL parsing.
+    }
     return undefined;
 }
-function resolveCommandFromArguments(argumentsValue) {
-    if (typeof argumentsValue === "string") {
-        const trimmed = argumentsValue.trim();
-        if (!trimmed)
-            return undefined;
-        try {
-            const parsed = JSON.parse(trimmed);
-            return resolveCommandFromObject(parsed) ?? trimmed;
-        }
-        catch {
-            return trimmed;
-        }
+/**
+ * Extract a command from handler options and message text.
+ *
+ * Resolution order:
+ *   1. `parameters.command` — explicit parameter
+ *   2. `parameters.shellCommand` — explicit alias
+ *   3. `parameters.arguments` — MCP-style JSON string like `{"command":"ls"}`
+ */
+function getCommand(options) {
+    const params = (options?.parameters ?? {});
+    const argumentParams = parseJsonArguments(params.arguments);
+    // The planner must extract the command as an explicit `command` param.
+    // We intentionally do not fall back to regex-scraping the message text or
+    // keyword-matching the request for hardcoded commands ("free -h" for
+    // "memory", etc.) — that would be intent classification in the handler
+    // instead of in the LLM planner, which bypasses the LLM's judgment on
+    // safety, scope, and argument construction.
+    return (readStringValue(params.command) ??
+        readStringValue(params.shellCommand) ??
+        readStringValue(argumentParams?.command) ??
+        readStringValue(argumentParams?.shellCommand));
+}
+function resolveTerminalInput(options) {
+    return {
+        command: getCommand(options),
+    };
+}
+function normalizeCapturedRun(command, value) {
+    const data = isJsonRecord(value) ? value : {};
+    const exitCode = typeof data.exitCode === "number" && Number.isFinite(data.exitCode)
+        ? data.exitCode
+        : Number(data.exitCode ?? 0) || 0;
+    return {
+        command,
+        runId: readStringValue(data.runId),
+        exitCode,
+        stdout: typeof data.stdout === "string" ? data.stdout : "",
+        stderr: typeof data.stderr === "string" ? data.stderr : "",
+        timedOut: data.timedOut === true,
+        truncated: data.truncated === true,
+        maxDurationMs: typeof data.maxDurationMs === "number" &&
+            Number.isFinite(data.maxDurationMs)
+            ? data.maxDurationMs
+            : undefined,
+    };
+}
+function formatOutputBlock(content) {
+    return content.trimEnd() || "(empty)";
+}
+function buildCommandArtifactContent(result) {
+    return [
+        `Command: ${result.command}`,
+        `Exit code: ${result.exitCode}`,
+        result.timedOut
+            ? `Timed out: yes${typeof result.maxDurationMs === "number" ? ` (${result.maxDurationMs} ms limit)` : ""}`
+            : "Timed out: no",
+        result.truncated ? "Captured output truncated to 128 KB." : "",
+        "",
+        "STDOUT:",
+        formatOutputBlock(result.stdout),
+        "",
+        "STDERR:",
+        formatOutputBlock(result.stderr),
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function buildOutputPreview(content, maxLength = 3_000) {
+    const trimmed = content.trimEnd();
+    if (trimmed.length <= maxLength) {
+        return formatOutputBlock(trimmed);
     }
-    return resolveCommandFromObject(argumentsValue);
+    return `${trimmed.slice(0, maxLength).trimEnd()}\n\n[... ${trimmed.length - maxLength} chars omitted; use the attachment for full output ...]`;
 }
-function resolveCommandFromParams(params) {
-    const record = params;
-    if (!record || typeof record !== "object")
-        return undefined;
-    const direct = nonEmptyString(record.command) ??
-        nonEmptyString(record.cmd) ??
-        nonEmptyString(record.commandLine) ??
-        nonEmptyString(record.shellCommand);
-    if (direct)
-        return direct;
-    return (resolveCommandFromArguments(record.arguments) ??
-        resolveCommandFromArguments(record.input) ??
-        resolveCommandFromObject(record.parameters));
+function truncateForData(text, max = MAX_TERMINAL_DATA_CHARS) {
+    return text.length <= max ? text : `${text.slice(0, max)}\n…[truncated]`;
 }
-function resolveCommandFromText(text) {
-    const source = nonEmptyString(text);
-    if (!source)
+async function createCommandOutputAttachment(runtime, message, result) {
+    if (!runtime?.createMemory) {
         return undefined;
-    const fenced = source.match(/```(?:bash|sh|zsh|shell)?\s*([\s\S]*?)```/i);
-    if (fenced) {
-        const command = nonEmptyString(fenced[1]);
-        if (command)
-            return command;
     }
-    const inline = source.match(/`([^`\n]+)`/);
-    if (inline) {
-        const command = nonEmptyString(inline[1]);
-        if (command)
-            return command;
+    const attachmentId = stringToUuid(`terminal-output:${message.id ?? message.roomId}:${result.runId ?? result.command}:${Date.now()}`);
+    const title = `Shell output: ${result.command}`;
+    const attachment = {
+        id: attachmentId,
+        url: `memory://terminal-output/${attachmentId}`,
+        title,
+        source: TERMINAL_ACTION_NAME,
+        description: `Full stdout/stderr for \`${result.command}\` (exit ${result.exitCode}).`,
+        text: buildCommandArtifactContent(result),
+        contentType: ContentType.DOCUMENT,
+    };
+    try {
+        const memoryId = await runtime.createMemory({
+            id: stringToUuid(`terminal-output-memory:${attachmentId}`),
+            entityId: runtime.agentId,
+            agentId: runtime.agentId,
+            roomId: message.roomId,
+            createdAt: Date.now(),
+            content: {
+                text: `Stored terminal output attachment ${attachment.id}: ${attachment.title}`,
+                source: TERMINAL_ACTION_NAME,
+                attachments: [attachment],
+            },
+        }, "messages");
+        return { attachment, memoryId };
     }
-    const runMatch = source.match(/\b(?:run|execute|exec)\b\s+(?:(?:the|this)\s+)?(?:(?:command|shell command)\s+)?["'`]?([^"'`\n]+?)["'`]?$/i);
-    if (runMatch) {
-        const candidate = runMatch[1]
-            .replace(/\s+(?:in|on)\s+(?:the\s+)?(?:terminal|shell)\b.*$/i, "")
-            .replace(/[.?!,:;]+$/g, "")
-            .trim();
-        if (candidate)
-            return candidate;
+    catch (error) {
+        logger.warn(`[terminal] Failed to store shell output attachment (${error instanceof Error ? error.message : String(error)})`);
+        return { attachment };
     }
-    return undefined;
+}
+function buildCapturedResponseText(result, outputAttachment) {
+    const outputContent = buildCommandArtifactContent(result);
+    return [
+        `Shell command completed: \`${result.command}\``,
+        `Exit code: ${result.exitCode}`,
+        result.timedOut
+            ? `Timed out${typeof result.maxDurationMs === "number" ? ` after ${result.maxDurationMs} ms` : ""}.`
+            : "",
+        result.truncated ? "Captured output truncated to 128 KB." : "",
+        outputAttachment
+            ? `Full output attachment: ${outputAttachment.attachment.id} (${outputAttachment.attachment.title})`
+            : "",
+        outputAttachment?.memoryId
+            ? `Attachment memory: ${outputAttachment.memoryId}`
+            : outputAttachment
+                ? "Attachment memory could not be persisted; full output is still present in this action result."
+                : "No attachment was stored for this output.",
+        "",
+        "Output preview:",
+        buildOutputPreview(outputContent),
+        "",
+        "Next-step contract for the planner:",
+        "- Decide whether to reply to the user, stay silent, or continue with another action.",
+        "- If the output should be kept for this task, call SAVE_ATTACHMENT_TO_CLIPBOARD with the attachmentId above.",
+        "- If replying, answer naturally from the output instead of echoing this report.",
+    ]
+        .filter(Boolean)
+        .join("\n");
 }
 export const terminalAction = {
-    name: "RUN_IN_TERMINAL",
+    name: TERMINAL_ACTION_NAME,
+    contexts: ["terminal", "code", "files", "admin"],
+    roleGate: { minRole: "OWNER" },
     similes: [
+        "RUN_IN_TERMINAL",
         "RUN_COMMAND",
         "EXECUTE_COMMAND",
         "TERMINAL",
-        "SHELL",
+        "SHELL_COMMAND",
         "RUN_SHELL",
         "EXEC",
-        // Compatibility for upstream templates that may still emit CALL_MCP_TOOL.
         "CALL_MCP_TOOL",
-        "CALL_TOOL",
     ],
-    description: "Run a shell command in the user's terminal. Use this when the user asks " +
-        "you to run a command, execute a script, install packages, or perform " +
-        "any terminal operation. Output is shown in real time.",
-    validate: async () => true,
-    handler: async (_runtime, _message, _state, options) => {
+    description: "Run a single explicit shell command that the user provided directly. " +
+        "Only use when the user gives a specific command like 'run ls -la' or 'execute npm install'. " +
+        "Do NOT use for building projects, creating websites, or multi-step work — use START_CODING_TASK instead. " +
+        "The command output is captured as a document attachment for native planner follow-up. After the run, decide whether to reply, stay silent, continue with another action, or save the attachment via the clipboard plugin.",
+    descriptionCompressed: "run single explicit shell command user provide directly use user give specific command like run ls - la execute npm install use build project, create website, multi-step work use START_CODING_TASK instead command output captur document attachment native planner follow-up after run, decide whether reply, stay silent, continue w/ another action, save attachment via clipboard plugin",
+    validate: async () => isLocalCodeExecutionAllowed(),
+    handler: async (runtime, message, _state, options) => {
+        if (!isLocalCodeExecutionAllowed()) {
+            return {
+                success: false,
+                text: buildStoreVariantBlockedMessage("Terminal commands"),
+                data: {
+                    actionName: TERMINAL_ACTION_NAME,
+                    suppressPostActionContinuation: true,
+                    terminal: { storeBuildBlocked: true },
+                },
+            };
+        }
+        if (!(await hasOwnerAccess(runtime, message))) {
+            return {
+                success: false,
+                text: "Permission denied: only the owner may run terminal commands.",
+                data: {
+                    actionName: TERMINAL_ACTION_NAME,
+                    suppressPostActionContinuation: true,
+                    terminal: { permissionDenied: true },
+                },
+            };
+        }
+        const input = resolveTerminalInput(options);
+        const command = input.command;
+        if (!command) {
+            return FAIL;
+        }
         try {
-            const params = options?.parameters;
-            const command = resolveCommandFromParams(params) ??
-                resolveCommandFromText(_message?.content
-                    ?.text);
-            if (!command) {
-                return { text: "", success: false };
-            }
             const response = await fetch(`http://localhost:${API_PORT}/api/terminal/run`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({
                     command,
                     clientId: "runtime-terminal-action",
+                    captureOutput: true,
                 }),
             });
             if (!response.ok) {
-                return { text: "", success: false };
+                return FAIL;
             }
+            const responseBody = (await response.json());
+            const capturedRun = normalizeCapturedRun(command, responseBody);
+            const boundedRun = {
+                ...capturedRun,
+                stdout: truncateForData(capturedRun.stdout),
+                stderr: truncateForData(capturedRun.stderr),
+            };
+            const outputAttachment = await createCommandOutputAttachment(runtime, message, capturedRun);
             return {
-                text: `Running in terminal: \`${command}\``,
+                text: buildCapturedResponseText(capturedRun, outputAttachment),
                 success: true,
-                data: { command },
+                data: {
+                    actionName: TERMINAL_ACTION_NAME,
+                    ...boundedRun,
+                    outputAttachment: outputAttachment?.attachment,
+                    outputAttachmentMemoryId: outputAttachment?.memoryId,
+                    suppressVisibleCallback: true,
+                },
             };
         }
-        catch (_err) {
-            return { text: "", success: false };
+        catch {
+            return FAIL;
         }
     },
     parameters: [
@@ -151,4 +272,34 @@ export const terminalAction = {
             schema: { type: "string" },
         },
     ],
+    examples: [
+        [
+            {
+                name: "{{name1}}",
+                content: {
+                    text: "Run ls -la in my home directory.",
+                },
+            },
+            {
+                name: "{{agentName}}",
+                content: {
+                    text: "The directory listing completed. It shows the current files and folders in your home directory.",
+                },
+            },
+        ],
+        [
+            {
+                name: "{{name1}}",
+                content: {
+                    text: "Execute `git status` and save the output so I can look at it later.",
+                },
+            },
+            {
+                name: "{{agentName}}",
+                content: {
+                    text: "The `git status` output was captured. I saved the full output as an attachment and can keep it in the clipboard if it is useful for the next step.",
+                },
+            },
+        ],
+    ],
 };

package/packages/agent/src/actions/trajectories.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Trajectory introspection actions.
+ *
+ * QUERY_TRAJECTORIES → GET /api/trajectories
+ */
+import type { Action } from "@elizaos/core";
+export declare const queryTrajectoriesAction: Action;
+//# sourceMappingURL=trajectories.d.ts.map

package/packages/agent/src/actions/trajectories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectories.d.ts","sourceRoot":"","sources":["../../../../../src/actions/trajectories.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAgC,MAAM,eAAe,CAAC;AAqB1E,eAAO,MAAM,uBAAuB,EAAE,MAyIrC,CAAC"}

package/packages/agent/src/actions/trajectories.js

@@ -0,0 +1,135 @@
+/**
+ * Trajectory introspection actions.
+ *
+ * QUERY_TRAJECTORIES → GET /api/trajectories
+ */
+import { logger } from "@elizaos/core";
+import { resolveServerOnlyPort } from "@elizaos/shared";
+function getApiBase() {
+    return `http://localhost:${resolveServerOnlyPort(process.env)}`;
+}
+const TRAJECTORY_STATUSES = ["active", "completed", "error"];
+export const queryTrajectoriesAction = {
+    name: "QUERY_TRAJECTORIES",
+    contexts: ["agent_internal", "admin", "documents"],
+    roleGate: { minRole: "OWNER" },
+    similes: ["LIST_TRAJECTORIES", "FIND_TRAJECTORIES", "BROWSE_TRAJECTORIES"],
+    description: "List recorded trajectories with optional filters: source, status, scenarioId, batchId, plus limit/offset.",
+    descriptionCompressed: "list record trajectory w/ optional filter: source, status, scenarioid, batchid, plus limit/offset",
+    validate: async () => true,
+    handler: async (_runtime, _message, _state, options) => {
+        const params = options?.parameters;
+        const search = new URLSearchParams();
+        if (params?.source)
+            search.set("source", params.source);
+        if (params?.status && TRAJECTORY_STATUSES.includes(params.status)) {
+            search.set("status", params.status);
+        }
+        if (params?.scenarioId)
+            search.set("scenarioId", params.scenarioId);
+        if (params?.batchId)
+            search.set("batchId", params.batchId);
+        if (params?.limit != null) {
+            search.set("limit", String(Math.max(1, Math.min(500, Math.floor(params.limit)))));
+        }
+        if (params?.offset != null) {
+            search.set("offset", String(Math.max(0, Math.floor(params.offset))));
+        }
+        const qs = search.toString();
+        const url = `${getApiBase()}/api/trajectories${qs ? `?${qs}` : ""}`;
+        try {
+            const resp = await fetch(url, { signal: AbortSignal.timeout(20_000) });
+            if (!resp.ok) {
+                return {
+                    success: false,
+                    text: `Failed to query trajectories: HTTP ${resp.status}`,
+                };
+            }
+            const data = (await resp.json());
+            const trajectories = data.trajectories ?? [];
+            const lines = trajectories
+                .slice(0, 25)
+                .map((t) => `- ${t.id} ${t.status ?? "?"} src=${t.source ?? "?"} started=${t.startTime ?? "?"}`);
+            return {
+                success: true,
+                text: [
+                    `Found ${trajectories.length} trajectory record(s) (total available: ${data.total}, offset: ${data.offset}).`,
+                    ...lines,
+                ].join("\n"),
+                values: {
+                    count: trajectories.length,
+                    total: data.total,
+                    offset: data.offset,
+                },
+                data: {
+                    actionName: "QUERY_TRAJECTORIES",
+                    trajectories,
+                    total: data.total,
+                    offset: data.offset,
+                    limit: data.limit,
+                },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn(`[query-trajectories] failed: ${msg}`);
+            return {
+                success: false,
+                text: `Failed to query trajectories: ${msg}`,
+            };
+        }
+    },
+    parameters: [
+        {
+            name: "source",
+            description: "Optional source filter.",
+            required: false,
+            schema: { type: "string" },
+        },
+        {
+            name: "status",
+            description: "Optional status filter.",
+            required: false,
+            schema: { type: "string", enum: [...TRAJECTORY_STATUSES] },
+        },
+        {
+            name: "scenarioId",
+            description: "Optional scenario ID filter.",
+            required: false,
+            schema: { type: "string" },
+        },
+        {
+            name: "batchId",
+            description: "Optional batch ID filter.",
+            required: false,
+            schema: { type: "string" },
+        },
+        {
+            name: "limit",
+            description: "Maximum number of records to return (1-500).",
+            required: false,
+            schema: { type: "number" },
+        },
+        {
+            name: "offset",
+            description: "Pagination offset.",
+            required: false,
+            schema: { type: "number" },
+        },
+    ],
+    examples: [
+        [
+            {
+                name: "{{name1}}",
+                content: { text: "List the last 10 completed trajectories." },
+            },
+            {
+                name: "{{agentName}}",
+                content: {
+                    text: "Found N trajectory record(s)...",
+                    action: "QUERY_TRAJECTORIES",
+                },
+            },
+        ],
+    ],
+};

package/packages/agent/src/actions/trigger.d.ts

@@ -0,0 +1,5 @@
+import { type Action } from "@elizaos/core";
+declare const TRIGGER_OPS: readonly ["create", "update", "delete", "run", "toggle"];
+export declare const triggerAction: Action;
+export { TRIGGER_OPS };
+//# sourceMappingURL=trigger.d.ts.map

package/packages/agent/src/actions/trigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger.d.ts","sourceRoot":"","sources":["../../../../../src/actions/trigger.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,KAAK,MAAM,EAgBZ,MAAM,eAAe,CAAC;AA2BvB,QAAA,MAAM,WAAW,0DAA2D,CAAC;AAqd7E,eAAO,MAAM,aAAa,EAAE,MAmL3B,CAAC;AAEF,OAAO,EAAE,WAAW,EAAE,CAAC"}