@elizaos/agent 0.25.8 → 2.0.0-alpha.83

package/packages/agent/src/runtime/custom-actions.js

@@ -0,0 +1,454 @@
+/**
+ * Custom Actions runtime loader.
+ *
+ * Converts `CustomActionDef[]` from config into elizaOS `Action[]` objects
+ * so the agent can use them in conversations.
+ *
+ * @module runtime/custom-actions
+ */
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as requestHttp, } from "node:http";
+import { request as requestHttps } from "node:https";
+import net from "node:net";
+import { Readable } from "node:stream";
+import { loadElizaConfig } from "../config/config";
+import { isBlockedPrivateOrLinkLocalIp, normalizeHostLike, } from "../security/network-policy";
+/** Cached runtime reference for hot-registration of new actions. */
+let _runtime = null;
+/**
+ * Store the runtime reference so we can hot-register actions later.
+ * Called once from plugin.init().
+ */
+export function setCustomActionsRuntime(runtime) {
+    _runtime = runtime;
+}
+/**
+ * Hot-register a CustomActionDef into the running agent.
+ * Returns the elizaOS Action that was registered, or null if no runtime.
+ */
+export function registerCustomActionLive(def) {
+    if (!_runtime)
+        return null;
+    const action = defToAction(def);
+    _runtime.registerAction(action);
+    return action;
+}
+/** API port for shell handler requests. */
+const API_PORT = process.env.API_PORT || process.env.SERVER_PORT || "2138";
+/** Valid handler types that we actually support. */
+const VALID_HANDLER_TYPES = new Set(["http", "shell", "code"]);
+let vmRunner = null;
+const CUSTOM_ACTION_FETCH_TIMEOUT_MS = 15_000;
+function resolveFetchInputUrl(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.toString();
+    if (typeof Request !== "undefined" && input instanceof Request) {
+        return input.url;
+    }
+    return null;
+}
+async function safeCodeFetch(input, init) {
+    const url = resolveFetchInputUrl(input);
+    if (!url) {
+        throw new Error("Blocked: cannot make requests to internal network addresses");
+    }
+    const safety = await resolveUrlSafety(url);
+    if (safety.blocked) {
+        throw new Error("Blocked: cannot make requests to internal network addresses");
+    }
+    const requestInit = await buildPinnedFetchInit(input, init);
+    const response = safety.target
+        ? await fetchWithPinnedTarget(safety.target, requestInit, CUSTOM_ACTION_FETCH_TIMEOUT_MS)
+        : await fetch(input, requestInit);
+    if (response.status >= 300 && response.status < 400) {
+        throw new Error("Blocked: redirects are not allowed for code custom actions");
+    }
+    return response;
+}
+async function runCodeHandler(code, params) {
+    if (typeof process === "undefined" || !process.versions?.node) {
+        throw new Error("Code actions are only supported in Node runtimes.");
+    }
+    if (!vmRunner) {
+        vmRunner = (await import("node:vm"));
+    }
+    const script = `(async () => { ${code} })();`;
+    const context = Object.create(null);
+    context.params = Object.freeze({ ...params });
+    const wrapperScript = `(function(hostFetch) {
+    return function fetch(input, init) { return hostFetch(input, init); };
+  })`;
+    const wrapFetch = vmRunner.runInNewContext(wrapperScript, Object.create(null), {
+        filename: "eliza-fetch-wrapper",
+        timeout: 1_000,
+    });
+    context.fetch = wrapFetch(safeCodeFetch);
+    return await vmRunner.runInNewContext(`"use strict"; ${script}`, context, {
+        filename: "eliza-custom-action",
+        timeout: 30_000,
+    });
+}
+function shellEscape(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function isBlockedIp(ip) {
+    return isBlockedPrivateOrLinkLocalIp(ip);
+}
+function toRequestHeaders(headers) {
+    const normalized = {};
+    headers.forEach((value, key) => {
+        normalized[key] = value;
+    });
+    return normalized;
+}
+async function toRequestBodyBuffer(body) {
+    if (body === null || body === undefined)
+        return null;
+    if (typeof body === "string")
+        return Buffer.from(body);
+    if (body instanceof URLSearchParams)
+        return Buffer.from(body.toString());
+    if (body instanceof Blob)
+        return Buffer.from(await body.arrayBuffer());
+    if (body instanceof ArrayBuffer)
+        return Buffer.from(body);
+    if (ArrayBuffer.isView(body)) {
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    }
+    throw new Error("Unsupported request body type for custom action fetch");
+}
+function responseFromIncomingMessage(response) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(response.headers)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(key, item);
+        }
+        else if (typeof value === "string") {
+            headers.set(key, value);
+        }
+    }
+    const status = response.statusCode ?? 500;
+    const body = status === 204 || status === 205 || status === 304
+        ? null
+        : Readable.toWeb(response);
+    return new Response(body, {
+        status,
+        statusText: response.statusMessage,
+        headers,
+    });
+}
+async function requestWithPinnedAddress(input) {
+    const { url, init, target, timeoutMs } = input;
+    const method = (init.method ?? "GET").toUpperCase();
+    const headers = new Headers(init.headers);
+    const bodyBuffer = await toRequestBodyBuffer(init.body);
+    if (bodyBuffer && !headers.has("content-length")) {
+        headers.set("content-length", String(bodyBuffer.byteLength));
+    }
+    const requestFn = url.protocol === "https:" ? requestHttps : requestHttp;
+    const family = net.isIP(target.pinnedAddress) === 6 ? 6 : 4;
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const signal = init.signal;
+        let timeoutHandle = null;
+        const settle = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutHandle !== null)
+                clearTimeout(timeoutHandle);
+            signal?.removeEventListener("abort", onAbort);
+            callback();
+        };
+        const onAbort = () => {
+            request.destroy(new DOMException("Aborted", "AbortError"));
+        };
+        const requestOptions = {
+            protocol: url.protocol,
+            hostname: target.hostname,
+            port: url.port ? Number(url.port) : undefined,
+            method,
+            path: `${url.pathname}${url.search}`,
+            headers: toRequestHeaders(headers),
+            lookup: (_hostname, _options, callback) => {
+                callback(null, target.pinnedAddress, family);
+            },
+            ...(url.protocol === "https:"
+                ? { servername: target.hostname }
+                : undefined),
+        };
+        const request = requestFn(requestOptions, (response) => {
+            settle(() => resolve(responseFromIncomingMessage(response)));
+        });
+        request.on("error", (error) => {
+            settle(() => reject(error));
+        });
+        if (signal) {
+            if (signal.aborted) {
+                onAbort();
+            }
+            else {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+        timeoutHandle = setTimeout(() => {
+            request.destroy(new Error(`Custom action request timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        if (bodyBuffer) {
+            request.write(bodyBuffer);
+        }
+        request.end();
+    });
+}
+let pinnedFetchImpl = requestWithPinnedAddress;
+export function __setPinnedFetchImplForTests(impl) {
+    pinnedFetchImpl = impl ?? requestWithPinnedAddress;
+}
+async function resolveUrlSafety(url) {
+    try {
+        const parsed = new URL(url);
+        const hostname = normalizeHostLike(parsed.hostname);
+        if (!hostname)
+            return { blocked: true, target: null };
+        if ((hostname === "localhost" ||
+            hostname === "127.0.0.1" ||
+            hostname === "::1") &&
+            parsed.port === String(API_PORT)) {
+            return { blocked: false, target: null };
+        }
+        if (hostname === "localhost" ||
+            hostname === "127.0.0.1" ||
+            hostname === "::1" ||
+            hostname === "0.0.0.0" ||
+            hostname.endsWith(".local") ||
+            hostname === "[::1]" ||
+            hostname === "metadata.google.internal" ||
+            hostname === "169.254.169.254") {
+            return { blocked: true, target: null };
+        }
+        if (net.isIP(hostname)) {
+            if (isBlockedIp(hostname))
+                return { blocked: true, target: null };
+            return {
+                blocked: false,
+                target: {
+                    parsed,
+                    hostname,
+                    pinnedAddress: hostname,
+                },
+            };
+        }
+        const records = await dnsLookup(hostname, { all: true });
+        const addresses = Array.isArray(records) ? records : [records];
+        for (const entry of addresses) {
+            if (isBlockedIp(entry.address)) {
+                return { blocked: true, target: null };
+            }
+        }
+        return {
+            blocked: false,
+            target: {
+                parsed,
+                hostname,
+                pinnedAddress: addresses[0]?.address ?? "",
+            },
+        };
+    }
+    catch {
+        return { blocked: true, target: null };
+    }
+}
+async function buildPinnedFetchInit(input, init) {
+    if (typeof Request !== "undefined" && input instanceof Request) {
+        const headers = new Headers(input.headers);
+        if (init?.headers) {
+            const overrideHeaders = new Headers(init.headers);
+            overrideHeaders.forEach((value, key) => {
+                headers.set(key, value);
+            });
+        }
+        const method = init?.method ?? input.method;
+        const bodyFromInit = init?.body;
+        const bodyFromRequest = bodyFromInit !== undefined
+            ? undefined
+            : method === "GET" || method === "HEAD"
+                ? undefined
+                : await input.clone().arrayBuffer();
+        return {
+            ...init,
+            method,
+            headers,
+            body: bodyFromInit ?? bodyFromRequest,
+            signal: init?.signal ?? input.signal,
+            redirect: "manual",
+        };
+    }
+    return {
+        ...init,
+        redirect: "manual",
+    };
+}
+async function fetchWithPinnedTarget(target, init, timeoutMs) {
+    if (!target.pinnedAddress) {
+        throw new Error("Blocked: cannot make requests to internal network addresses");
+    }
+    return pinnedFetchImpl({
+        url: target.parsed,
+        init,
+        target,
+        timeoutMs,
+    });
+}
+function buildHandler(handler, paramDefs) {
+    if (!VALID_HANDLER_TYPES.has(handler.type)) {
+        return async () => ({
+            ok: false,
+            output: `Unsupported handler type: ${handler.type}`,
+        });
+    }
+    switch (handler.type) {
+        case "http":
+            return async (params) => {
+                let url = handler.url;
+                let body = handler.bodyTemplate ?? "";
+                const headers = { ...handler.headers };
+                for (const p of paramDefs) {
+                    const value = params[p.name] ?? "";
+                    url = url.replaceAll(`{{${p.name}}}`, encodeURIComponent(value));
+                    body = body.replaceAll(`{{${p.name}}}`, value);
+                }
+                const safety = await resolveUrlSafety(url);
+                if (safety.blocked) {
+                    return {
+                        ok: false,
+                        output: "Blocked: cannot make requests to internal network addresses",
+                    };
+                }
+                if (!headers["Content-Type"] && body) {
+                    headers["Content-Type"] = "application/json";
+                }
+                const fetchOpts = {
+                    method: handler.method || "GET",
+                    headers,
+                    redirect: "manual",
+                };
+                if (body && handler.method !== "GET" && handler.method !== "HEAD") {
+                    fetchOpts.body = body;
+                }
+                const response = safety.target
+                    ? await fetchWithPinnedTarget(safety.target, fetchOpts, CUSTOM_ACTION_FETCH_TIMEOUT_MS)
+                    : await fetch(url, fetchOpts);
+                if (response.status >= 300 && response.status < 400) {
+                    return {
+                        ok: false,
+                        output: "Blocked: redirects are not allowed for HTTP custom actions",
+                    };
+                }
+                const text = await response.text();
+                return { ok: response.ok, output: text.slice(0, 4000) };
+            };
+        case "shell":
+            return async (params) => {
+                let command = handler.command;
+                for (const p of paramDefs) {
+                    const value = params[p.name] ?? "";
+                    command = command.replaceAll(`{{${p.name}}}`, shellEscape(value));
+                }
+                const response = await fetch(`http://localhost:${API_PORT}/api/terminal/run`, {
+                    method: "POST",
+                    headers: (() => {
+                        const headers = {
+                            "Content-Type": "application/json",
+                        };
+                        const token = process.env.ELIZA_API_TOKEN?.trim();
+                        if (token) {
+                            headers.Authorization = /^Bearer\s+/i.test(token)
+                                ? token
+                                : `Bearer ${token}`;
+                        }
+                        return headers;
+                    })(),
+                    body: JSON.stringify({ command, clientId: "runtime-shell-action" }),
+                });
+                if (!response.ok) {
+                    return {
+                        ok: false,
+                        output: `Terminal request failed: HTTP ${response.status}`,
+                    };
+                }
+                return { ok: true, output: `Executed: ${command}` };
+            };
+        case "code":
+            return async (params) => {
+                const result = await runCodeHandler(handler.code, params);
+                const output = result !== undefined ? String(result) : "Done";
+                return { ok: true, output: output.slice(0, 4000) };
+            };
+        default:
+            return async () => ({ ok: false, output: "Unknown handler type" });
+    }
+}
+function defToAction(def) {
+    const handler = buildHandler(def.handler, def.parameters);
+    return {
+        name: def.name,
+        similes: def.similes ?? [],
+        description: def.description,
+        validate: async () => true,
+        handler: async (_runtime, _message, _state, options) => {
+            try {
+                const opts = options;
+                const params = {};
+                for (const p of def.parameters) {
+                    const value = opts?.parameters?.[p.name];
+                    if (typeof value === "string") {
+                        params[p.name] = value;
+                    }
+                    else if (value !== undefined && value !== null) {
+                        params[p.name] = String(value);
+                    }
+                    else if (p.required) {
+                        return {
+                            text: `Missing required parameter: ${p.name}`,
+                            success: false,
+                        };
+                    }
+                }
+                const result = await handler(params);
+                return {
+                    text: result.output,
+                    success: result.ok,
+                    data: { actionId: def.id, params },
+                };
+            }
+            catch (err) {
+                return {
+                    text: `Action failed: ${err instanceof Error ? err.message : String(err)}`,
+                    success: false,
+                };
+            }
+        },
+        parameters: def.parameters.map((p) => ({
+            name: p.name,
+            description: p.description,
+            required: p.required,
+            schema: { type: "string" },
+        })),
+    };
+}
+export function loadCustomActions() {
+    try {
+        const config = loadElizaConfig();
+        const defs = config.customActions ?? [];
+        return defs.filter((d) => d.enabled).map(defToAction);
+    }
+    catch {
+        return [];
+    }
+}
+export function buildTestHandler(def) {
+    return buildHandler(def.handler, def.parameters);
+}

package/packages/agent/src/runtime/eliza-plugin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Eliza plugin for elizaOS — workspace context, session keys, and agent
+ * lifecycle actions (restart).
+ *
+ * Compaction is handled by core auto-compaction in the recent-messages provider.
+ * Memory search/get actions are superseded by plugin-scratchpad.
+ */
+import type { Plugin } from "@elizaos/core";
+export type ElizaPluginConfig = {
+    workspaceDir?: string;
+    initMaxChars?: number;
+    sessionStorePath?: string;
+    agentId?: string;
+};
+export declare function createElizaPlugin(config?: ElizaPluginConfig): Plugin;
+//# sourceMappingURL=eliza-plugin.d.ts.map

package/packages/agent/src/runtime/eliza-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eliza-plugin.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/eliza-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAEV,MAAM,EAIP,MAAM,eAAe,CAAC;AA6BvB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAoGpE"}

package/packages/agent/src/runtime/eliza-plugin.js

@@ -0,0 +1,108 @@
+/**
+ * Eliza plugin for elizaOS — workspace context, session keys, and agent
+ * lifecycle actions (restart).
+ *
+ * Compaction is handled by core auto-compaction in the recent-messages provider.
+ * Memory search/get actions are superseded by plugin-scratchpad.
+ */
+import { AgentEventService } from "@elizaos/core";
+import { emoteAction } from "../actions/emote";
+import { restartAction } from "../actions/restart";
+import { sendMessageAction } from "../actions/send-message";
+import { goLiveAction, goOfflineAction, manageOverlayWidgetAction, setStreamDestinationAction, speakOnStreamAction, } from "../actions/stream-control";
+import { switchStreamSourceAction } from "../actions/switch-stream-source";
+import { terminalAction } from "../actions/terminal";
+import { adminTrustProvider } from "../providers/admin-trust";
+import { createSessionKeyProvider } from "../providers/session-bridge";
+import { getSessionProviders, resolveDefaultSessionStorePath, } from "../providers/session-utils";
+import { createChannelProfileProvider } from "../providers/simple-mode";
+import { uiCatalogProvider } from "../providers/ui-catalog";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "../providers/workspace";
+import { createWorkspaceProvider } from "../providers/workspace-provider";
+import { createTriggerTaskAction } from "../triggers/action";
+import { registerTriggerTaskWorker } from "../triggers/runtime";
+import { loadCustomActions, setCustomActionsRuntime } from "./custom-actions";
+export function createElizaPlugin(config) {
+    const workspaceDir = config?.workspaceDir ?? DEFAULT_AGENT_WORKSPACE_DIR;
+    const agentId = config?.agentId ?? "main";
+    const sessionStorePath = config?.sessionStorePath ?? resolveDefaultSessionStorePath(agentId);
+    const baseProviders = [
+        createChannelProfileProvider(),
+        createWorkspaceProvider({
+            workspaceDir,
+            maxCharsPerFile: config?.initMaxChars,
+        }),
+        adminTrustProvider,
+        createSessionKeyProvider({ defaultAgentId: agentId }),
+        ...getSessionProviders({ storePath: sessionStorePath }),
+    ];
+    // Emote IDs are now declared as an enum on the PLAY_EMOTE action parameter,
+    // so they appear in the `# Available Actions` section automatically via
+    // core's formatActions. No separate provider injection needed.
+    //
+    // Backwards-compat: character.settings.DISABLE_EMOTES still works — when set,
+    // the PLAY_EMOTE action is excluded at init time so it never appears in the
+    // prompt. Previously this was checked per-request in the emote provider.
+    // Custom actions provider — tells the LLM about available custom actions.
+    const customActionsProvider = {
+        name: "customActions",
+        description: "User-defined custom actions",
+        async get() {
+            const customActions = loadCustomActions();
+            if (customActions.length === 0) {
+                // Don't waste tokens telling the LLM there are no custom actions.
+                return { text: "" };
+            }
+            const lines = customActions.map((a) => {
+                const params = a.parameters
+                    ?.map((p) => `${p.name}${p.required ? " (required)" : ""}`)
+                    .join(", ") || "none";
+                return `- **${a.name}**: ${a.description} [params: ${params}]`;
+            });
+            return {
+                text: [
+                    "## Custom Actions",
+                    "",
+                    "The following custom actions are available:",
+                    ...lines,
+                ].join("\n"),
+            };
+        },
+    };
+    const plugin = {
+        name: "eliza",
+        description: "Eliza workspace context, session keys, and lifecycle actions",
+        services: [AgentEventService],
+        init: async (_pluginConfig, runtime) => {
+            registerTriggerTaskWorker(runtime);
+            setCustomActionsRuntime(runtime);
+            // Honour DISABLE_EMOTES: remove PLAY_EMOTE so it never appears in prompts.
+            if (runtime.character?.settings?.DISABLE_EMOTES) {
+                const idx = plugin.actions?.findIndex((a) => a.name === "PLAY_EMOTE");
+                if (idx != null && idx >= 0) {
+                    plugin.actions?.splice(idx, 1);
+                }
+            }
+        },
+        providers: [
+            ...baseProviders,
+            uiCatalogProvider,
+            customActionsProvider,
+        ],
+        actions: [
+            restartAction,
+            sendMessageAction,
+            terminalAction,
+            createTriggerTaskAction,
+            emoteAction,
+            switchStreamSourceAction,
+            goLiveAction,
+            goOfflineAction,
+            setStreamDestinationAction,
+            speakOnStreamAction,
+            manageOverlayWidgetAction,
+            ...loadCustomActions(),
+        ],
+    };
+    return plugin;
+}